Architecture — milestone 1

User decisions: assets + estimated valuation; first EVE login creates the app user; single-host Compose. See milestone.md for acceptance and explicit non-goals; research/ for live official-source evidence.

Svelte 5 chat / assets / characters
  │ same-origin SvelteKit API (opaque HttpOnly session)
  ├─ convex-svelte subscription: safe character + synchronization state
  ▼
Bun application services
  ├─ typed intent router (JEV Choice, or explicit /assets and /value commands)
  ├─ deterministic capability/ownership gates
  ├─ shared AssetService / reference valuation
  ├─ Convex repository ── user state, encrypted tokens, snapshot chunks, executions
  ├─ centralized ESI transport ── conditional cache / retry / pagination
  └─ read-only ReferenceRepository ── ACTIVE immutable bun:sqlite artifact

Dedicated Bun reference worker
  source adapters → normalized rows → STAGING database → validation
      → versioned artifact → atomic manifest {ACTIVE, PREVIOUS, generation}

Boundaries

src/lib/domain is independent of Svelte, Convex, ESI, SQLite and JEV. Characters/assets belong to an application user. Reference IDs, item names, normalized blueprint relationships and XYZ live in reference SQLite. Mutable ownership, snapshots and assistant executions live in Convex. Market estimates use a separate provider port and never enter the immutable reference DB.

src/lib/server is server-only by SvelteKit convention. No EVE tokens or bridge secret may be imported into client modules. Convex public queries expose explicit safe projections. Privileged bridge functions authenticate a dedicated server-only service secret (not the deployment admin key). User-facing queries authenticate an application JWT with issuer/audience and check session revocation plus user ownership.

Authentication and synchronization

EVE authorization-code + PKCE and encrypted token storage runs in Bun. First login creates an app user keyed to a verified character and owner claim; explicit linking attaches additional characters to the current user. Conflicting ownership never silently merges accounts. Session cookies carry random opaque values; only hashes are stored. Application RS256 JWTs are short-lived and audience-scoped for the Convex browser client. EVE access/refresh tokens are never browser credentials.

Asset sync is a durable asset_sync job owned by the authenticated user; /api/sync only enqueues a server-derived, deduplicated request. A dedicated Bun worker claims bounded due work with renewable tokenized leases, stages validated chunks, then atomically changes a character's active generation after all pages succeed. A failed fetch preserves the previous complete generation. Sync metadata records freshness/error, and the domain gate refuses to present missing/stale coverage as complete. ESI page caches are isolated by authorization identity; no partial paginated result is accepted as a full snapshot. Cooldowns are persisted in Convex and shared by workers. Token refresh is coordinated by a durable per-character lease and compare-and-swap; uncertain rotating-token results fail closed as reconnect_required instead of replaying a refresh. The worker receives no application signing, JEV, reference, or deployment-admin secrets. This is a local T07 prototype; it requires CONVEX_SYNC_WORKER_SECRET and the explicit worker-scoped startup path. T08 location/containment enrichment remains feature-local, with integration at the post-assets/pre-publication seam still pending.

Valuation

Only reference_estimate is executable now. ESI average prices are estimates, not Jita bids, asks, replacement quotes or liquidation proceeds. Exact accumulation uses integer hundredths of ISK serialized as strings. ESI average unit prices are rounded half-up to 0.01 ISK before quantity multiplication; this deliberately bounded precision is part of the estimate policy, not a claim of exact market execution. Large stacks can magnify sub-cent rounding, so higher-precision reference estimates are a future refinement. Missing/unpriceable items are excluded and counted, never silently zeroed. Prices, assets and reference version carry provenance/freshness. Blueprint-copy valuation is deliberately excluded.

Future order books, depth walking, fees/taxes and location/range matching belong behind OrderBook; immediate liquidation cannot be implemented by multiplying the best bid. Industry contracts separate additional cash needed from owned-material opportunity value and economic profit.

Reference lifecycle

The reference worker owns archive work. Source metadata/fingerprints and import status are independent for Reference Data, Hoboleaks, and the CCP SDE universe complement. CCP records are translated into the existing ESI-shaped universe contract (the compatibility source key remains esi-universe). A failed source may retain its verified last successful input while another advances; cross-source validation still gates the resulting database. Explicit production adapters stream/validate archive members and compile real releases, while tiny fixtures continue to exercise offline promotion/rollback. Archive bytes and canonical source payloads have separate hashes; immutable source caches bind provenance to the active artifact. Version identity is the downstream cache key; readers select one version for a request and never mix tables across artifacts. Live readers reject fixture-profile artifacts.

Development deployment and secrets

The configured development deployment uses Infisical startup injection, not runtime vault requests per user operation. A host-side read-only machine identity fetches allowlisted app secrets; its bootstrap credentials/token never reach the web container. CLI-only Convex administration can derive its key locally from the persistent backend for explicit deployment commands. The browser uses the public HTTPS Convex hostname; internal server traffic stays on the Compose network. Pangolin supplies public TLS/HTTP routing and WebSocket upgrades. See live-setup.md for exact origins, ports, and operator boundaries.

Future domain contracts

universe/routing: normalized systems, finite XYZ, stargate edges; exact EVE light-year constant 9,460,000,000,000,000 metres; future capital search uses ship/skill/eligibility and weighted constraints.
structures: separate visibility from docking permission; timestamped evidence and explicit unknown/allowed/denied with limitations. Live route findings are in research/eve.md.
blueprints/industry: normalized activities/materials/products; deterministic quantities/time/economics, candidate generation before any semantic ranking.
assistant: narrow semantic judgments only; deterministic allowlisted dispatch, capability gates, structured connect/sync/clarify/unavailable results. A missing JEV key does not silently simulate natural-language understanding.

Scaling gate, not premature infrastructure

No Redis, PostgreSQL, search service or market analytics database is introduced. Convex stores bounded snapshot chunks; the live market provider is replaceable. The reviewed full archives have been validated, but projection/cache construction still materializes bounded source maps in memory. Before larger deployments: benchmark transaction/import limits, improve row-level streaming where needed, implement retention/GC and durable job recovery, and validate future release formats rather than assuming compatibility.

7.4 KiB Raw Blame History