Skip to content
Browse the docs

Accepted2 Nov 2026

0010. One Gradle build at the repository root, one folder per module

View on GitHubReport a problem with this page

Context and Problem Statement#

During the port, Java and Python live side by side. The Java code needs golden files exported from the Python engine, the black-box API tests, the example designs in examples/, and the web app's API client to check its contract against. After the port, Python remains only in the benchmark harness, and only until stage 7 (ADR-0015).

Where should the Java code live?

Considered Options#

  • One Gradle build at the repository root, with one top-level folder per module
  • A separate Gradle build under java/
  • A separate repository

Decision Outcome#

Chosen option: "One Gradle build at the repository root", because:

  • it's where a Java developer looks first;
  • once the Python code is gone, it's an ordinary Java repository with the web app beside it;
  • every shared input (golden files, examples, the web client) stays in the same repository and the same change.
archsim/
  settings.gradle.kts         the build's modules
  gradle/libs.versions.toml   dependency versions (ADR-0006)
  archsim-model/              the design document (ADR-0012)
  archsim-engine/             the simulation engine (ADR-0012)
  archsim-app/                API, workers and migrations (ADR-0014)
  archsim-cli/                the archsim command
  archsim-mcp/                the MCP server
  apps/web/                   the Next.js web app, unchanged
  benchmarks/                 the benchmark harness (Python until stage 7)
  packages/, services/        the Python code, removed stage by stage

Modules are added when a stage needs them. Test-only modules, such as the black-box API tests, sit beside them.

Consequences#

  • Good, because one checkout and one change cover a feature and its parity check.
  • Good, because the layout after the port needs no further move.
  • Bad, because during the port the top level mixes Java module folders with the Python packages/ and services/, which takes a moment to read.
  • Bad, because Gradle and the Python tooling share the root, so each must ignore the other's files and outputs.

More Information#