Architecture Design

Evidence-based architecture proposals with explicit trade-offs and alternatives.

Guiding Principle

Architecture is the art of trade-offs, not the application of best practices. Every choice has a cost — make it visible.

Procedure

Step 1 — Constraint Mapping

Before designing, map the constraints:

Step 2 — Option Generation

Generate at least 3 viable options:

1. Conservative: Minimum change, lowest risk, closest to current architecture
2. Recommended: Best balance of quality, effort, and risk
3. Ambitious: Highest quality outcome, higher effort/risk

Step 3 — Trade-off Analysis

For each option, evaluate:

Step 4 — Decision Record

Document the decision as an ADR:

• Context (why this decision is needed)
• Decision (what was chosen)
• Consequences (positive, negative, neutral)
• Alternatives considered (with rejection rationale)

Step 5 — Architecture Artifacts

Generate as needed:

• Component diagram (Mermaid)
• Data flow diagram
• API contract sketch
• Database schema changes
• Infrastructure changes

Quality Criteria

• At least 3 options evaluated
• Every option has explicit trade-offs
• Decision rationale references specific constraints
• Artifacts are specific to the system, not generic patterns

Anti-Patterns

• Proposing architecture without understanding constraints
• "Best practice" as sole justification
• Single-option proposals disguised as analysis
• Over-engineering for hypothetical future requirements