# System overview (docs/architecture/system-design.md)

Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.

Required: **Purpose**, **Subsystem map**. Optional: Key flows, Sources of truth.

```markdown
---
type: system-overview
description: "{at most 300 characters: what this document settles and where its boundary sits}"
---

# System Overview

## Purpose

{Two or three sentences: what the system does, for whom, in what environment it runs.}

## Subsystem map

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Frontend │────▶│   API    │────▶│    DB    │
└──────────┘     └──────────┘     └──────────┘
{One box per subsystem; label the arrows with the contract that crosses them.}

- **{Subsystem}:** what it owns, in one line. → [owning doc](../features/{feature}.md)

## Key flows

{At most two or three mermaid flow diagrams, at role level, for the flows everything else hangs off: request lifecycle, auth, the core domain operation.}

## Sources of truth

| Area | Canonical doc |
| ---- | ------------- |
| {area} | [{doc}](path) |
```