# Architecture Diagram Set

**System:** _______________  **Version:** 0.1  **Date:** _______________
**Owner:** _______________

> Four diagrams at decreasing zoom. Most teams need the first two; draw the
> third only for components with real internal structure.
> Diagrams below use Mermaid — renders in most Markdown tools, and it is text,
> so it diffs in version control instead of rotting as a stale image.

---

## Conventions — agree these first

**Every arrow must say what it means.** An unlabelled arrow is the single most
common defect in architecture diagrams: nobody knows whether it means "calls",
"sends data to", "depends on", or "sometimes reads from". Label direction and
protocol.

| Convention | Rule |
|---|---|
| Arrow direction | Points the way the **request** travels, not the data |
| Arrow label | Verb + protocol, e.g. "reads via HTTPS/JSON" |
| Boxes | One responsibility each; if you cannot name it in three words, split it |
| Colour | Never the only carrier of meaning — some readers cannot see it |
| Trust boundaries | Drawn explicitly; this is where security review focuses |
| Anything external | Visually distinct from what you control |

---

## 1. Context — who uses this and what it talks to

> One page. The diagram you show a stakeholder. No internal detail.

```mermaid
graph TD
    U[Customer] -->|uses via browser| S[Your System]
    A[Internal Staff] -->|administers| S
    S -->|reads/writes via HTTPS| P[Payment Provider]
    S -->|sends email via SMTP| E[Email Service]
    S -->|queries via JDBC| D[(Core Database)]
```

**Actors:**

| Actor | Type | What they do |
|---|---|---|
| | Person / System | |

## 2. Containers — the deployable parts

> Applications, services, databases, stores. What runs where, and how the parts
> communicate. This is the diagram engineers use most.

```mermaid
graph TD
    subgraph "Trust boundary: our infrastructure"
        W[Web Application<br/>static HTML/CSS/JS]
        A[API<br/>PHP 8.3]
        DB[(Database<br/>MySQL)]
        Q[Job Runner<br/>cron]
    end
    U[Browser] -->|HTTPS| W
    W -->|HTTPS/JSON| A
    A -->|SQL over local socket| DB
    Q -->|SQL| DB
    A -->|HTTPS| X[External API]
```

| Container | Technology | Responsibility | Scaling | Data held |
|---|---|---|---|---|
| | | | | |

## 3. Components — inside one container

> Only for containers with genuine internal structure. Skip otherwise.

```mermaid
graph LR
    R[Router] --> C[Controller]
    C --> S[Service Layer]
    S --> Rp[Repository]
    Rp --> DB[(Database)]
    S --> Ext[External Client]
```

## 4. Deployment — where it physically runs

```mermaid
graph TD
    subgraph "Host: production VPS"
        N[nginx :443]
        F[php-fpm pool]
        M[(MySQL :3306 localhost only)]
    end
    I[Internet] -->|TLS 1.3| N
    N --> F
    F --> M
```

| Environment | Host | Sizing | Notes |
|---|---|---|---|
| Production | | | |
| Test | | | |

---

## Data flow and classification

> What moves where, and how sensitive it is. This drives security decisions.

| Data | Classification | From | To | Protection |
|---|---|---|---|---|
| | Public / Internal / Confidential / Personal | | | |

## Trust boundaries

| Boundary | What crosses it | Control |
|---|---|---|
| Internet → application | | TLS, authentication, rate limit |
| Application → database | | Network isolation, least-privilege account |
| Application → third party | | |

## Key decisions

> Record the decision AND what you rejected. Six months later, the rejected
> options are the valuable part — they stop someone re-litigating a settled
> question, or repeating a mistake.

| # | Decision | Alternatives rejected | Why | Date |
|---|---|---|---|---|
| 1 | | | | |

## Known constraints and debt

| Item | Impact | Plan |
|---|---|---|
| | | |