Architecture Decisions
Architecture Decision Records
Index of architectural decisions made in the HanseNexus monorepo
What are ADRs?
Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions made in the project, along with their context and consequences. They help:
- Document why decisions were made — not just what, but why
- Provide context for future maintainers — understand the reasoning behind choices
- Track architectural evolution — see how and why the architecture changed over time
- Facilitate onboarding — new team members can quickly understand key decisions
We use the MADR (Markdown Architectural Decision Records) format, which is lightweight, readable, and version-controlled alongside the code.
Index of ADRs
| Number | Title | Status | Date |
|---|---|---|---|
| 0001 | Turborepo Monorepo Structure | Accepted | 2025-02-03 |
| 0002 | Convex as Backend Platform | Accepted | 2025-02-03 |
| 0003 | Shared Package Strategy | Accepted | 2025-02-03 |
| 0004 | Bun as Package Manager | Accepted | 2025-02-03 |
| 0005 | Tailwind CSS v4 Adoption | Accepted | 2025-02-03 |
| 0006 | Next.js 16 Proxy Migration | Accepted | 2025-03 |
| 0007 | 1Password Secret Management | Accepted | 2025-03 |
| 0008 | Self-Hosted Convex | Accepted | 2025-03 |
| 0009 | OTel + SigNoz Monitoring | Accepted | 2025-03 |
When to Write an ADR
Write an ADR when making decisions that:
- Affect the project structure (monorepo layout, package organization)
- Choose core technologies (frameworks, databases, build tools)
- Define architectural patterns (state management, API design, auth flow)
- Impact multiple teams or apps (shared packages, coding standards)
- Are hard to reverse (database schema, core dependencies)
- Need explanation (non-obvious choices, tradeoffs)
How to Create an ADR
- Copy the template:
cp docs/adr/template.md docs/adr/XXXX-your-decision-title.md - Number it sequentially using the next available number
- Fill in the sections: Status, Context, Decision, Consequences, Alternatives Considered
- Keep it concise — ADRs should be readable in 5-10 minutes
- Commit the ADR alongside the code it documents
Resources
- MADR — Markdown Architectural Decision Records
- ADR GitHub Organization — Tools and resources