# Planned Diagrams for System Design (Chapter 3)

| Section | Diagram Type | Description |
|---|---|---|
| 3.2 Representing Music in AP | Code listing | JSON-LD examples showing the custom vocabulary extension (Track, Album as OrderedCollection, BLAKE3 hash embedding) |
| 3.3 Federation Model | Sequence diagram | Instance A uploads track → federates to instance B via Create activity → instance B's listener discovers it |
| 3.4 Content Distribution | Flow diagram | Upload → instance seeds via iroh → desktop client requests byte range → starts playback. Show NAT traversal (hole punch / relay fallback) |
| 3.5 Architecture | Crate dependency graph | Hexagonal layers: domain, application, adapters. Same style as thoughts/movies-diary Mermaid diagrams |
| 3.5 Architecture | Component diagram | High-level: backend server, iroh node, desktop client, PostgreSQL, NATS. Show how they connect |

## Rendering options

- **Mermaid → SVG/PNG**: Export with `mmdc` CLI, include as images in Typst
- **fletcher**: Typst package for in-document vector diagrams (nicer but more work)
- **draw.io**: Manual option if the above don't fit

## Reference material

- `/mnt/drive/dev/thoughts/ARCHITECTURE.md` — Mermaid crate dependency graph + domain ports class diagram
- `/mnt/drive/dev/movies-diary/architecture.mmd` — Mermaid hexagonal architecture (more detailed)