| name | architecture-blueprint |
| description | Create comprehensive architecture blueprints with C4 diagrams, ADRs (Architecture Decision Records), technology radar, dependency graphs, and deployment topology. Document architectural decisions before implementation. |
| tags | ["architecture","design","adr","c4-model","diagrams","planning","documentation"] |
| version | 1.0.0 |
| author | Enhanced from ThoughtWorks Tech Radar + C4 Model) |
Architecture Blueprint
Overview
Create a comprehensive architecture blueprint before building. The blueprint is the technical foundation that guides all implementation decisions.
A good architecture blueprint includes:
- C4 Diagrams - Context, Container, Component, Code views
- ADRs - Architecture Decision Records documenting key choices
- Technology Radar - Adopted, Trial, Assess, Hold technologies
- Dependency Graph - Service and module dependencies
- Deployment Topology - Infrastructure and deployment architecture
- Data Flow - How data moves through the system
- Security Model - Trust boundaries and security controls
- Scalability Plan - How the system scales
When to Use
Always use when:
- Starting a new project or major feature
- Making significant architectural changes
- Introducing new technologies or patterns
- Designing distributed systems
- Planning microservices architecture
- Migrating legacy systems
- Preparing for scale
Use before:
- Writing any code
- Creating detailed specs
- Estimating timelines
- Allocating resources
The 5-Phase Blueprint Process
┌─────────────────────────────────────────────────────────┐
│ ARCHITECTURE BLUEPRINT WORKFLOW │
└─────────────────────────────────────────────────────────┘
┌──────────────┐
│ PHASE 1 │ Understand Requirements
│ UNDERSTAND │ - Functional requirements
│ REQUIREMENTS │ - Non-functional requirements
└──────┬───────┘ - Constraints
│
▼
┌──────────────┐
│ PHASE 2 │ Design Architecture
│ DESIGN │ - C4 diagrams
│ ARCHITECTURE │ - Component design
└──────┬───────┘ - Data model
│
▼
┌──────────────┐
│ PHASE 3 │ Document Decisions
│ DOCUMENT │ - ADRs
│ DECISIONS │ - Technology choices
└──────┬───────┘ - Trade-offs
│
▼
┌──────────────┐
│ PHASE 4 │ Validate Design
│ VALIDATE │ - Review with stakeholders
│ DESIGN │ - Threat modeling
└──────┬───────┘ - Performance analysis
│
▼
┌──────────────┐
│ PHASE 5 │ Create Roadmap
│ CREATE │ - Implementation phases
│ ROADMAP │ - Dependencies
└──────────────┘ - Milestones
Phase 1: Understand Requirements
Step 1.1: Gather Functional Requirements
What the system must do:
## Functional Requirements
### User Management
- Users can sign up with email/password
- Users can log in and log out
- Users can reset forgotten passwords
- Users can update their profile
- Admins can manage user accounts
### Content Management
- Users can create, read, update, delete posts
- Posts support markdown formatting
- Posts can have tags and categories
- Posts can be published or drafted
- Posts have revision history
### Search
- Full-text search across posts
- Filter by tags, categories, author
- Sort by date, relevance, popularity
- Autocomplete suggestions
Step 1.2: Gather Non-Functional Requirements
How the system must perform:
## Non-Functional Requirements
### Performance
- Page load time < 2 seconds (p95)
- API response time < 200ms (p95)
- Search results < 500ms (p95)
- Support 10,000 concurrent users
- Handle 1,000 requests/second
### Scalability
- Horizontal scaling for web tier
- Database read replicas
- CDN for static assets
- Auto-scaling based on load
### Availability
- 99.9% uptime (8.76 hours downtime/year)
- Zero-downtime deployments
- Automated failover
- Multi-region deployment
### Security
- HTTPS everywhere
- OWASP Top 10 compliance
- Data encryption at rest
- Regular security audits
- GDPR compliance
### Maintainability
- Comprehensive test coverage (>80%)
- Automated CI/CD pipeline
- Infrastructure as code
- Monitoring and alerting
- Documentation
### Observability
- Distributed tracing
- Centralized logging
- Metrics and dashboards
- Error tracking
- Performance monitoring
Step 1.3: Identify Constraints
What limits our choices:
## Constraints
### Technical Constraints
- Must use existing PostgreSQL database
- Must integrate with legacy authentication system
- Must support IE11 (corporate requirement)
- Must run on AWS (company standard)
### Business Constraints
- Budget: $50,000 for infrastructure (first year)
- Timeline: 6 months to MVP
- Team: 3 developers, 1 designer, 1 PM
- Compliance: SOC2, GDPR, HIPAA
### Organizational Constraints
- Must use company-approved technologies
- Must follow company security policies
- Must integrate with existing monitoring
- Must use company CI/CD pipeline
Phase 2: Design Architecture
Step 2.1: Create C4 Diagrams
Level 1: System Context
Shows how the system fits into the world.
## C4 Level 1: System Context
```mermaid
graph TB
User[User<br/>Web Browser]
Admin[Admin<br/>Web Browser]
System[Content Management System]
Auth[Legacy Auth System<br/>LDAP]
Email[Email Service<br/>SendGrid]
CDN[CDN<br/>CloudFront]
User -->|Uses| System
Admin -->|Manages| System
System -->|Authenticates via| Auth
System -->|Sends emails via| Email
System -->|Serves static assets via| CDN
Key:
- Users - Content creators and readers
- Admins - System administrators
- CMS - Our system (the thing we're building)
- Legacy Auth - Existing authentication system (constraint)
- Email Service - Third-party email delivery
- CDN - Content delivery network
---
**Level 2: Container Diagram**
Shows the high-level technology choices.
```markdown
## C4 Level 2: Container Diagram
```mermaid
graph TB
User[User<br/>Web Browser]
subgraph "Content Management System"
Web[Web Application<br/>Next.js 14<br/>Port 3000]
API[API Server<br/>Node.js + Express<br/>Port 4000]
Search[Search Service<br/>Elasticsearch<br/>Port 9200]
DB[(Database<br/>PostgreSQL 16)]
Cache[(Cache<br/>Redis 7)]
Queue[Message Queue<br/>RabbitMQ]
end
Auth[Legacy Auth<br/>LDAP]
Email[Email Service<br/>SendGrid API]
CDN[CDN<br/>CloudFront]
User -->|HTTPS| Web
Web -->|API calls| API
API -->|Reads/Writes| DB
API -->|Caches| Cache
API -->|Searches| Search
API -->|Publishes| Queue
API -->|Authenticates| Auth
Queue -->|Sends| Email
Web -->|Static assets| CDN
Technology Choices:
- Web: Next.js 14 (React framework, SSR, API routes)
- API: Node.js + Express (REST API, business logic)
- Database: PostgreSQL 16 (relational data, ACID)
- Cache: Redis 7 (session storage, query cache)
- Search: Elasticsearch (full-text search)
- Queue: RabbitMQ (async tasks, email sending)
- CDN: CloudFront (static assets, images)
---
**Level 3: Component Diagram**
Shows the internal structure of a container.
```markdown
## C4 Level 3: Component Diagram (API Server)
```mermaid
graph TB
subgraph "API Server"
Router[Router<br/>Express Router]
Auth[Auth Middleware<br/>JWT validation]
subgraph "Controllers"
UserCtrl[User Controller]
PostCtrl[Post Controller]
SearchCtrl[Search Controller]
end
subgraph "Services"
UserSvc[User Service]
PostSvc[Post Service]
SearchSvc[Search Service]
EmailSvc[Email Service]
end
subgraph "Repositories"
UserRepo[User Repository]
PostRepo[Post Repository]
end
Router --> Auth
Auth --> UserCtrl
Auth --> PostCtrl
Auth --> SearchCtrl
UserCtrl --> UserSvc
PostCtrl --> PostSvc
SearchCtrl --> SearchSvc
UserSvc --> UserRepo
PostSvc --> PostRepo
PostSvc --> SearchSvc
PostSvc --> EmailSvc
UserRepo --> DB[(Database)]
PostRepo --> DB
SearchSvc --> ES[(Elasticsearch)]
EmailSvc --> Queue[(RabbitMQ)]
end
Component Responsibilities:
- Router: Route HTTP requests to controllers
- Auth Middleware: Validate JWT tokens, check permissions
- Controllers: Handle HTTP requests/responses, validation
- Services: Business logic, orchestration
- Repositories: Data access, queries
---
**Level 4: Code Diagram**
Shows the class/module structure (optional, for complex components).
```markdown
## C4 Level 4: Code Diagram (Post Service)
```typescript
// Domain Model
interface Post {
id: string;
title: string;
content: string;
authorId: string;
status: 'draft' | 'published';
tags: string[];
createdAt: Date;
updatedAt: Date;
}
// Repository Interface
interface PostRepository {
findById(id: string): Promise<Post | null>;
findByAuthor(authorId: string): Promise<Post[]>;
create(post: Omit<Post, 'id'>): Promise<Post>;
update(id: string, post: Partial<Post>): Promise<Post>;
delete(id: string): Promise<void>;
}
// Service
class PostService {
constructor(
private postRepo: PostRepository,
private searchService: SearchService,
private emailService: EmailService
) {}
async createPost(authorId: string, data: CreatePostDTO): Promise<Post> {
// Validate
const validated = CreatePostSchema.parse(data);
// Create
const post = await this.postRepo.create({
...validated,
authorId,
status: 'draft',
createdAt: new Date(),
updatedAt: new Date()
});
// Index for search
await this.searchService.indexPost(post);
return post;
}
async publishPost(postId: string, authorId: string): Promise<Post> {
// Verify ownership
const post = await this.postRepo.findById(postId);
if (!post || post.authorId !== authorId) {
throw new ForbiddenError();
}
// Update status
const published = await this.postRepo.update(postId, {
status: 'published',
updatedAt: new Date()
});
// Notify subscribers
await this.emailService.notifySubscribers(published);
return published;
}
}
### Step 2.2: Design Data Model
**Entity-Relationship Diagram:**
```markdown
## Data Model
```mermaid
erDiagram
User ||--o{ Post : creates
User ||--o{ Comment : writes
Post ||--o{ Comment : has
Post }o--o{ Tag : tagged_with
User ||--o{ Session : has
User {
uuid id PK
string email UK
string password_hash
string name
boolean is_admin
timestamp created_at
timestamp updated_at
}
Post {
uuid id PK
uuid author_id FK
string title
text content
string status
timestamp published_at
timestamp created_at
timestamp updated_at
}
Comment {
uuid id PK
uuid post_id FK
uuid author_id FK
text content
timestamp created_at
}
Tag {
uuid id PK
string name UK
string slug UK
}
PostTag {
uuid post_id FK
uuid tag_id FK
}
Session {
uuid id PK
uuid user_id FK
string token UK
timestamp expires_at
timestamp created_at
}
Schema (PostgreSQL):
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
name VARCHAR(255) NOT NULL,
is_admin BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_users_email ON users(email);
CREATE TABLE posts (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
author_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
title VARCHAR(500) NOT NULL,
content TEXT NOT NULL,
status VARCHAR(20) DEFAULT 'draft',
published_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_posts_author ON posts(author_id);
CREATE INDEX idx_posts_status ON posts(status);
CREATE INDEX idx_posts_published ON posts(published_at DESC);
### Step 2.3: Design API
**REST API Specification:**
```markdown
## API Design
### Authentication
All endpoints except `/auth/login` and `/auth/signup` require authentication via JWT token in `Authorization: Bearer <token>` header.
### Endpoints
#### Authentication
POST /api/auth/signup Create account
POST /api/auth/login Login
POST /api/auth/logout Logout
POST /api/auth/refresh Refresh token
POST /api/auth/reset-password Request password reset
#### Users
GET /api/users/:id Get user profile
PUT /api/users/:id Update user profile
DELETE /api/users/:id Delete user account
GET /api/users/:id/posts Get user's posts
#### Posts
GET /api/posts List posts (paginated)
POST /api/posts Create post
GET /api/posts/:id Get post
PUT /api/posts/:id Update post
DELETE /api/posts/:id Delete post
POST /api/posts/:id/publish Publish post
#### Search
GET /api/search?q=query Search posts
GET /api/search/suggest?q= Autocomplete suggestions
### Example Request/Response
**POST /api/posts**
```json
// Request
{
"title": "My First Post",
"content": "# Hello World\n\nThis is my first post.",
"tags": ["introduction", "hello"]
}
// Response (201 Created)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "My First Post",
"content": "# Hello World\n\nThis is my first post.",
"authorId": "123e4567-e89b-12d3-a456-426614174000",
"status": "draft",
"tags": ["introduction", "hello"],
"createdAt": "2026-05-26T00:00:00Z",
"updatedAt": "2026-05-26T00:00:00Z"
}
Error Responses
{
"error": "Validation failed",
"details": [
{ "field": "title", "message": "Title is required" }
]
}
{
"error": "Authentication required"
}
{
"error": "You don't have permission to access this resource"
}
{
"error": "Resource not found"
}
{
"error": "Internal server error",
"requestId": "req_abc123"
}
## Phase 3: Document Decisions
### Step 3.1: Write Architecture Decision Records (ADRs)
**ADR Template:**
```markdown
# ADR-001: Use PostgreSQL for Primary Database
**Status:** Accepted
**Date:** 2026-05-26
**Context:**
We need a database to store user data, posts, and comments. The system requires ACID transactions, complex queries with joins, and full-text search capabilities.
**Decision:**
We will use PostgreSQL 16 as our primary database.
**Consequences:**
**Positive:**
- ACID compliance ensures data integrity
- Rich query capabilities (joins, CTEs, window functions)
- Built-in full-text search (pg_trgm, ts_vector)
- JSON support for flexible schemas
- Mature ecosystem and tooling
- Strong community support
- Excellent performance for our scale (< 1M records)
**Negative:**
- Vertical scaling limits (though sufficient for our needs)
- More complex to operate than managed NoSQL
- Requires careful index management for performance
**Alternatives Considered:**
- **MongoDB**: Rejected due to lack of ACID transactions and complex query support
- **MySQL**: Rejected due to inferior full-text search and JSON support
- **DynamoDB**: Rejected due to query limitations and vendor lock-in
**Related Decisions:**
- ADR-002: Use Prisma as ORM
- ADR-005: Use Elasticsearch for advanced search
Common ADR Topics:
- Database choice
- Framework selection
- Authentication strategy
- Deployment platform
- API design (REST vs GraphQL)
- State management
- Testing strategy
- Monitoring solution
Step 3.2: Create Technology Radar
Inspired by ThoughtWorks Technology Radar:
## Technology Radar
### Adopt (Use with confidence)
- **Next.js 14** - React framework with SSR
- **TypeScript 5** - Type-safe JavaScript
- **PostgreSQL 16** - Primary database
- **Redis 7** - Caching and sessions
- **Vitest** - Fast unit testing
- **Playwright** - E2E testing
- **Docker** - Containerization
- **GitHub Actions** - CI/CD
### Trial (Worth pursuing, but not yet proven)
- **Elasticsearch** - Advanced search (evaluate vs PostgreSQL FTS)
- **RabbitMQ** - Message queue (evaluate vs SQS)
- **Prisma** - ORM (evaluate vs raw SQL)
- **Zod** - Schema validation
### Assess (Explore to understand potential)
- **tRPC** - Type-safe APIs (alternative to REST)
- **Turborepo** - Monorepo tooling
- **Bun** - Fast JavaScript runtime
- **Drizzle ORM** - Lightweight ORM
### Hold (Proceed with caution)
- **MongoDB** - Not suitable for our use case
- **GraphQL** - Adds complexity without clear benefit
- **Microservices** - Premature for our scale
- **Kubernetes** - Over-engineered for our needs
Phase 4: Validate Design
Step 4.1: Threat Modeling
STRIDE Analysis:
## Threat Model
### Spoofing
- **Threat**: Attacker impersonates legitimate user
- **Mitigation**: JWT tokens, secure session management, MFA
### Tampering
- **Threat**: Attacker modifies data in transit or at rest
- **Mitigation**: HTTPS, database encryption, input validation
### Repudiation
- **Threat**: User denies performing an action
- **Mitigation**: Audit logging, immutable logs
### Information Disclosure
- **Threat**: Sensitive data exposed
- **Mitigation**: Encryption at rest, access controls, data masking
### Denial of Service
- **Threat**: System becomes unavailable
- **Mitigation**: Rate limiting, auto-scaling, DDoS protection
### Elevation of Privilege
- **Threat**: User gains unauthorized access
- **Mitigation**: Role-based access control, principle of least privilege
Step 4.2: Performance Analysis
Back-of-the-envelope calculations:
## Performance Analysis
### Traffic Estimates
- **Users**: 100,000 monthly active users
- **Requests**: 10 requests/user/day = 1M requests/day
- **Peak**: 3x average = 35 requests/second
- **Growth**: 2x per year
### Database Sizing
- **Users**: 100K users × 1KB = 100MB
- **Posts**: 1M posts × 10KB = 10GB
- **Comments**: 5M comments × 500B = 2.5GB
- **Total**: ~15GB (fits in memory for caching)
### Bandwidth
- **Average page**: 500KB (HTML + CSS + JS + images)
- **Peak traffic**: 35 req/s × 500KB = 17.5 MB/s = 140 Mbps
- **Monthly**: 1M req/day × 30 days × 500KB = 15TB/month
### Cost Estimate (AWS)
- **EC2** (2× t3.medium): $60/month
- **RDS** (db.t3.medium): $70/month
- **ElastiCache** (cache.t3.micro): $15/month
- **S3 + CloudFront**: $50/month
- **Total**: ~$200/month
Phase 5: Create Roadmap
Step 5.1: Define Implementation Phases
## Implementation Roadmap
### Phase 1: Foundation (Weeks 1-4)
**Goal**: Basic infrastructure and authentication
**Deliverables:**
- [ ] Database schema and migrations
- [ ] Authentication system (signup, login, logout)
- [ ] Basic API structure
- [ ] CI/CD pipeline
- [ ] Monitoring and logging
**Success Criteria:**
- Users can sign up and log in
- All tests passing
- Deployed to staging
---
### Phase 2: Core Features (Weeks 5-12)
**Goal**: Post creation and management
**Deliverables:**
- [ ] Post CRUD operations
- [ ] Markdown editor
- [ ] Draft/publish workflow
- [ ] Tag system
- [ ] Basic search
**Success Criteria:**
- Users can create and publish posts
- Search returns relevant results
- Performance meets targets
---
### Phase 3: Advanced Features (Weeks 13-20)
**Goal**: Enhanced user experience
**Deliverables:**
- [ ] Comments system
- [ ] User profiles
- [ ] Email notifications
- [ ] Advanced search (Elasticsearch)
- [ ] Image uploads
**Success Criteria:**
- Users can comment on posts
- Email notifications working
- Advanced search operational
---
### Phase 4: Polish & Launch (Weeks 21-24)
**Goal**: Production-ready system
**Deliverables:**
- [ ] Performance optimization
- [ ] Security audit
- [ ] Documentation
- [ ] Admin dashboard
- [ ] Production deployment
**Success Criteria:**
- All success criteria met
- Security audit passed
- Documentation complete
- Deployed to production
Step 5.2: Identify Dependencies
## Dependencies
### Critical Path
Database Schema → Auth System → API Structure → Post CRUD → Search → Launch
### Parallel Workstreams
- **Frontend**: Can start after API structure is defined
- **Search**: Can be developed in parallel with core features
- **Email**: Can be added after core features are stable
### External Dependencies
- **Legacy Auth Integration**: Requires coordination with IT team (2-week lead time)
- **CDN Setup**: Requires approval from infrastructure team (1-week lead time)
- **Security Audit**: External vendor (schedule 2 weeks before launch)
Blueprint Checklist
Before implementation, verify:
Integration with Other Skills
Load these skills after blueprint:
spec-driven-development-enhanced - For detailed specificationstdd-iron-law - For test-driven implementationsecurity-review-owasp - For security validation
Tools
Diagramming:
- Mermaid (text-based, version-controllable)
- Excalidraw (hand-drawn style)
- draw.io (traditional diagrams)
ADR Management:
- adr-tools (CLI for managing ADRs)
- Markdown files in
docs/adr/
Threat Modeling:
- OWASP Threat Dragon
- Microsoft Threat Modeling Tool
Pitfalls
Pitfall 1: Over-Engineering
Symptom: Architecture is too complex for the problem
Solution: Start simple, add complexity only when needed
Pitfall 2: Under-Engineering
Symptom: Architecture doesn't support requirements
Solution: Validate against non-functional requirements
Pitfall 3: Ignoring Constraints
Symptom: Design violates organizational or technical constraints
Solution: List constraints explicitly, validate against them
Pitfall 4: No Documentation
Symptom: Decisions are made but not recorded
Solution: Write ADRs for every significant decision
Remember: Architecture is about making trade-offs explicit. There are no perfect architectures, only architectures that fit the constraints and requirements.
