Architecture templates help document technical decisions, system designs, and component specifications in a consistent, comprehensive manner.
ADR Template
Architecture Decision Records capture significant technical decisions along with their context and consequences.
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Date
[YYYY-MM-DD]
## Context
[Describe the issue motivating this decision. What is the problem we're trying to solve?
Include relevant constraints, requirements, and forces at play.]
## Decision
[State the architecture decision that was made. Use active voice:
"We will..." or "We have decided to..."]
## Consequences
### Positive
[List the benefits of this decision]
- Benefit 1
- Benefit 2
### Negative
[List the drawbacks or trade-offs]
- Drawback 1
- Drawback 2
### Risks
[Identify any risks introduced by this decision]
- Risk 1: [Description] - Mitigation: [How we'll address it]
## Alternatives Considered
[List other options that were evaluated]
### Alternative 1: [Name]
- Pros: [List advantages]
- Cons: [List disadvantages]
- Reason not chosen: [Why this wasn't selected]
### Alternative 2: [Name]
- Pros: [List advantages]
- Cons: [List disadvantages]
- Reason not chosen: [Why this wasn't selected]
## Related Decisions
- ADR-XXX: [Related decision]
- ADR-YYY: [Another related decision]
## References
- [Link to relevant documentation]
- [Link to discussion thread]System Design Document
# System Design: [System Name]
## Document Information
| Field | Value |
|-------|-------|
| Version | 1.0 |
| Author | [Name] |
| Last Updated | [Date] |
| Status | Draft / In Review / Approved |
| Reviewers | [Names] |
## 1. Overview
### 1.1 Purpose
[What problem does this system solve? What is its primary purpose?]
### 1.2 Scope
[What is included and excluded from this design?]
### 1.3 Goals and Non-Goals
**Goals:**
- Goal 1
- Goal 2
**Non-Goals:**
- Non-goal 1
- Non-goal 2
## 2. Background
### 2.1 Current State
[Describe the existing system or situation]
### 2.2 Motivation
[Why is this change needed?]
### 2.3 Requirements
[Key requirements driving the design]
| ID | Requirement | Priority |
|----|-------------|----------|
| REQ-001 | [Description] | Must Have |
| REQ-002 | [Description] | Should Have |
## 3. Architecture
### 3.1 High-Level Architecture
[Include architecture diagram]
[ASCII diagram or reference to image]
### 3.2 Components
| Component | Responsibility | Technology |
|-----------|--------------- |------------|
| [Name] | [What it does] |[Tech stack]|
### 3.3 Data Flow
[Describe how data moves through the system]
### 3.4 External Interfaces
[APIs, integrations, external systems]
## 4. Detailed Design
### 4.1 Component A
[Detailed design of each major component]
#### Responsibilities
[What this component does]
#### Interfaces
[APIs it exposes or consumes]
#### Data Model
[Data structures used]
#### Dependencies
[What it depends on]
### 4.2 Component B
[Repeat for each component]
## 5. Data Design
### 5.1 Data Model
[Entity relationship diagram or schema]
### 5.2 Data Storage
[Database choices and rationale]
### 5.3 Data Retention
[How long data is kept]
## 6. Security Considerations
### 6.1 Authentication
[How users/services authenticate]
### 6.2 Authorization
[How access is controlled]
### 6.3 Data Protection
[Encryption, PII handling]
### 6.4 Threat Mitigations
[Security measures implemented]
## 7. Operational Considerations
### 7.1 Monitoring
[What metrics, logs, alerts]
### 7.2 Scaling
[How system scales]
### 7.3 Failure Modes
[What can fail and how we handle it]
### 7.4 Deployment
[How system is deployed]
## 8. Testing Strategy
### 8.1 Unit Testing
[Approach to unit tests]
### 8.2 Integration Testing
[Approach to integration tests]
### 8.3 Performance Testing
[Approach to performance tests]
## 9. Migration Plan
[If replacing existing system]
## 10. Open Questions
[Unresolved issues needing decisions]
## Appendix
### A. Glossary
[Define terms used]
### B. References
[Links to related documents]API Specification
# API Specification: [API Name]
## Overview
| Field | Value |
|-------|-------|
| Version | 1.0.0 |
| Base URL | https://api.example.com/v1 |
| Authentication | Bearer Token |
| Last Updated | [Date] |
## Authentication
[Describe authentication method]
http Authorization: Bearer [Token]
## Common Headers
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |
| X-Request-ID | No | Correlation ID |
## Error Handling
### Error Response Format{ "error": { "code": "ERROR_CODE", "message": "Human-readable message", "details": {} } }
### Common Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| UNAUTHORIZED | 401 | Invalid or missing token |
| FORBIDDEN | 403 | Insufficient permissions |
| NOT_FOUND | 404 | Resource not found |
| VALIDATION_ERROR | 400 | Invalid request data |
## Rate Limiting
- 100 requests per minute per API key
- Rate limit headers included in response
## Endpoints
### [Resource Name]
#### Create [Resource]POST /resources
**Request Body:**{ "name": "string", "description": "string" }
**Response (201 Created):**{ "id": "string", "name": "string", "description": "string", "createdAt": "2024-01-01T00:00:00Z" }
#### Get [Resource]GET /resources/{id}
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| id | string | Resource ID |
**Response (200 OK):**{ "id": "string", "name": "string", "description": "string", "createdAt": "2024-01-01T00:00:00Z" }
#### List [Resources]GET /resources
**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| page | integer | 1 | Page number |
| limit | integer | 20 | Items per page |
| sort | string | createdAt | Sort field |
**Response (200 OK):**{ "data": [], "pagination": { "page": 1, "limit": 20, "total": 100 } }
## Webhooks
[If applicable, describe webhook events]
## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | [Date] | Initial release |Data Model Template
# Data Model: [Domain Name]
## Overview
[Describe the data domain and its purpose]
## Entity Relationship Diagram[ASCII or reference to diagram]
┌──────────────┐ ┌──────────────┐ │ User │ │ Order │ ├──────────────┤ ├──────────────┤ │ id │───┐ │ id │ │ email │ │ │ userId │──┐ │ name │ └──▶│ status │ │ │ createdAt │ │ totalAmount │ │ └──────────────┘ │ createdAt │ │ └──────────────┘ │ │ │ ▼ │ ┌──────────────┐ │ │ OrderItem │ │ ├──────────────┤ │ │ id │ │ │ orderId │──┘ │ productId │ │ quantity │ │ price │ └──────────────┘
## Entities
### User
[Description of the User entity]
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| email | VARCHAR(255) | UNIQUE, NOT NULL | User's email |
| name | VARCHAR(100) | NOT NULL | Display name |
| passwordHash | VARCHAR(255) | NOT NULL | Bcrypt hash |
| status | ENUM | NOT NULL | active, inactive, suspended |
| createdAt | TIMESTAMP | NOT NULL | Creation time |
| updatedAt | TIMESTAMP | NOT NULL | Last update |
**Indexes:**
- `idx_user_email` on `email` (unique)
- `idx_user_status` on `status`
**Relationships:**
- One-to-many with Order
### Order
[Description of the Order entity]
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | UUID | PK | Unique identifier |
| userId | UUID | FK, NOT NULL | Reference to User |
| status | ENUM | NOT NULL | pending, confirmed, shipped |
| totalAmount | DECIMAL(10,2) | NOT NULL | Order total |
| createdAt | TIMESTAMP | NOT NULL | Creation time |
## Enumerations
### OrderStatus
| Value | Description |
|-------|-------------|
| pending | Order created, not yet confirmed |
| confirmed | Payment received |
| shipped | Order shipped |
| delivered | Order delivered |
| cancelled | Order cancelled |
## Migration Scripts
### Create Users TableCREATE TABLE users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email VARCHAR(255) NOT NULL UNIQUE, name VARCHAR(100) NOT NULL, password_hash VARCHAR(255) NOT NULL, status VARCHAR(20) NOT NULL DEFAULT 'active', created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP );
CREATE INDEX idx_user_email ON users(email); CREATE INDEX idx_user_status ON users(status);
## Data Validation Rules
[Business rules for data integrity]
## Sensitive Data
[Identify PII, PHI, or other sensitive data]
| Field | Classification | Protection |
|-------|---------------|------------|
| email | PII | Encrypted at rest |
| passwordHash | Sensitive | Never logged |Related Resources
Compliance
This section fulfills ISO 13485 requirements for design and development planning (7.3.2), design inputs (7.3.3), and design outputs (7.3.4), and ISO 27001 requirements for secure architecture (A.8.27), information security in project management (A.5.8), and documentation of operating procedures (A.5.37).