# Technical Architecture

Choose the smallest architecture that satisfies the requirements and can be operated by the available team. Record alternatives and trade-offs; do not select services only because they are popular.

[Kit README](README.md) · [Project Overview](Project%20Overview.md) · [PRD](Full%20PRD%20Template.md) · [Master Build Prompt](Master%20Build%20Prompt.md) · [Completion Checklist](Project%20Completion%20Checklist.md)

## Context

- **Product:** [PROJECT NAME]
- **Primary workload:** [INTERACTIVE REQUEST, BACKGROUND JOB, LOCAL TASK, OR CONTENT DELIVERY]
- **Clients:** [WEB, MOBILE, DESKTOP, API CONSUMER, OR AUTOMATION]
- **Scale assumption:** [ACTIVE USERS / REQUESTS / DATA VOLUME], labeled as estimate
- **Sensitive data:** [CLASSIFICATION]
- **Availability and recovery target:** [TARGET]

## Proposed Components

| Component | Responsibility | Owns Data? | Trust Boundary | Failure Behavior |
| --- | --- | --- | --- | --- |
| Client | Input, presentation, local state | Minimal | Untrusted input | Preserve safe draft; show recovery |
| Application service | Validation, authorization, business rules | Coordinates | Server boundary | Structured error; no partial hidden success |
| Persistence | Durable domain records | Yes | Restricted network/process | Retry bounded operations; alert |
| External dependency | [PURPOSE] | External | Third-party boundary | Timeout, circuit break, fallback |
| Worker/local engine | [ASYNC OR SPECIAL TASK] | Job state | Isolated execution | Idempotent retry or dead-letter |

For this project, likely records include Page, NavigationItem, ContentEntry, ContactSubmission, Asset, Redirect. Candidate interfaces include POST /api/contact; GET /api/content/:slug; POST /api/analytics/event. Remove a component or network hop if local or static behavior meets the requirement.

## Data Flow Review

For each core flow, document:

1. Origin and classification of input.
2. Validation at the first trusted boundary.
3. Authentication and object/tenant authorization.
4. Transaction and idempotency boundary.
5. External calls, timeouts, retry rules, and duplicate effects.
6. Stored fields, encryption, retention, deletion, and backup.
7. User-visible success or failure evidence.
8. Logs, metrics, traces, and sensitive-field redaction.

## Quality Attributes

| Attribute | Measurable Requirement | Verification |
| --- | --- | --- |
| Performance | [P95 OR STARTUP TARGET] | [LOAD/DEVICE TEST] |
| Reliability | [SUCCESS/RECOVERY TARGET] | [FAULT TEST] |
| Security | server-side contact validation | [AUTOMATED + REVIEW] |
| Accessibility | Core flow meets documented standard | [AUTOMATED + MANUAL] |
| Maintainability | Modules have single responsibilities and documented contracts | [REVIEW] |
| Operability | Owner can detect, diagnose, and roll back failures | [RUNBOOK DRILL] |

## Architecture Decision Record

~~~text
Decision: [TITLE]
Status/date: [PROPOSED/ACCEPTED + DATE]
Context: [FORCES AND CONSTRAINTS]
Options: [A / B / C]
Choice: [OPTION]
Why: [EVIDENCE]
Trade-offs: [COSTS]
Revisit when: [TRIGGER]
~~~

## Risk Review

Prioritize architecture controls for unclear positioning, oversized media, broken mobile navigation, forms that silently fail, missing page titles and alt text. Each high risk needs prevention, detection, recovery, an owner, and a test. The architecture is ready when the core flow, trust boundaries, data ownership, failure behavior, deployment, and rollback can be explained without relying on unstated platform magic.