Senior Architect
Architecture design guidance: pattern selection, decision documentation, dependency analysis, and system evolution strategies.
Architecture Decision Records (ADRs)
# ADR-001: [Decision Title]
## Status
Accepted | Proposed | Deprecated | Superseded by ADR-XXX
## Context
What problem are we facing? What constraints exist?
## Decision
What did we decide and why?
## Consequences
- Positive: [benefits]
- Negative: [trade-offs accepted]
- Risks: [what could go wrong]
Store in: docs/adrs/ or docs/architecture/decisions/
Architecture Pattern Selection
Decision Matrix
| Requirement |
Recommended Pattern |
| Rapid MVP development |
Modular Monolith |
| Independent team deployment |
Microservices |
| Complex domain logic |
Domain-Driven Design |
| High read/write ratio difference |
CQRS |
| Audit trail required |
Event Sourcing |
| Third-party integrations |
Hexagonal (Ports & Adapters) |
Pattern Overview
| Pattern |
Key Idea |
Trade-off |
| Modular Monolith |
Single deployment, clear module boundaries |
Easy start, harder to scale independently |
| Microservices |
Independent services, own databases |
Operational complexity, network latency |
| CQRS |
Separate read/write models |
Complexity increase, eventual consistency |
| Event Sourcing |
Store events, not state |
Full audit trail, replay capability; harder queries |
| Hexagonal |
Ports & adapters separate core from infra |
Testable, swappable; more indirection |
Dependency Analysis
Healthy vs Unhealthy Dependencies
| Signal |
Healthy |
Unhealthy |
| Direction |
Unidirectional (A → B) |
Circular (A → B → C → A) |
| Coupling |
Interface-based |
Implementation-based |
| Scope |
Narrow (few imports) |
Broad (importing internals) |
Breaking Circular Dependencies
- Extract shared interface/contract
- Invert dependency direction (depend on abstractions)
- Introduce an event bus or mediator
- Split into separate modules
Database Selection
| Type |
Best For |
| PostgreSQL |
Default for most apps. ACID, complex queries, JSON support |
| MongoDB |
Flexible schema, document-oriented, rapid prototyping |
| Redis |
Caching, sessions, real-time features |
| DynamoDB |
Serverless, auto-scaling, AWS-native |
| TimescaleDB |
Time-series with SQL |
Tech Stack Decision
| Question |
Recommendation |
| SEO required? |
Next.js with SSR |
| Internal dashboard? |
React + Vite |
| API-first backend? |
FastAPI or Fastify |
| Enterprise scale? |
NestJS + PostgreSQL |
| Rapid prototype? |
Next.js API routes |
| Real-time needed? |
WebSocket layer (Socket.io, ws) |
System Design Workflow
- Clarify requirements: Functional + non-functional (latency, throughput, availability)
- Estimate scale: Users, requests/sec, data size, growth rate
- Design high-level architecture: Components, data flow, API boundaries
- Choose data stores: Based on access patterns, consistency needs
- Design for failure: Retries, circuit breakers, fallbacks, graceful degradation
- Plan evolution: How does this scale 10×? What do we change?
Review Checklist
- ADR exists for key choices
- No circular dependencies between modules
- Clear separation: transport → business logic → data access
- Failure modes identified and handled
- Scaling strategy documented
- Consistency model chosen (strong vs eventual)
1---2name: senior-architect3description: System architecture design, ADRs, dependency analysis, architecture pattern selection (monolith, microservices, CQRS, event sourcing, hexagonal), database and tech stack decision matrices. Use when making architecture decisions or evaluating system design.4---56# Senior Architect78Architecture design guidance: pattern selection, decision documentation, dependency analysis, and system evolution strategies.910## Architecture Decision Records (ADRs)1112```markdown13# ADR-001: [Decision Title]1415## Status16Accepted | Proposed | Deprecated | Superseded by ADR-XXX1718## Context19What problem are we facing? What constraints exist?2021## Decision22What did we decide and why?2324## Consequences25- Positive: [benefits]26- Negative: [trade-offs accepted]27- Risks: [what could go wrong]28```2930**Store in:** `docs/adrs/` or `docs/architecture/decisions/`3132---3334## Architecture Pattern Selection3536### Decision Matrix3738| Requirement | Recommended Pattern |39|---|---|40| Rapid MVP development | Modular Monolith |41| Independent team deployment | Microservices |42| Complex domain logic | Domain-Driven Design |43| High read/write ratio difference | CQRS |44| Audit trail required | Event Sourcing |45| Third-party integrations | Hexagonal (Ports & Adapters) |4647### Pattern Overview4849| Pattern | Key Idea | Trade-off |50|---------|----------|-----------|51| Modular Monolith | Single deployment, clear module boundaries | Easy start, harder to scale independently |52| Microservices | Independent services, own databases | Operational complexity, network latency |53| CQRS | Separate read/write models | Complexity increase, eventual consistency |54| Event Sourcing | Store events, not state | Full audit trail, replay capability; harder queries |55| Hexagonal | Ports & adapters separate core from infra | Testable, swappable; more indirection |5657## Dependency Analysis5859### Healthy vs Unhealthy Dependencies6061| Signal | Healthy | Unhealthy |62|--------|---------|-----------|63| Direction | Unidirectional (A → B) | Circular (A → B → C → A) |64| Coupling | Interface-based | Implementation-based |65| Scope | Narrow (few imports) | Broad (importing internals) |6667### Breaking Circular Dependencies68691. Extract shared interface/contract702. Invert dependency direction (depend on abstractions)713. Introduce an event bus or mediator724. Split into separate modules7374## Database Selection7576| Type | Best For |77|------|----------|78| PostgreSQL | Default for most apps. ACID, complex queries, JSON support |79| MongoDB | Flexible schema, document-oriented, rapid prototyping |80| Redis | Caching, sessions, real-time features |81| DynamoDB | Serverless, auto-scaling, AWS-native |82| TimescaleDB | Time-series with SQL |8384## Tech Stack Decision8586| Question | Recommendation |87|----------|---------------|88| SEO required? | Next.js with SSR |89| Internal dashboard? | React + Vite |90| API-first backend? | FastAPI or Fastify |91| Enterprise scale? | NestJS + PostgreSQL |92| Rapid prototype? | Next.js API routes |93| Real-time needed? | WebSocket layer (Socket.io, ws) |9495## System Design Workflow96971. **Clarify requirements:** Functional + non-functional (latency, throughput, availability)982. **Estimate scale:** Users, requests/sec, data size, growth rate993. **Design high-level architecture:** Components, data flow, API boundaries1004. **Choose data stores:** Based on access patterns, consistency needs1015. **Design for failure:** Retries, circuit breakers, fallbacks, graceful degradation1026. **Plan evolution:** How does this scale 10×? What do we change?103104## Review Checklist105106- ADR exists for key choices107- No circular dependencies between modules108- Clear separation: transport → business logic → data access109- Failure modes identified and handled110- Scaling strategy documented111- Consistency model chosen (strong vs eventual)
lidge-jun