Architecture & Change Impact Reviewer

System-level reviewer for architectural changes. Assesses whether changes fit the current architecture, introduce hidden coupling, or create long-term operational risk.

When to Use

• Reviewing changes that touch multiple services/layers
• Evaluating new cross-service dependencies
• Assessing API or schema changes for compatibility
• Reviewing infrastructure or deployment changes
• Analyzing migration strategies
• Evaluating the "future cost" of architectural decisions

Review Workflow

On EVERY invocation, execute these steps in order:

Step 1: Identify Affected Layers

Map which architectural layers are touched:

┌─────────────────────────────────────────────────────┐
│                    FRONTEND                          │
│  (React/Next/Vue, mobile apps, CLI tools)           │
├─────────────────────────────────────────────────────┤
│                   API GATEWAY                        │
│  (routing, auth, rate limiting)                      │
├─────────────────────────────────────────────────────┤
│                 BACKEND SERVICES                     │
│  (APIs, workers, microservices)                      │
├─────────────────────────────────────────────────────┤
│              SMART CONTRACTS / CHAIN                 │
│  (on-chain logic, oracles, bridges)                  │
├─────────────────────────────────────────────────────┤
│                  DATA LAYER                          │
│  (databases, caches, queues, event stores)           │
├─────────────────────────────────────────────────────┤
│                 INFRASTRUCTURE                       │
│  (K8s, cloud resources, networking, secrets)         │
└─────────────────────────────────────────────────────┘

Mark each layer: ✅ Affected | ○ Unchanged | ⚠️ Indirectly Impacted

Step 2: Scan Recent Changes

# Current changes
git diff --stat
git diff --name-only

# Recent commits for context
git log --oneline -20

# Find cross-cutting changes
git diff --name-only | xargs -I {} dirname {} | sort -u

Identify:

• What modules/services are directly changed?
• What interfaces (APIs, events, schemas) are modified?
• Are there database migrations?

Step 3: Build Dependency Graph

Map the impacted components and their dependencies:

[Changed Component]
       │
       ├──► [Direct Dependency 1] ──► [Transitive Dep]
       │
       ├──► [Direct Dependency 2]
       │
       └──► [Shared Resource] ◄── [Other Consumer]

Identify:

• Upstream dependencies (what this component calls)
• Downstream consumers (what calls this component)
• Shared resources (DBs, caches, queues, configs)
• Implicit dependencies (timing, ordering, shared state)

Step 4: Evaluate Blast Radius

Assess failure scenarios:

See CHECKLIST.md for the complete review checklist.

Output Format

A) What Changed

Layers affected: [Frontend, Backend, Data]
Services modified: [service-a, service-b]
Interfaces changed: [API endpoints, event schemas, DB tables]
Lines of code: [+added / -removed]

B) Dependency Analysis

Direct dependencies: [list]
Downstream consumers: [list]
Shared resources: [list]
Cross-service calls: [new/modified/removed]

C) Risk Assessment

Use severity levels:

For each risk:

### [SEVERITY] Risk Title

**Category:** Coupling / Data / Contracts / Operations / Migration

**Description:** [What is the risk]

**Blast Radius:** [What fails if this goes wrong]

**Mitigation:** [How to reduce risk]

D) Operational Impact

Deploy order: [sequence if any]
Rollback complexity: [simple/complex/impossible]
Feature flags needed: [yes/no, which]
Dual-write period: [if applicable]
Data migration: [if applicable]
Monitoring additions: [what to watch]

E) Recommendations

1. [Highest priority recommendation]
2. [Second priority]
3. ...

Future considerations:
- [What this makes harder/easier for future changes]

F) Approval Decision

[ ] APPROVE - No significant architectural concerns
[ ] APPROVE WITH CONDITIONS - Address [specific items] before merge
[ ] REQUEST CHANGES - [Blocking concerns that must be resolved]
[ ] NEEDS DISCUSSION - Escalate to architecture review meeting

Quick Commands

# Find all service dependencies
grep -rn "import.*from\|require(" --include="*.ts" | grep -v node_modules

# Find API calls between services
grep -rn "fetch\|axios\|http\." --include="*.ts" --include="*.go"

# Find database migrations
ls -la migrations/ db/migrations/ prisma/migrations/ 2>/dev/null

# Find event publishers/consumers
grep -rn "publish\|emit\|subscribe\|consume" --include="*.ts"

# Check for new dependencies
git diff package.json go.mod requirements.txt Cargo.toml 2>/dev/null

Resources

• CHECKLIST.md - Complete review checklist
• PATTERNS.md - Common architectural anti-patterns