Skip to main content

ADR-0002: One repository, independent build projects, no parent POM

Status: Accepted (retroactive) Date: 2026-07-24

Context​

The repository holds several codebases with very different lifecycles:

  • backend/ — the Spring Boot 4 payroll API (Maven);
  • frontend/ — the React/Vite app (npm);
  • the Playwright e2e suite at the repo root (package.json, playwright.config.ts);
  • the legacy JavaFX desktop app's root pom.xml (MySQL/Hibernate/JavaFX dependencies, kept for history — its src/ is gone);
  • MotorPH Event-Driven Inventory System/ — three Spring Boot microservices + RabbitMQ, each with its own POM, eventually replacing the in-monolith warehouse module. It lives on the feature/MotorPHEnterpriseInventorySystem branch rather than main.

The choice was between wiring these into one build (Maven multi-module parent, npm workspaces) or keeping one repo of independent projects that only share git history, docs, and CI.

Decision​

One monorepo, no parent POM and no workspace root. Each project declares its own dependencies and builds in isolation:

  • backend/pom.xml and each inventory service POM inherit directly from spring-boot-starter-parent — nothing in this repo aggregates them.
  • frontend/package.json and the root e2e package.json are unrelated npm projects with separate lockfiles.
  • CI reflects this explicitly: codeql.yml runs a matrix of four separate Maven builds (mvn -f "<path>/pom.xml"), with an in-file comment noting that "four independent Maven projects, no parent POM" is why autobuild can't discover them from one root.
  • Shared context lives in docs/ and the compose files, not in build tooling.

Consequences​

Positive

  • Projects upgrade independently — the monolith moved to Spring Boot 4.0.7 without touching the inventory services, and frontend dependency bumps never invalidate a backend build.
  • New contributors can build the one project they work on (mvn -f backend/pom.xml, npm --prefix frontend) without understanding the rest.
  • The legacy POM and the future microservices coexist with the shipping product without any aggregator gymnastics.

Negative

  • Dependency-version drift is possible and unpoliced. The backend and the three inventory services each pin their own Spring Boot version; nothing fails if they diverge.
  • No atomic cross-project version enforcement — there is no single command that builds "the whole repo", and no mechanism to keep, e.g., shared DTO shapes in sync between monolith and microservices except discipline.
  • The root pom.xml is a trap for newcomers: mvn at the repo root builds the dead JavaFX project, not the product. The real backend is backend/pom.xml; this is only discoverable from docs.
  • Every new Java project must be manually added to the CodeQL matrix or it is silently unscanned.

References​