11For developers

Audience: engineers who'll read or write code. This is the orientation map; the authoritative, always-current source of truth is the repo root CLAUDE.md. When this doc and CLAUDE.md disagree, CLAUDE.md wins.

The architecture in one screen#

A pnpm + Turborepo monorepo. One sentence per layer:

Browser (Next.js + WASM engine) ──▶ Fastify API ──┬──▶ Postgres
                                                   ├──▶ fidelity service (Orekit)
                                                   └──▶ discovery service (TESS/MAST)

The sacred rules (do not violate)#

1. No physics in TypeScript. Ever. The WASM boundary is sacred — the browser renders, the Rust engine computes. (The one carve-out: Deep Field is data analysis over NASA pipeline products, in Python, using astronomy units; the browser still only renders.)
2. Never mix units. SI everywhere (m, s, kg, rad) — except the documented Deep Field astronomy units. No km/m mixing in one calculation.
3. Determinism is law. The engine is golden-bit tested. Don't break bit-reproducibility; rebuild and re-commit the WASM pkg/ after any lib.rs change.
4. Honesty is first-class. Every result carries a fidelity/honesty label, provenance, and (for services) a pipeline/label/credit. This is Constitution Art. XI, never optional.
5. Free academic tier is untouchable. No code or feature may gate .edu / .ac.* users.
6. Never ship code you can't explain.

The full HOUSE PATTERNS list (service shape, API-as-thin-proxy, shared-types contract, TSL-only shaders, cost/test doctrine, comment discipline) is in CLAUDE.md — read it before contributing.

Local setup#

# Node 22 (via nvm) is required
pnpm install

# Build the Rust → WASM engine (after any packages/engine/src/lib.rs change)
cd packages/engine && wasm-pack build --target web --out-dir pkg

# Run everything in dev
pnpm dev

# Type-check / format (run before committing)
pnpm typecheck      # rebuild @deltav/shared first if you touched it
pnpm format

# Rust tests (the engine's truth)
cargo test

# Physics validation harness
node scripts/validate-physics.mjs

Docker (profile-based; local images mirror prod)#

pnpm docker:dev       # Postgres only (schema auto-applied)
pnpm docker:full      # db + discovery + api (prod images; dev flags flipped)
pnpm docker:fidelity  # the Orekit service
pnpm docker:reset     # tear down

Local uses the same prod Dockerfiles Railway deploys, with two bypass flags for dev (ALLOW_DEV_AUTH=1, DB_NO_SSL=1). Env names are identical to prod; only values + those flags differ.

Discovery service (needed for /deep-field)#

cd services/discovery && .venv/bin/uvicorn app.main:app --port 8100
cd services/discovery && .venv/bin/python smoke_test.py   # QUICK: cached, no network

Where things live (quick map)#

• Engine math: packages/engine/src/lib.rs — every pub fn is a WASM export; natively-unconstructible types use *_internal + thin WASM wrappers.
• Domain types & API contracts: packages/shared/src/index.ts (Zod schemas, MissionPackageSchema, discovery schemas).
• Flight Deck UI: apps/web/src/app/deck/page.tsx; rail panels in apps/web/src/components/shell/panels/ (Orbit, Maneuver, Target, FiniteBurn, Track, Vehicle, Access, Coverage, Fidelity); 3D scene in apps/web/src/components/orbit/.
• Marketing/rooms: apps/web/src/app/(marketing)/ (archive, hangar, napkin, deep-field, loop, m, u, contact, docs).
• Presets & catalogs: apps/web/src/missions/ (presets, stations, constellations, vehicles, engines, deepfield-targets, apolloMission).
• Canonical mission format: missions/apollo-11/mission.yaml (.dvmission YAML; schema in packages/shared).
• API routes: apps/api/src/routes/ (propagate, tle, discovery, feedback, missions/community).
• Notes (append-only learning log): notes/YYYY-MM-DD-HHMM-topic.md — write one per session (see notes/README.md).
• Program docs: docs/reviews/ (phase deliverables + the war plan), docs/implementation/, docs/system-truth/.

Conventions that bite if ignored#

• Rebuild & commit packages/engine/pkg/ after engine changes — CI validates the committed WASM (the deployed bits). ENGINE_PREBUILT=1 lets the TS jobs skip the Rust build by downloading the wasm-pkg artifact.
• Rebuild @deltav/shared before typechecking the API.
• Shaders are TSL-only for the WebGPU scene (compiles to WGSL and GLSL — no raw GLSL). The star map deliberately uses shaderless built-in materials + procedural CanvasTextures.
• Cost/test doctrine (PROMPTS.md §7): expensive/network checks are phase-exit gates, never per-edit; one browser verification at the end. Heavy Python imports (lightkurve, astropy, sklearn) stay lazy inside functions so /health is instant.
• notes/ is excluded from Prettier (append-only audit prose). Run pnpm format, lint, and typecheck before committing.
• Branches: active work is on develop-2 (the Opus implementation track); develop/main are reserved. CI runs on all four.

The contribution loop (typical brick)#

1. Add the math to packages/engine/src/lib.rs + cargo test (and golden bits if needed).
2. Rebuild WASM, commit pkg/.
3. Add the shared Zod schema / TS types in packages/shared (if it crosses the wire).
4. Build the UI panel that marshals inputs → engine call → render (no physics in TS).
5. If a service is involved: engine module + pydantic models + a smoke test; thin API proxy with the honest 400/404/502/503 taxonomy.
6. One browser verification at the end; write a notes/ entry.
7. pnpm format && pnpm typecheck && cargo test.

Read these before touching core code#

• CLAUDE.md — the living context & house patterns (start here)
• packages/engine/src/lib.rs — the physics engine
• packages/shared/src/index.ts — all domain types
• missions/apollo-11/mission.yaml — canonical mission format
• VISION.md, ARCHITECTURE.md, TECHNICAL_BIBLE.md, CONSTITUTION.md
• docs/reviews/sovereignty-program-war-plan-2026-06-11.md — the S0–S7 plan