# ADR 001: Monorepo

- HTML version: https://robbiepalmer.me/projects/personal-site/adrs/001-monorepo
- Project: Personal Site (https://robbiepalmer.me/projects/personal-site.md)
- Status: Accepted
- Date: 2025-10-18

# Context

As the technical scope of my projects grows, I need to manage multiple related concerns: UI code, infrastructure-as-code (Terraform), and shared scripts.
Splitting these into separate repositories would introduce significant friction:

* **Dependency Drift**: Keeping shared tooling (like `mise`) and linting configurations in sync across multiple repos is painful.
* **Complexity**: It requires setting up and maintaining an artifact store (npm/pypi packages) to share code, which adds unnecessary overhead—[Less Is More](/projects?tab=philosophy#less-is-more)—for a personal project where velocity is paramount.
* **Context Switching**: "Agentic" development works best when the AI has the full context of the system available in one place.

# Decision

I decided to adopt a **Monorepo** structure.

This centralizes all code—frontend, infrastructure, and tooling—into a single repository.

# Consequences

### Pros

* **Single Point of Reference**: One place to look for everything. Documentation, code, and infrastructure live side-by-side.
* **Shared Tooling & Standards**: I can enforce common linting, formatting, and `mise` configurations at the root level.
* **Reusable Workflows**: CI/CD workflows and secrets can be defined once and reused across different projects within the repo.
* **Velocity**: Avoids the complexity of versioning and publishing internal packages. I can change a shared utility and update its consumers in a single atomic commit.
* **Agentic Optimization**: AI agents can inspect the entire codebase to understand cross-component dependencies and impact, leading to better code generation and debugging. This supports [LLM-Optimized](/projects?tab=philosophy#llm-optimized) development.

### Cons

* **Build Complexity**: The build pipeline needs to be "smart" enough to only build/deploy what changed (handled via tools like Turbo or simple path filtering).
* **Clone Size**: The repo is larger than a single service repo, but negligible for this scale.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt