1. Monorepo

Status

Accepted

Date

2026-03-23

Context

The project is an open-source project consisting of multiple components. The maintenance overhead should be kept as low as possible. A repository strategy that serves this goal needs to be established.

Decision

We use a monorepo. All components of the system live in a single repository.

Monorepo Structure

.github/
└── workflows/
docs/
├── Architecture/
└── ADRs/
keycloak/
├── Dockerfile
└── realms/
frontend/
backend/
CONTRIBUTING.md
VERSIONING.md
README.md

Rationale

  • Small team: A single repository reduces coordination overhead and avoids maintaining multiple repositories.

  • Minimal maintenance: CI/CD workflows, linting, and dependencies are managed centrally in one place.

  • Open source: Contributors find everything in one place, which lowers the barrier to entry.

  • Cross-component changes can be implemented in a single commit and pull request.

Considered Alternatives

Multi-Repository

Each component in its own repository.

  • Pros

    • Clear separation

    • Independent development cycles

  • Cons

    • High maintenance overhead

    • Complex coordination for cross-component changes

    • Multiple pull requests for a single logical change

    • Manual version pinning across repositories

Hybrid

Frontend and backend in one repository, Keycloak separate.

  • Pros

    • Flexibility

  • Cons

    • Higher maintenance overhead than monorepo

    • Inconsistent processes across repositories

    • Additional complexity without a clear benefit

Consequences

  • Unified toolchain and development environment for all components

  • Simpler refactoring across component boundaries

  • Centralized documentation

  • Conditional CI/CD pipelines required to avoid unnecessary builds when only one component changes