# Technical Design — {Gear Name}

<!--
=============================================================================
TECHNICAL DESIGN DOCUMENT
=============================================================================
PURPOSE: Define HOW the system is built — architecture, components, APIs,
data models, and technical decisions that realize the requirements.

DESIGN IS PRIMARY: DESIGN defines the "what" (architecture and behavior).
ADRs record the "why" (rationale and trade-offs) for selected design
decisions; ADRs are not a parallel spec, it's a traceability artifact.

SCOPE:
  ✓ Architecture overview and vision
  ✓ Design principles and constraints
  ✓ Component model and interactions
  ✓ API contracts and interfaces
  ✓ Data models and database schemas
  ✓ Technology stack choices

NOT IN THIS DOCUMENT (see other templates):
  ✗ Requirements → PRD.md
  ✗ Detailed rationale for decisions → ADR/
  ✗ Step-by-step implementation flows → features/

STANDARDS ALIGNMENT:
  - IEEE 1016-2009 (Software Design Description)
  - IEEE 42010 (Architecture Description — viewpoints, views, concerns)
  - ISO/IEC 15288 / 12207 (Architecture & Design Definition processes)

ARCHITECTURE VIEWS (per IEEE 42010):
  - Context view: system boundaries and external actors
  - Functional view: components and their responsibilities
  - Information view: data models and flows
  - Deployment view: infrastructure topology

DESIGN LANGUAGE:
  - Be specific and clear; no fluff, bloat, or emoji
  - Reference PRD requirements using `cpt-{system}-fr-{slug}`, `cpt-{system}-nfr-{slug}`, and `cpt-{system}-usecase-{slug}` IDs
  - Reference ADR documents using `cpt-{system}-adr-{slug}` IDs
=============================================================================
-->

- [ ] `p3` - **ID**: `cpt-{system}-design-{slug}`

## Table of Contents

<!-- generated by `cfs toc` -->

## 1. Architecture Overview

### 1.1 Architectural Vision

{2-3 paragraphs: Technical approach, key decisions, design philosophy. How does this architecture satisfy the requirements?}

### 1.2 Architecture Drivers

Requirements that significantly influence architecture decisions.

#### Functional Drivers

| Requirement | Design Response |
|-------------|------------------|
| `cpt-{system}-fr-{slug}` | {How architecture addresses this requirement} |

#### NFR Allocation

This table maps non-functional requirements from PRD to specific design/architecture responses, demonstrating how quality attributes are realized.

| NFR ID | NFR Summary | Allocated To | Design Response | Verification Approach |
|--------|-------------|--------------|-----------------|----------------------|
| `cpt-{system}-nfr-{slug}` | {Brief NFR description} | {Component/layer/mechanism} | {How this design element realizes the NFR} | {How compliance is verified} |

#### Key ADRs

| ADR ID | Decision Summary |
|--------|-----------------|
| `cpt-{system}-adr-{slug}` | {Brief description of the architecture decision} |

### 1.3 Architecture Layers

{Add architecture diagram here: Mermaid or ASCII}

- [ ] `p3` - **ID**: `cpt-{system}-tech-{slug}`

| Layer | Responsibility | Technology |
|-------|---------------|------------|
| Presentation | {description} | {tech} |
| Application | {description} | {tech} |
| Domain | {description} | {tech} |
| Infrastructure | {description} | {tech} |

## 2. Principles & Constraints

### 2.1 Design Principles

#### {Principle Name}

- [ ] `p2` - **ID**: `cpt-{system}-principle-{slug}`

{Description of the principle and why it matters for this system.}

**ADRs**: `cpt-{system}-adr-{slug}`

### 2.2 Constraints

#### {Constraint Name}

- [ ] `p2` - **ID**: `cpt-{system}-constraint-{slug}`

{Description of the constraint (technical, regulatory, organizational) and its impact on design.}

**ADRs**: `cpt-{system}-adr-{slug}`

## 3. Technical Architecture

### 3.1 Domain Model

**Technology**: {GTS, Rust structs},

**Location**: [{domain-model-file}]({path/to/domain-model})

**Core Entities**:

- [ ] `p2` - **ID**: `cpt-{system}-entity-{slug}`

| Entity | Description | Schema |
|--------|-------------|--------|
| {EntityName} | {Purpose} | [{file}]({path}) |

**Relationships**:
- {Entity1} → {Entity2}: {Relationship description}

### 3.2 Component Model

{Describe all components covered by this design. For single-component designs, document that component. For multi-component designs, list all components with their responsibilities and interfaces. Include a component diagram (Mermaid or ASCII) showing structure and relationships.}

```mermaid
graph LR
    A[React SPA] -->|REST/WS| B[API Server]
    B --> C[PostgreSQL]
    B --> D[Redis PubSub]
    D --> B
```

#### {Component Name}

- [ ] `p2` - **ID**: `cpt-{system}-component-{slug}`

##### Why this component exists

{What problem it solves / why it is needed in the architecture.}

##### Responsibility scope

{What this component owns: core responsibilities, invariants, main operations.}

##### Responsibility boundaries

{What it explicitly does NOT do; what is delegated to other components; constraints on responsibilities.}

##### Related components (by ID)

{List component-to-component relationships using component IDs.}

- `cpt-{system}-component-{slug}` — {relationship type: depends on | calls | publishes to | subscribes to | shares model with | owns data for | etc.}

### 3.3 API Contracts

{For gear-level design: Document all public API contracts exposed by this gear. For multi-component design: Document the primary API contracts exposed by each component. Add references to gear designs}

- [ ] `p2` - **ID**: `cpt-{system}-interface-{slug}`

- **Contracts**: `cpt-{system}-contract-{slug}`
- **Technology**: {REST/OpenAPI | GraphQL | gRPC | etc.}
- **Location**: [{api-spec-file}]({path/to/api-spec})

**Endpoints Overview**:

| Method | Path | Description | Stability |
|--------|------|-------------|-----------|
| `{METHOD}` | `{/path}` | {Description} | {stable/unstable} |

### 3.4 Internal Dependencies

{Internal system/gear dependencies within the platform. All inter-gear communication goes through versioned contracts, SDK clients, or plugin interfaces — never through internal types.}

| Dependency Gear | Interface Used | Purpose |
|-------------------|----------------|----------|
| {gear_name} | {contract / SDK client / plugin} | {Why this gear is needed} |

**Dependency Rules** (per project conventions):
- No circular dependencies
- Always use sdk modules for inter-gear communication
- No cross-category sideways deps except through contracts
- Only integration/adapter gears talk to external systems
- `SecurityContext` must be propagated across all in-process calls

### 3.5 External Dependencies

External systems, databases, and third-party services this gear interacts with. Define protocols, data formats, and integration points.

#### {External System / Database / Service Name}

- **Contract**: `cpt-{system}-contract-{slug}`

| Dependency Gear | Interface Used | Purpose |
|-------------------|---------------|---------|
| {gear_name} | {contract / SDK client / plugin} | {Why this gear is needed} |

**Dependency Rules** (per project conventions):
- No circular dependencies
- Always use SDK modules for inter-gear communication
- No cross-category sideways deps except through contracts
- Only integration/adapter gears talk to external systems
- `SecurityContext` must be propagated across all in-process calls

### 3.6 Interactions & Sequences

{Document key interaction sequences and message flows between components.}

#### {Sequence Name}

**ID**: `cpt-{system}-seq-{slug}`

**Use cases**: `cpt-{system}-usecase-{slug}` (ID from PRD)

**Actors**: `cpt-{system}-actor-{slug}` (ID from PRD)

```mermaid
sequenceDiagram
    User ->> System: Request
    System ->> Gear B: Call
    System ->> Database: Query
    Database -->> System: Result
    System -->> User: Response
```

**Description**: {Brief description of what this sequence accomplishes}

### 3.7 Database schemas & tables

{ For gear-level design: Document database tables, schemas, and data models. For multi-component design: refer to component-level design documents. }

- [ ] `p3` - **ID**: `cpt-{system}-db-{slug}`

#### Table: {table_name}

**ID**: `cpt-{system}-dbtable-{slug}`

**Schema**:

| Column | Type | Description |
|--------|------|-------------|
| {col} | {type} | {description} |

**PK**: {primary key column(s)}

**Constraints**: {NOT NULL, UNIQUE, etc.}

**Additional info**: {Indexes, relationships, triggers, etc.}

**Example**:

| {col1} | {col2} | {col3} |
|--------|--------|--------|
| {val1} | {val2} | {val3} |

### 3.8 Deployment Topology

{Optional: Describe deployment topology — how components are deployed, network layout, infrastructure.}

- [ ] `p3` - **ID**: `cpt-{system}-topology-{slug}`

## 4. Additional context

{whatever useful additional context}

## 5. Traceability

- **PRD**: [PRD.md](./PRD.md)
- **ADRs**: [ADR/](./ADR/)
- **Features**: [features/](./features/)
