Architecture & System Design Templates

# ADR-{{NUMBER}}: {{TITLE}}

- **Status**: [PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED by ADR-XXX]
- **Deciders**: [List of architects and lead engineers]
- **Date**: YYYY-MM-DD
- **Technical Story**: [Jira/Issue link or SRS reference]

## Context and Problem Statement
{{Describe the context and problem statement in 2-3 plain-language sentences. What forces are at play?}}

## Decision Drivers
- {{Driver 1: e.g. Zero downtime migration requirement}}
- {{Driver 2: e.g. Compliance with HIPAA § 164.312 encryption standards}}
- {{Driver 3: e.g. Sub-50ms p99 query latency}}

## Considered Options
1. **Option 1**: {{Title and brief summary}}
2. **Option 2**: {{Title and brief summary}}
3. **Option 3**: {{Title and brief summary}}

## Decision Outcome
Chosen Option: **Option 1**, because {{rationale justifying choice against decision drivers}}.

### Positive Consequences
- {{Positive consequence 1}}
- {{Positive consequence 2}}

### Negative Consequences / Trade-offs
- {{Negative consequence 1, e.g. increased operational overhead}}
- {{Mitigation plan}}

## Pros and Cons of the Options
### Option 1: {{Name}}
- Good, because {{reason}}
- Bad, because {{reason}}

### Option 2: {{Name}}
- Good, because {{reason}}
- Bad, because {{reason}}

# System Design Document: {{SYSTEM_NAME}}

- **Author(s)**: {{Names}}
- **Reviewer(s)**: {{Lead Architect, Security Lead}}
- **Target Release**: {{Version / Sprint}}
- **Status**: [DRAFT | UNDER REVIEW | APPROVED]

## 1. Executive Summary & Plain-Language Overview
{{1-2 paragraphs explaining what the system does and why it is being built in non-technical terms.}}

## 2. Goals & Non-Goals
### Goals
- {{Measurable Goal 1: e.g. Support 5,000 concurrent clinical telemetry streams}}
- {{Measurable Goal 2: e.g. 99.99% availability with zero data loss}}

### Non-Goals
- {{Explicit out-of-scope items}}

## 3. Architecture & Component Diagram
```mermaid
graph TD
  Client[Client Application] --> API[API Gateway]
  API --> Service[Core Processing Service]
  Service --> DB[(Encrypted Database)]
  Service --> Cache[(Redis Cache)]
```

## 4. Data Model & Storage
- **Primary Datastore**: {{e.g. PostgreSQL with AES-256 transparent data encryption}}
- **Schema & Relationships**: {{Describe entities and indexing strategy}}

## 5. Security & Compliance Considerations
- **Authentication**: {{OAuth 2.0 / JWT}}
- **Data Protection**: {{Encryption in transit via TLS 1.3, at rest via AES-GCM}}
- **Audit Logging**: {{Immutable write-only audit trail}}

## 6. Failure Modes & Disaster Recovery
- **Component Failure Handling**: {{Circuit breakers, dead letter queues}}
- **RTO / RPO**: {{RTO < 1 hour, RPO < 5 minutes}}

# API Specification: {{API_NAME}}

- **Base URL**: `https://api.example.com/v1`
- **Authentication**: Bearer JWT in `Authorization` header
- **Content-Type**: `application/json`

## Endpoint: `POST /v1/records`
Creates a new patient compliance record.

### Request Headers
| Header | Type | Required | Description |
|:---|:---|:---|:---|
| `Authorization` | string | Yes | `Bearer <JWT_TOKEN>` |
| `X-Correlation-ID` | string | Yes | Unique UUID for distributed tracing |

### Request Body Schema
```json
{
  "recordType": "TELEMETRY_LOG",
  "patientId": "pt-882194",
  "payload": {
    "vitalCode": "HR_BPM",
    "value": 72
  }
}
```

### Response `201 Created`
```json
{
  "id": "rec-00129",
  "status": "RECORDED",
  "createdAt": "2026-08-20T12:00:00Z"
}
```

### Error Responses
- `400 Bad Request`: Schema validation failure.
- `401 Unauthorized`: Missing or expired token.
- `403 Forbidden`: Insufficient role permissions.

# Data Model Specification: {{DOMAIN_NAME}}

## 1. Entity-Relationship Overview
- **Primary Schema**: `public` or domain namespace
- **Database Engine**: PostgreSQL 16+

## 2. Table: `user_accounts`
Stores verified user identities and authorization roles.

| Column Name | Data Type | Constraints | Description |
|:---|:---|:---|:---|
| `id` | `UUID` | `PRIMARY KEY, DEFAULT gen_random_uuid()` | Unique account identifier |
| `email` | `VARCHAR(255)` | `NOT NULL, UNIQUE` | User email address |
| `password_hash` | `VARCHAR(255)` | `NOT NULL` | Argon2id password hash |
| `role` | `VARCHAR(50)` | `NOT NULL, DEFAULT 'PRACTITIONER'` | RBAC role tag |
| `created_at` | `TIMESTAMPTZ` | `NOT NULL, DEFAULT NOW()` | Record insertion timestamp |

## 3. Indexes & Constraints
- `CREATE INDEX idx_user_accounts_email ON user_accounts(email);`
- `CREATE INDEX idx_user_accounts_role ON user_accounts(role);`

## 4. Privacy & Retention Policy
- Records retained for 7 years per regulatory archive rules.
- ePHI fields encrypted using column-level AES-256 encryption.