Architecture Templates

# 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: [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]

### 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 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]

## 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
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

POST /resources

{
  "name": "string",
  "description": "string"
}

{
  "id": "string",
  "name": "string",
  "description": "string",
  "createdAt": "2024-01-01T00:00:00Z"
}

GET /resources/{id}

{
  "id": "string",
  "name": "string",
  "description": "string",
  "createdAt": "2024-01-01T00:00:00Z"
}

GET /resources

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

---

## Data Model Template

```markdown
# Data Model: [Domain Name]

## Overview
[Describe the data domain and its purpose]

## Entity Relationship Diagram

## 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 Table
```sql
CREATE 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);

---

## Related Resources

- [Design Patterns](/docs/netspective-unified-process-deterministic/design/design-patterns)
- [API Design](/docs/netspective-unified-process-deterministic/design/api-design)
- [Architecture Decisions](/docs/netspective-unified-process-deterministic/design/architecture-decisions)
- [Microsoft Playbook: Design](https://microsoft.github.io/code-with-engineering-playbook/design/)

---

## 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).

[View full compliance matrix](/docs/netspective-unified-process-deterministic/compliance-matrix)