Initial Commit

docs/architecture.md

@@ -0,0 +1,58 @@
+# 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 stages bounded 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. Single-host deployment initially runs one web process; token refresh also uses durable compare-and-swap to prevent a stale refresh from overwriting a rotated token.
+
+## 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.