Architecture
The system's technical shape and boundaries.
Architecture tree
Start with the conceptual model, then descend only into the runtime concern you are changing.
The architecture is the authored work of Jason Yu (jasonyu0100). Its contracts establish the
instrument; they do not claim authorship over runtime-generated Domain content or the actions of its
operators. See Authorship and provenance.
- What must stay true across the system? Architecture overview.
- How does the World vision map onto stable engine boundaries? World engine direction.
- How does state persist and reach other clients? Persistence and sync.
- Which runtime relationships should I see before changing a surface? System connections.
Architecture
├── overview/
│ ├── foundations one app · one writer · canonical record
│ ├── authority record and runtime authority
│ ├── one-writer action path end to end
│ ├── runtime-roles core · engine · server · client
│ └── glossary precise runtime terms
├── persistence/
│ ├── record-and-write-path
│ ├── cache-and-reconciliation
│ ├── sync-foundations
│ ├── replication
│ ├── client-and-edge-cases
│ └── research-and-scaling
├── [World engine direction](WORLD_ENGINE.md) future instance · context · clock · information boundaries
├── [Structure](STRUCTURE.md) file placement and import constraints
└── [API principles](API_PRINCIPLES.md) reducer/API constitution
For a code change, begin with the smallest matching leaf. The generated file map reports what exists; it does not replace the architectural contract.
Overview
7 articles- 2. Sources of truth — the exact wordsPublic
Two orthogonal axes. Don't conflate them.
- 3. The write path (follow one action end to end)Public
This is the whole backend in one diagram. A renderer edits a scene:
- 4. The layer map — src/lib/ is role-firstPublic
src/lib/ is organised into four role buckets , so "is this browser safe? does it serve the record?" is answered by the path. Import as @/lib/<role /<folder . The UI above it has its own three tier stack (shell → features → ui); both stacks and the lint enforced import matrix are owned by...
- 5. How the restructure was done (and the one thing left)Public
The role first layout above was migrated mechanically, lowest blast radius first, verifying tsc (module resolution) + the full suite after each move: server/ (ops·record·sync) → engine/ (ai·prompts·extraction·research) → core/ (all pure derivations + the reducer, split out of the old state/) →...
- 6. Glossary — the words that trip people upPublic
| Term | Precise meaning | | | | | the record | the canonical on disk store (.meridians local/record/). The source of truth. | | projection / cache | IndexedDB — a rebuildable view of the record. Never authoritative. | | master | the sovereign instance that owns its record (localhost / Electron...
- 7. Where to read nextPublic
The reducer + the tiers, in depth → API PRINCIPLES.md, MCP manual The store linkage (record↔cache) + the sync / master client / tunnel layer → PERSISTENCE.md Where a file goes + what it may import → STRUCTURE.md UI component naming → FRONTEND CONVENTION.md · Domain vocabulary → LANGUAGE.md The...
- Architecture — runtime boundaries, canonical state, and the one-writer modelPublic
Who this is for. A developer used to a backend/frontend split landing in this repo and asking "where's the server, where's the client, where's the database, and why is it shaped like this?" This is the map. It complements — doesn't replace — the specialized docs: API PRINCIPLES.md (the reducer +...
Persistence
7 articles- 11. Replication modelPublic
Reads — local first Every node hydrates from its own IndexedDB and renders locally (Part A); the dashboard list and the open domain come from the local replica. Opening a domain the replica lacks issues a request; the master answers with the canonical doc.
- 14. Domain categories — src/lib/client/store/store.tsxPublic
Three sets, exported for UI differentiation:
- 19. Outbound research, monitoring & the Sources repoPublic
The research/forecast spine adds an outbound dimension the collaboration model above doesn't otherwise touch — the app reaches the open web (via Firecrawl) and the LLM on the Director's keys. How it fits the single instance design:
- 3. Documents — daemon-first, then echoed to the cachePublic
Documents (domains, constellations, extractions, …) are the only shape written daemon first : the record is updated and versioned before the cache, so canon is never behind the projection.
- 6. Goal & constraintsPublic
One world, many people. A Director runs Meridians locally; teammates/admins reach the same instance over an ngrok tunnel and work together in real time. Sovereign / local first. No cloud backend. The Director's machine is the system of record (Part A): the record on disk is canon; the only...
- Legacy lifecycle — how compatibility enters, rolls through the fleet, and leavesPublic
Scope. This doc owns the management of legacy: the principles under which a historical shape may be tolerated, the one place every tolerated shape is listed, the mechanism that upgrades tenants so the tolerance can end, and the enforcement that makes it end on a date. The migration boundary...
- Persistence — where state lives and how it propagatesPublic
Scope. This doc owns how state is stored and kept in agreement across the two stores and the two instance roles. It has two halves: Part A — the store linkage (§1–§5): the on disk record (canon) and the browser IndexedDB (a rebuildable projection), and the exact machinery that keeps them in...
Root
5 articles- API & State Principles — the grounded vocabulary and handling rulesPublic
Why this doc. The generated MCP manual is the catalog (which calls exist — every read, op, action, route + the affordance graph, generated). This is the constitution (why they're shaped this way, what the words mean, how to handle them). It changes rarely, so it's hand maintained — the catalog...
- ArchitecturePublic
The architecture contract is split into topical leaves. Begin with the architecture tree, then read the smallest matching overview or persistence leaf.
- STRUCTURE — how the codebase is organized (agent-first)Public
Read this before adding or moving a file. It is the mechanical answer to two questions an implementer (human or agent) asks constantly: "where does this go?" and "what may it import?" The rules here are enforced by lint (eslint.config.mjs) and surfaced in the generated map (knowledge...
- System Connections — runtime and surface wiring mapPublic
The map lives under diagrams/, one single purpose file per topic, split into three tracks — [Concept] (what the system is), [Flow] (how work moves), [UI] (what you see). Read the index at diagrams/README.md and pick the diagram you need.
- World engine direction — stable boundaries for branch-derived WorldsPublic
Status: architecture direction, not an implementation contract. The World concept contract owns the product concept. Current runtime truth remains in the code, Architecture, API principles, Persistence, and the generated MCP manual.