Architecture Decision Framework
Relevant source files
The following files were used as context for generating this wiki page:
- bundled-skills/architecture/SKILL.md
- bundled-skills/wiki-architect/SKILL.md
- bundled-skills/wiki-page-writer/SKILL.md
- bundled-skills/documentation-templates/SKILL.md
- bundled-skills/wiki-onboarding/SKILL.md
- bundled-skills/docs-architect/SKILL.md
- bundled-skills/architect-review/SKILL.md
- bundled-skills/software-architecture/SKILL.md
The Architecture Decision Framework is a structured methodology within the project designed to guide requirements analysis, trade-off evaluation, and the documentation of Architectural Decision Records (ADRs). It operates on the core principle that requirements drive architecture while trade-offs inform the final decisions, ensuring that complexity is added only when proven necessary.
This framework facilitates system design by providing selective reading paths for specific architectural tasks, such as context discovery, pattern selection, and trade-off analysis. It serves as a central pillar for maintaining architectural integrity, scalability, and maintainability across the software lifecycle.
Sources: bundled-skills/architecture/SKILL.md:1-12, bundled-skills/architect-review/SKILL.md:43-48
Core Methodology and Principles
The framework is built on the philosophy that "Simplicity is the ultimate sophistication." It advocates for starting with the simplest possible solution and only introducing patterns or architectural complexity when justified by specific requirements.
Decision-Making Logic
The following flow illustrates the standard procedure for applying the framework when making architectural choices:
The framework emphasizes that removing complexity is significantly harder than adding it.
Sources: bundled-skills/architecture/SKILL.md:23-30, bundled-skills/software-architecture/SKILL.md:10-15
Framework Components
The framework is divided into specialized modules that handle different stages of the architectural process.
| Component | Purpose | Relevant Files |
|---|---|---|
| Context Discovery | Initial phase to ask questions and classify projects. | context-discovery.md |
| Trade-off Analysis | Framework for evaluating competing priorities and documenting rationale. | trade-off-analysis.md |
| Pattern Selection | Decision trees and anti-pattern identification for choosing solutions. | pattern-selection.md |
| ADR Documentation | Capturing the history and rationale of significant decisions. | trade-off-analysis.md, SKILL.md |
Sources: bundled-skills/architecture/SKILL.md:14-21, bundled-skills/documentation-templates/SKILL.md:85-95
Architectural Documentation Standards
The framework mandates specific formats for documenting decisions to ensure clarity and historical context for the engineering team.
Architecture Decision Record (ADR)
Significant decisions must be captured in an ADR following a standardized template:
| Section | Description |
|---|---|
| Status | Current state: Accepted, Deprecated, or Superseded. |
| Context | The reasoning and background necessitating a decision. |
| Decision | The specific path chosen. |
| Consequences | The resulting trade-offs and impacts (positive and negative). |
Sources: bundled-skills/documentation-templates/SKILL.md:85-95, bundled-skills/architecture/SKILL.md:32-40
C4 Model Integration
For visual representation, the framework utilizes the C4 model to map system architecture across different levels of abstraction:
This hierarchical approach ensures that documentation serves both high-level stakeholders and deep-dive technical requirements.
Sources: bundled-skills/wiki-architect/SKILL.md:20-25, bundled-skills/wiki-page-writer/SKILL.md:30-40
Validation and Review
Before finalizing any architectural decision, the framework requires a validation checklist to be completed:
- Requirement Alignment: Are requirements clearly understood and mapped?
- Constraint Identification: Have technical and business constraints been identified?
- Trade-off Verification: Does each decision include a formal trade-off analysis?
- Simplicity Check: Have simpler alternatives been considered and documented?
- Expertise Match: Does the team's current expertise match the chosen technology or pattern?
Sources: bundled-skills/architecture/SKILL.md:32-40, bundled-skills/architect-review/SKILL.md:155-165
Technical Implementation Rules
When translating decisions into code, the framework enforces specific design patterns based on Clean Architecture and Domain-Driven Design (DDD).
Core Principles for Implementation
- Early Return Pattern: Use early returns over nested conditions to maintain readability.
- Library-First Approach: Always search for existing solutions (npm, SaaS, APIs) before writing custom code to avoid "Not Invented Here" syndrome.
- Separation of Concerns: Business logic must remain independent of frameworks and UI components.
- Bounded Context Naming: Use domain-specific names (e.g.,
OrderCalculator) instead of generic terms likeutilsorcommon.
Sources: bundled-skills/software-architecture/SKILL.md:7-40, bundled-skills/architect-review/SKILL.md:43-55
Summary
The Architecture Decision Framework ensures that system design remains intentional, documented, and as simple as possible. By leveraging ADRs, C4 modeling, and rigorous trade-off analysis, it provides a scalable environment for senior architects and developers to build maintainable, distributed systems while minimizing technical debt through "just-in-time" complexity.