# Architecture

A modular monolith with internal service boundaries that map one-to-one to the spec's layers (section 4).
Scientific computation, orchestration, evidence grading and UI are separate packages. Agents reach everything
through typed tools (`agents/tools.py`) and never through solver internals or the filesystem.

| Spec layer | Package(s) | Key entry points |
|---|---|---|
| Experience | `apps/dashboard`, `visualization/` | dashboard `index.html`, `viewer.js`, `visualization/viewer.structure_payload` |
| API/application | `apps/api.py`, `matter_os/app.py` | `create_app()`, `MatterOS` container (Project API) |
| Orchestration | `orchestration/` | `MissionOrchestrator`, `JobRunner`, `ResourceManager`, `scheduler.execute`, `failures.classify` |
| Agent runtime | `agents/` | `AgentRuntime`, `ResearchCoordinator`, 12 specialists, `DynamicAgent`, `MessageBus`, `debate.resolve` |
| Scientific core | `core/`, `discovery/` | `MatterStructure`, `ConstraintSet`, transformations, generators, searches, Pareto, active learning |
| Simulation adapters | `simulation/` | `SolverAdapter` contract, `MethodRegistry`, `SimulationRouter`, `SimulationService`, benchmarks |
| Knowledge | `knowledge/` | `KnowledgeGraph`, governance rules, provenance registry, ingestion connectors |
| Infrastructure | `storage/`, `orchestration/jobs.py` | SQLite `Database` (+migrations, immutability triggers), `ArtifactStore`, archives/snapshots |

## End-to-end flow (one mission)
`mission -> hypotheses -> design -> screening -> method_selection -> execution -> analysis -> learning -> replication -> novelty -> evidence_grading -> knowledge_update -> next_action`

The coordinator routes each stage to its agent with a `TaskContract`. The result is validated against the StageResult
schema, posted as a structured message and persisted into the mission checkpoint, so a crash resumes at the next stage.

## Data stores (SQLite, `var/matter_os.sqlite3`)
`projects, missions, candidates (+candidate_versions), run_records (immutable), claims (+claim_versions), jobs,
kg_entities, kg_edges, kg_events (append-only), audit_log (append-only), agent_memory, messages, artifacts,
data_sources, failures, strategy_stats, agent_evaluations, improvements, metrics, schema_migrations`.
Artifacts are content-addressed files under `var/artifacts/<sha[:2]>/<sha>/<name>`, each with an HMAC signature row.

## Execution isolation
`JobRunner` forks one worker per job (`multiprocessing` "fork" context). The worker sets RLIMIT_CPU and thread caps,
runs in `var/jobs/<job_id>/`, and returns a pickled `SolverOutput`. The parent enforces wall time, a resident-RAM
watchdog (USS sampled every 0.5 s) and cancellation (cooperative flag file, then terminate). Checkpoints are ASE
trajectories, and resume continues from the last frame.

## Decisions recorded as ADRs
See `docs/decisions/`.