Skip to content
Browse the docs

Architecture Decision Records

View on GitHubReport a problem with this page

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#

  1. Copy template.md to NNNN-short-kebab-title.md, using the next free number.
  2. Fill it in with status: proposed while it's being discussed. Keep it to about one screen.
  3. Put it in the same change as the work it governs, so the code and its reasons land together.
  4. Once the owner accepts it, set status: accepted and 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