Architecture Documentation

Create clear, comprehensive architecture documentation that communicates design decisions and system structure to stakeholders.

When to Use This Skill

• New system design
• Architecture changes
• Team onboarding
• Stakeholder communication
• Technical reviews
• Knowledge transfer
• Compliance requirements
• Decision tracking

Core Concepts

1. Architecture Decision Record (ADR)

# ADR 001: Use PostgreSQL for Primary Database

**Date:** 2024-01-15
**Status:** Accepted
**Deciders:** Tech Lead, Solutions Architect, Backend Team

## Context
Need to select a database for new e-commerce platform. Requirements:
- ACID transactions for order processing
- Complex queries (joins, aggregations)
- Strong consistency
- Support for 100K users initially, 1M within 2 years

## Decision
Use PostgreSQL as primary database.

## Alternatives Considered

**MySQL:**
- ✅ Widely used, good documentation
- ✅ Strong community support
- ❌ Historically weaker for complex queries
- ❌ JSON support not as robust

**MongoDB:**
- ✅ Flexible schema
- ✅ Horizontal scaling
- ❌ No multi-document ACID transactions (at time of decision)
- ❌ Eventual consistency by default

**DynamoDB:**
- ✅ Fully managed, auto-scaling
- ❌ Complex query limitations
- ❌ Vendor lock-in
- ❌ Cost unpredictable at scale

## Rationale
- PostgreSQL offers ACID guarantees needed for financial transactions
- Advanced SQL features (window functions, CTEs) for analytics
- Excellent JSON support for flexible data
- Proven at scale (Instagram, Uber)
- Can add read replicas for scaling
- Strong typing prevents data errors

## Consequences

**Positive:**
- Strong data consistency
- Rich query capabilities
- Battle-tested reliability
- Excellent tooling ecosystem

**Negative:**
- Vertical scaling limits (mitigated with read replicas)
- More complex horizontal sharding (if needed in future)
- Requires DBA expertise for optimization

## Compliance
No specific compliance requirements impacted.

## Notes
Will reassess if we need to shard beyond 10M users.

2. System Architecture Document

# System Architecture: E-Commerce Platform

## Overview
Microservices-based e-commerce platform supporting 1M users with high availability and scalability.

## Architecture Principles
1. Microservices for domain separation
2. API-first design
3. Event-driven communication
4. Cloud-native (AWS)
5. Infrastructure as Code

## System Context (C4 Level 1)
[Diagram showing users, system, external systems]

## Container Diagram (C4 Level 2)

**Frontend:**
- React SPA (S3 + CloudFront)
- Mobile Apps (iOS/Android)

**Backend Services:**
- API Gateway (AWS API Gateway)
- User Service (Node.js, PostgreSQL)
- Product Service (Node.js, PostgreSQL)
- Order Service (Node.js, PostgreSQL)
- Payment Service (Node.js)
- Notification Service (Node.js, SES)

**Data Stores:**
- PostgreSQL (RDS Multi-AZ)
- Redis (ElastiCache)
- S3 (product images)

**Messaging:**
- EventBridge (event bus)
- SQS (queues)

**External:**
- Stripe (payment processing)
- SendGrid (email)

## Technology Stack

**Frontend:**
- React 18
- TypeScript
- Tailwind CSS

**Backend:**
- Node.js 20
- Express.js
- TypeScript
- PostgreSQL 15
- Redis 7

**Infrastructure:**
- AWS (primary cloud)
- Terraform (IaC)
- GitHub Actions (CI/CD)
- DataDog (monitoring)

## Security
- HTTPS only (TLS 1.3)
- JWT authentication
- Role-based access control
- Encryption at rest (AES-256)
- Regular security scans (Snyk, OWASP ZAP)

## Scalability
- Horizontal scaling with Auto Scaling Groups
- Database read replicas
- CDN for static assets
- Redis caching
- Async processing with SQS

## Disaster Recovery
- RPO: 1 hour
- RTO: 4 hours
- Multi-AZ deployment
- Daily database backups
- Cross-region replication for critical data

## Monitoring & Observability
- DataDog APM
- CloudWatch logs
- Custom metrics dashboard
- PagerDuty alerts

Best Practices

1. Keep it current - Update with changes
2. Multiple views - Different stakeholders need different levels
3. Visual diagrams - Architecture diagrams, sequence diagrams
4. Decision rationale - Document "why", not just "what"
5. ADRs for major decisions - Track decision history
6. Living documentation - Evolve with system
7. Version control - Track changes over time
8. Review regularly - Quarterly architecture reviews

Resources

• C4 Model: https://c4model.com
• ADR Templates: https://adr.github.io
• Structurizr: Architecture diagram tool