ADR-0004: Use a monorepo for core infrastructure¶

Status¶

Accepted

Context¶

The Jersal organization needs to manage shared infrastructure (Terraform), a portfolio website (Vite), and a documentation hub (MkDocs). These components could be organized as:

Monorepo -- All components in jersal-projects-core
Polyrepo -- Separate repositories for infra, portfolio site, and docs hub

Decision¶

Use a monorepo (jersal-projects-core) to house shared infrastructure, the portfolio site, and the documentation hub.

Repository structure:

jersal-projects-core/
├── terraform/     # Shared infrastructure
├── site/app/      # Portfolio website
├── hub/           # Documentation hub
└── .github/       # CI/CD workflows for all components

Each component has independent CI/CD workflows that trigger only when their respective directories change (path filters in GitHub Actions).

Consequences¶

Positive¶

Single source of truth -- All foundational components are in one place. No need to coordinate across repos for shared concerns.
Atomic changes -- Infrastructure changes and documentation updates can be made in the same PR.
Simplified CI/CD -- One set of GitHub secrets and variables serves all workflows. OIDC federated credentials are configured once.
Shared context -- Documentation can reference infrastructure code directly. Contributors see the full picture.

Negative¶

Larger repository -- More files and directories than a focused single-purpose repo. Navigation requires understanding the layout.
Mixed concerns -- A Vite site, Terraform configs, and MkDocs content in the same repo may feel unusual to contributors expecting a single-purpose repo.
CI complexity -- Path filters must be carefully maintained to avoid triggering unrelated workflows.

Neutral¶

Individual projects remain in their own repositories. Only shared/foundational components live in core.
The monorepo pattern is well-established in the industry (Google, Meta, Microsoft all use monorepos at scale, though at a different magnitude).