| # 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/`. |
|
|
