eden/docs/research/platform.md

Platform evidence

Checked 2026-09-18 against live official documentation. Raw working copies are in ignored .firecrawl/.

Convex

• Self hosting and official deployment guide: backend defaults to SQLite; no PostgreSQL/Redis is necessary. Backend API uses 3210, HTTP actions 3211, dashboard 6791. Persistent /convex/data is essential. Generate a deployment admin key with ./generate_admin_key.sh; CLI uses CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY, not cloud project login. Admin key is deployment-only, never a browser environment value.
• Official Compose: health probe /version; backend SIGINT shutdown; distinct cloud/site origins. Upstream example uses latest; operators should pin tested image digests and back up before upgrades.
• Svelte quickstart, Svelte overview: use the actual convex-svelte package, Svelte 5; put Convex functions in src/convex via convex.json. Root setupConvex(url); declarative useQuery(api.function, () => args) for subscriptions. Keep domain calculations in Bun server services, not separate browser/Convex copies.
• Custom JWT: supports RS256/ES256, kid/alg/typ, sub/iss/exp and client refresh iat. Enforce application audience. JWKS may be a data URI, avoiding a boot-time callback from Convex to the web container. This permits an EVE-login-backed application identity without handing EVE tokens to the browser. An application JWT is NOT an EVE access token.

Bun

• SQLite: synchronous bun:sqlite driver; parameterized prepared statements, transactions, read-only connections, strict bindings, integrity pragmas. SQLite integers are 64-bit but JS numbers only exact through 2^53−1: external EVE instance/location IDs should be decimal strings at domain boundaries. Reference type/system IDs fit safe integers and are validated.
• Transactions must contain synchronous writes, not awaited parsing/downloads. Immutable artifact compiler can use DELETE journaling to avoid promoting a DB without a WAL sidecar. Complete/close staging file before publishing its manifest. Serving uses read-only handles to a version, not an in-place changing database.
• Local available runtime: Bun 1.3.14. Live docs advertise a newer release; use only APIs verified by repository tests on 1.3.14 and explicitly pin the tested runtime in deployment.

Evidence caveat

Documentation evolves. URLs above are live sources, not promises of permanent API compatibility. Dependency lockfile, ESI contract evidence and offline regression tests capture the implemented contract. Deployment and live-auth testing need separately configured services/credentials.