This directory contains immutable architectural decisions for FlowForge. ADRs document the context, decision, and consequences of significant technical choices.
An Architecture Decision Record captures:
- Context: The forces at play (technical, organizational, project)
- Decision: The change we're proposing or have made
- Consequences: The resulting context after applying the decision
ADRs serve as:
- Historical record of why decisions were made
- Onboarding material for new team members
- Reference for future architectural discussions
- Justification for current system design
See INDEX.md for the complete, organized list of all ADRs with their mappings to archived sources.
- Copy the template:
cp 000-template.md NNN-your-decision.md - Fill in all sections: Context, Decision, Consequences, Alternatives
- Number sequentially: Use next available number (check INDEX.md)
- Include examples: Add code samples where relevant
- Link related docs: Reference other ADRs, evidence, plans
- Update INDEX.md: Add entry to the index
Proposed → Under Review → Accepted → Implemented → Superseded (if needed)
- Proposed: Draft ADR open for discussion
- Under Review: Team is evaluating the decision
- Accepted: Decision approved and documented
- Implemented: Decision applied to codebase
- Superseded: Replaced by newer ADR (original preserved for history)
Use 000-template.md which includes:
- Title: Short, descriptive name
- Status: Proposed | Accepted | Superseded by ADR-XXX
- Context: What forces are at play?
- Decision: What are we doing about it?
- Consequences: What becomes easier/harder?
- Alternatives Considered: What else did we evaluate?
- Related: Links to other ADRs, evidence, plans
- 001-099: Core architecture and foundations
- 100-199: Module-specific decisions (reserved for future use)
- future/: Exploratory ADRs not yet adopted
Current range: 001-024 (+ future ADRs)
- Evidence - Current implementation status
- Plans - Future work based on these decisions
- Design - Active design work
- Archive - Historical docs superseded by ADRs
- ADRs are immutable: Don't edit accepted ADRs (create superseding ADR instead)
- Be specific: Include code examples, diagrams, concrete details
- Explain alternatives: Document what you considered and why you rejected it
- Update INDEX.md: Always keep the index current
- Start with "why": Context is more important than the decision itself
- Be honest about trade-offs: Every decision has consequences
- Use examples: Code samples make decisions concrete
- Link liberally: Connect to related documents
- Think long-term: Future you will read this - make it clear!
For the complete ADR index and mappings, see INDEX.md