Architecture Decision Records
An Architecture Decision Record (ADR) is a short document that records one significant decision: the problem, the options considered, the option chosen and why, and what follows from it. ArchSim's ADRs use the MADR 4 format. Read them in order to see why the project looks the way it does.
When to write one#
Write an ADR when a decision:
- is hard or costly to reverse (a language, framework, database or module boundary);
- changes a contract other parts rely on (the design document, the HTTP API, the result digests);
- chooses between real alternatives that a later contributor might reasonably reopen;
- changes how ArchSim's accuracy is measured or judged.
Routine choices that follow existing conventions (a library update, a new endpoint in an existing feature) don't need one.
How to add one#
- Copy
template.mdtoNNNN-short-kebab-title.md, using the next free number. - Fill it in with
status: proposedwhile it's being discussed. Keep it to about one screen. - Put it in the same change as the work it governs, so the code and its reasons land together.
- Once the owner accepts it, set
status: acceptedand the date, and add a row to the index below.
Accepted ADRs are not rewritten. Typos and broken links may be fixed. To change a decision, write
a new ADR and mark the old one superseded by ADR-NNNN.
Status lifecycle#
proposed ──► accepted ──► superseded by ADR-NNNN
│ └──────► deprecated (no longer applies, nothing replaces it)
└──► rejected
ADRs 0002 to 0004 record decisions made before ADRs were adopted. They say so, and they state only what the repository shows.
Index#
| ADR | Title | Status | Date |
|---|---|---|---|
| 0001 | Record architecture decisions | Accepted | 2026-11-02 |
| 0002 | The versioned design document is the contract between web app, API and engine | Accepted | 2026-10-24 |
| 0003 | Run simulations from a PostgreSQL queue with leases | Accepted | 2026-10-27 |
| 0004 | Prove accuracy on held-out experiments, sealed until a frozen engine predicts them | Accepted | 2026-10-30 |
| 0005 | Port ArchSim to Java 25 in stages | Accepted | 2026-11-02 |
| 0006 | Build with Gradle, Kotlin DSL and a version catalog | Accepted | 2026-11-02 |
| 0007 | Use Spring Boot 4 for the application | Accepted | 2026-11-02 |
| 0008 | Access PostgreSQL through JdbcClient, with Flyway migrations |
Accepted | 2026-11-02 |
| 0009 | Use io.archsim as the base package |
Accepted | 2026-11-02 |
| 0010 | One Gradle build at the repository root, one folder per module | Accepted | 2026-11-02 |
| 0011 | Organise the application's code by feature | Accepted | 2026-11-02 |
| 0012 | Separate the design model from the simulation engine | Accepted | 2026-11-02 |
| 0013 | An event-driven simulation kernel | Accepted | 2026-11-02 |
| 0014 | One deployable application, started as api, worker or migrate |
Accepted | 2026-11-02 |
| 0015 | Keep the benchmark harness in Python until the port is complete | Accepted | 2026-11-02 |
| 0016 | Drop the SQLite development mode | Accepted | 2026-11-02 |
| 0017 | Freeze the Python engine during the port; run the held-out campaign before stage 4 | Accepted | 2026-11-02 |
| 0018 | Judge p95 within a factor of two either way | Accepted | 2026-11-02 |
| 0019 | Black-box API tests in Java, run against any base URL | Accepted | 2026-11-05 |
| 0020 | Record the frozen engine's deterministic functions as golden files | Accepted | 2026-11-05 |
| 0021 | Java build conventions: one convention plugin, warnings as errors, JUnit 6 | Accepted | 2026-11-05 |
| 0022 | Map the design document with records and a pydantic-compatible codec over Jackson trees | Accepted | 2026-11-05 |
| 0023 | Upgrade older documents with a chain of steps on the JSON, and model only the current schema | Accepted | 2026-11-05 |
| 0024 | Report what is wrong with a design as issues with stable codes and the Python engine's words | Accepted | 2026-11-05 |
| 0025 | Generate the design document's JSON Schema from the records, as pydantic writes it | Accepted | 2026-11-05 |
| 0026 | Component specifications and the price-snapshot lookup belong to the model | Accepted | 2026-11-05 |
| 0027 | Reproduce Python's text conventions for numbers and values in one package | Accepted | 2026-11-05 |
| 0028 | Read the golden files with a reader shared as Gradle test fixtures | Accepted | 2026-11-05 |
| 0029 | Build the model's packages in layers, one direction only, checked by ArchUnit | Accepted | 2026-11-05 |
| 0030 | Write Java in Spring Framework's style, with clean-code rules the build enforces | Accepted | 2026-11-05 |
| 0031 | Build the component catalog from the specifications, with its presentation as data | Accepted | 2026-11-05 |
| 0032 | Flyway takes over from Alembic at revision 0008, proven by a schema snapshot | Accepted | 2026-11-05 |
| 0033 | Run the database tests on an embedded PostgreSQL, without Docker | Accepted | 2026-11-05 |
| 0034 | Keep the FastAPI API's HTTP contract in Spring MVC | Accepted | 2026-11-05 |
| 0035 | Read the Python API's ARCHSIM_* settings unchanged |
Accepted | 2026-11-05 |
| 0036 | Run the engine's synchronous calls in a small internal Python service | Accepted | 2026-11-05 |
| 0037 | Sign people in with plain Spring MVC, not Spring Security | Superseded by 0065 | 2026-11-05 |
| 0038 | The engine computes on the model's records and typed configs, not on JSON trees | Accepted | 2026-11-05 |
| 0039 | The engine reads a run's report as records of the parts it reads | Accepted | 2026-11-05 |
| 0040 | A run comparison copies the report parts it shows and diffs the simulated inputs as stored | Accepted | 2026-11-06 |
| 0041 | The application's clock never tells the same microsecond twice | Accepted | 2026-11-06 |
| 0042 | Exports read settings leniently and write their own YAML | Accepted | 2026-11-06 |
| 0043 | Read imported YAML with SnakeYAML, resolved as PyYAML resolves it | Accepted | 2026-11-06 |
| 0044 | Read Terraform JSON with Jackson, as Python's json reads it | Accepted | 2026-11-06 |
| 0045 | Replay calibrations through an interim /simulate on the engine service |
Accepted | 2026-11-07 |
| 0046 | Call Prometheus with Apache HttpClient 5, pinned to the address it checks | Accepted | 2026-11-07 |
| 0047 | Draw the Python engine's random streams in Java | Accepted | 2026-11-08 |
| 0048 | Keep SimPy's order of events in the Java kernel | Accepted | 2026-11-08 |
| 0049 | Measure the Java simulator by replaying the frozen engine's runs | Accepted | 2026-11-08 |
| 0050 | One report per seed on every platform, with the Python engine's digest definitions | Accepted | 2026-11-08 |
| 0051 | Start the Java CLI in stage 4 with archsim run |
Accepted | 2026-11-09 |
| 0052 | Record the frozen engine's simulation baselines once, and judge the Java simulator by them | Accepted | 2026-11-09 |
| 0053 | Simulate runs in the Java app's worker role, one thread per run | Accepted | 2026-11-09 |
| 0054 | Replay calibrations on a pool of platform threads, never on the request's thread | Accepted | 2026-11-09 |
| 0055 | The Java CLI keeps the Python CLI's words, exit codes and JSON values | Accepted | 2026-11-10 |
| 0056 | The Java CLI takes options by their full names | Accepted | 2026-11-10 |
| 0057 | Move the Prometheus client into the engine, for the app and the CLI | Accepted | 2026-11-10 |
| 0058 | Serve ArchSim's MCP tools with the official MCP Java SDK | Accepted | 2026-11-11 |
| 0059 | Read files as Python did in the engine, for the CLI and the MCP server | Accepted | 2026-11-11 |
| 0060 | Run the archsim-check action's CLI in an image the job builds | Accepted | 2026-11-11 |
| 0061 | Answer the benchmark harness's engine calls from one Java process | Superseded by 0073 | 2026-11-11 |
| 0062 | Make the Java engine the benchmark harness's default | Accepted | 2026-11-11 |
| 0063 | Retire Alembic: a database below revision 0008 upgrades first from the tag alembic-0008 |
Accepted | 2026-11-12 |
| 0064 | Keep Python only for the benchmark harness and the repository's tooling, until stage 7 | Accepted | 2026-11-12 |
| 0065 | Move sign-in to Spring Security after the port, keeping its HTTP contract | Accepted | 2026-11-12 |
| 0066 | Ship the web image without Next.js's image optimizer, and so without sharp and libvips | Accepted | 2026-11-12 |
| 0067 | License ArchSim under the AGPL-3.0, and offer a commercial license | Accepted | 2026-11-13 |
| 0068 | Port the benchmark harness to its own module, archsim-benchmarks, which calls the engine in process |
Accepted | 2026-11-13 |
| 0069 | Run the harness from Gradle, as picocli commands named as run.py named them |
Accepted | 2026-11-13 |
| 0070 | Write the harness's files as the Python harness wrote them, byte for byte | Accepted | 2026-11-13 |
| 0071 | Reduce the results with Python's statistics, ported exactly | Accepted | 2026-11-13 |
| 0072 | Move the repository's tooling to Java, and retire the recorders of CPython's behaviour | Accepted | 2026-11-13 |
| 0073 | Remove archsim functions with the Python harness |
Accepted | 2026-11-14 |
| 0074 | Bill a workload's peak for the hours a month it lasts, and autoscaled parts at the count they settle at | Accepted | 2026-11-14 |
| 0075 | Ask outside contributors to sign a contributor license agreement on their pull request, AI-assisted work included | Proposed | 2026-11-15 |
| 0076 | Version ArchSim as a product, apart from its engine, in gradle.properties |
Accepted | 2026-11-15 |
| 0077 | Publish release images to GHCR, and run them from docker-compose.yml |
Accepted | 2026-11-15 |
| 0078 | Build archsim.io as a static export of the web app, from the repository's own docs | Accepted | 2026-11-15 |
| 0079 | Let visitors try ArchSim in a sandbox for a day, without signing in | Accepted | 2026-11-16 |
| 0080 | Host a public server from a Compose kit in deploy/, behind Caddy or a Cloudflare Tunnel |
Accepted | 2026-11-16 |