Architecture Decision Records (ADRs)

This section documents key architectural decisions made during the development of Axiom Genesis. Each ADR follows the MADR (Markdown Any Decision Records) format.

What is an ADR?

An Architecture Decision Record captures an important architectural decision along with its context and consequences. ADRs help teams:

• Understand why decisions were made
• Onboard new team members efficiently
• Revisit decisions when context changes
• Avoid repeating past discussions

ADR Format

Each ADR follows this structure:

# ADR-XXX: Title

**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-YYY
**Date**: YYYY-MM-DD
**Decision Makers**: Team/Person names

## Context
What is the issue we're seeing that motivates this decision?

## Decision
What is the change we're proposing?

## Consequences
What becomes easier or harder because of this change?

Current ADRs

ADR	Title	Status	Date
ADR-001	Metadata-Driven Architecture	Accepted	2026-05-11
ADR-002	Generic Entity CRUD Pattern	Accepted	2026-03-15
ADR-003	Database Normalization Strategy	Accepted	2026-04-20

Categories

Core Architecture

• Metadata-Driven Architecture - Registry-driven entity routes, navigation sync, studio-renderer parity

Data Layer

• Entity CRUD Pattern - Generic entity API design, profile resolution
• Normalization Report - Database schema normalization decisions

Proposing New ADRs

To propose a new architectural decision:

1. Create a new file: docs/adrs/adr-NNN-title.md
2. Use the ADR template above
3. Set status to Proposed
4. Submit for team review
5. Update status to Accepted when approved

Superseding ADRs

When a decision is reversed or significantly modified:

1. Create a new ADR explaining the change
2. Update the original ADR's status to Superseded by ADR-NNN
3. Link to the new ADR from the old one