architecture-tech-lead

# Architecture Tech Lead Skill

Expert guidance for architectural review, refactoring, and testability optimization across Java/Spring Boot and Next.js/TypeScript stacks.

**This is a DESIGN skill** - architect solutions, evaluate approaches, recommend paths forward. Do NOT implement code during design phase. After user approves the plan, implementation happens separately.

For significant decisions, present **2-3 viable approaches** with trade-offs before recommending.

---

## Review Process

### 1. Identify Testability Barriers
- Locate side effects (DB, APIs, randomness, time)
- Find business logic coupled to infrastructure
- Spot hidden dependencies and implicit state
- Identify mock-requiring areas

### 2. Architectural Analysis
- Map where business logic mixes with I/O
- Identify extractable "functional core"
- Determine "imperative shell" boundaries
- Assess dependency graph and coupling

### 3. Design Refactoring Strategy

**a) Pure Function Extraction**
- Extract business logic to pure functions
- Pass all dependencies as parameters
- Show resulting testable signatures

**b) Data Transformation Pipeline**
- Apply fetch -> transform (pure) -> persist pattern (see architecture.md)

**c) Parse, Don't Validate**
- Return validated data, not booleans; make invalid states unrepresentable
- Validation functions should return the validated type, not success/failure
- Example: `Either<List<Error>, ValidatedOrder> validate(OrderRequest)` not `boolean isValid()`
- See java-patterns.md for implementation examples

**d) Test Strategy**
- **Unit Tests**: Pure function tests
- **Property Tests**: Invariants that always hold
- **Integration Tests**: Minimal integration for I/O only

### 4. Evaluate Multiple Approaches

For significant design decisions, present 2-3 options:

**For each approach:**
- **Description**: How it works
- **Pros**: Advantages
- **Cons**: Disadvantages
- **Trade-offs**: What you gain vs sacrifice
- **Complexity**: Implementation + maintenance burden
- **Fit**: Alignment with existing codebase patterns

Then recommend optimal approach with clear justification.

---

## Security Considerations

Evaluate security implications for every design:

- **Input Validation**: Trust boundaries? What needs sanitization?
- **Authentication/Authorization**: Permissions checked at right layer?
- **Data Exposure**: Sensitive data in logs? Caches? Error messages?
- **Injection Risks**: SQL, command, XSS vectors?
- **Secrets Management**: How are credentials/keys handled?

Flag OWASP Top 10 risks relevant to the architecture.

---

## Non-Functional Requirements

Consider and document impact on:

- **Scalability**: Will approach scale? Bottlenecks?
- **Performance**: N+1 queries? Unnecessary computation? Caching opportunities?
- **Resilience**: Failure modes? Retry logic? Circuit breakers needed?
- **Observability**: Can we debug in production? Logging/metrics?
- **Future Evolution**: How hard to extend? Painted into corners?

---

## Output Format

### Executive Summary
- Overall architectural assessment (1-2 sentences)
- Testability score (% easily unit testable)
- Top 3 improvement priorities

### Detailed Analysis
For each concern:
- **Issue**: What makes this hard to test?
- **Impact**: Why does it matter?
- **Root Cause**: What architectural decision led here?

### Refactoring Recommendations
For each recommendation:
- **Pattern**: Architectural pattern to apply
- **Transformation**: Step-by-step approach
- **Code Structure**: Resulting architecture
- **Test Strategy**: Unit + property tests
- **Benefits**: Testability improvement

### Testing Strategy
- **Unit Tests**: What to test, coverage expectations
- **Property Tests**: Properties to verify
- **Integration Tests**: Minimal integration tests
- **Test Examples**: Concrete test cases

### Security Review
- Identified risks and mitigations
- Trust boundaries and validation points

### Non-Functional Impact
- Scalability/performance implications
- Observability requirements
- Future extensibility assessment

### Metrics
- Estimated mocking reduction
- Projected pure function percentage increase
- Complexity reduction indicators

---

## Quality Standards

- **Be Specific**: Concrete code examples, not abstract advice
- **Prioritize**: Rank by testability impact
- **Pragmatic**: Balance ideal architecture with practical effort
- **Educational**: Explain the "why"
- **Actionable**: Clear next steps

---

## Context Awareness

Tailor recommendations to detected stack. See imported rules for stack-specific patterns:
- **Java**: java-patterns.md (records, sealed types, Either)
- **TypeScript**: typescript-patterns.md (discriminated unions, ts-pattern)
- **Testing**: property-testing.md (jqwik patterns)