Architecture Discipline

Architecture Discipline

When to Use

Use when decisions affect:

• Data models or schema changes
• Service boundaries or new services
• Deployment topology or infrastructure
• Scale characteristics (10x growth implications)
• Technology stack choices
• API contracts or external integrations

Skip for:

• Parameter tweaks or configuration changes
• UI/styling changes
• Localization or copy changes
• Bug fixes within existing architecture
• Adding fields to existing models (unless schema migration)

Threshold: If the decision could cause a 3+ month re-architecture project if wrong, use this skill.

CRITICAL: This Is Reasoning Discipline, Not a Checklist

The 7 sections are a reasoning sequence, not boxes to check:

• Alternatives BEFORE choosing
• Scale requirements BEFORE design
• Failure modes built in, not bolted on

🚨 If you wrote architecture without starting with all 7 sections: DELETE and restart. Retrofitting analysis is rationalization, not evaluation.

MANDATORY FIRST STEP

CREATE TodoWrite with these 7 sections (22+ items total):

Do not design, propose solutions, or implement until TodoWrite is verified.

Verification Checkpoint

After creating TodoWrite, verify 3 random items pass this test:

Each item must have ALL THREE:

• ✓ Concrete numbers/thresholds ("100K users", "$500/mo", "P95 < 500ms")
• ✓ Specific tools/technologies ("PostgreSQL", "Redis", "CloudWatch")
• ✓ Measurable outcome ("handles 1M req/sec", "costs $X at 10x")

DO NOT PROCEED until 22+ items AND quality check passes.

Section Requirements

1. Scale Analysis (4+ items)

NEVER design for current scale only. Before proposing any solution:

• Current scale: Users (DAU/MAU), requests/sec, data volume, read/write ratio
• 10x scale: What numbers at 10x? When expected?
• Bottlenecks: What breaks at 10x? (DB connections, API limits, memory)
• Mitigation: Specific solution for each bottleneck

2. Architectural Options (3+ items)

NEVER present single solution. Minimum 3 distinct options, each with:

• Performance: Latency (P50/P95/P99), throughput, scale limit
• Complexity: LOC estimate, services involved, operational burden
• Cost: Infrastructure ($X/mo current, $Y/mo at 10x), development (engineer-weeks)
• Trade-offs: Specific advantages (✅) and disadvantages (❌)

If stakeholder suggests solution: Add as Option A, evaluate with SAME rigor as alternatives.

3. Ripple Effect Analysis (5+ items)

Changes propagate across layers. Analyze ALL:

• Data layer: Schema changes, migrations, indexes, query performance
• Services: Which need updates? API contracts changed?
• API: Breaking changes? Version bump? Backward compatibility?
• Clients: Mobile updates? Web UI changes?
• Operations: Deployment changes? New monitoring? Cost changes?

4. Failure Modes (3+ items)

For each mode:

• Scenario: [Component] fails because [reason]
• Detection: How we know (metrics drop, error rate spike)
• Impact: What breaks (user features, data integrity)
• Mitigation: Circuit breaker, fallback, redundancy

5. Observability (3+ items)

• Metrics: Specific (latency P95, error rate %, throughput)
• Alerts: Conditions (error rate > 5%, latency P95 > 500ms)
• Dashboards: Key visualizations

6. Documentation (2+ items)

• ADR: Chosen option, rejected alternatives, trade-offs, constraints
• Diagram: New components, data flows, failure paths

7. Migration/Compatibility (2+ items)

• Backward compatibility: Old clients work? API versioning?
• Migration path: Phased rollout, feature flags, rollback procedure

Red Flags - STOP When You Think:

Override Requirements

To skip ANY requirement, you MUST provide ALL 4:

1. Specific retrofit date (not "later")
2. Budget allocated (engineer-weeks)
3. Risk acceptance signed by decision maker
4. Interim mitigation plan

Verification Before Complete

If any item missing, do not proceed to implementation.