---
description: How the codebase is put together — module map, value objects, contracts, orchestrator, storage, the decisions behind them, and how to contribute.
---

# Architecture

These pages are for changing MatMelt rather than using it. They assume you have
read {doc}`../explanation/index`, which covers *why* the design is what it is;
here the subject is *where things are* and *what holds them together*.

```{toctree}
:maxdepth: 1

module-map
value-objects
contracts
orchestrator
state-and-storage
design-decisions
contributing
```

| Page | Covers |
|---|---|
| {doc}`module-map` | Every package and module, and the dependency rule between them |
| {doc}`value-objects` | The frozen dataclasses that travel between layers |
| {doc}`contracts` | The two ABCs, their registries, and what implementing them obliges you to |
| {doc}`orchestrator` | One pass, function by function, and where failure is attributed |
| {doc}`state-and-storage` | The SQLite schema, the workspace on disk, and read-only observers |
| {doc}`design-decisions` | The locked defaults, and the decisions that reversed earlier ones |
| {doc}`contributing` | Dev setup, the check battery, and how to add a stage or backend |

The generated API reference — every module, class and method, from the
docstrings — is {doc}`../api/index`.
