> ## Documentation Index
> Fetch the complete documentation index at: https://cona.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagram Conventions

> Rules for authoring and maintaining CONA architecture diagrams — diagram types, palette, node shapes, and the verification bar

# Diagram Conventions

These rules keep the architecture diagrams consistent, reviewable in pull requests,
and honest about what the code actually does.

## The verification bar

<Warning>
  **Every node and every edge must be traceable to a file.** If you cannot cite the import, call
  site, config entry, or schema line that proves a connection exists, the connection does not go on
  the diagram.
</Warning>

* Diagrams describe **what the code does**, not what it should do.
* When intended architecture and actual architecture differ, draw the actual one and
  add a callout naming the gap.
* Aspirational or planned components are marked with a dashed border and an explicit
  "planned" label, or they are left out.

## Which diagram type to use

| View                                 | Mermaid type      | Use when                                               |
| ------------------------------------ | ----------------- | ------------------------------------------------------ |
| Structure, containment, dependencies | `flowchart`       | Showing what contains or depends on what               |
| A flow over time across participants | `sequenceDiagram` | Showing a request, sync, or OAuth handshake            |
| Data model                           | `erDiagram`       | Showing tables and relations                           |
| Lifecycle of one entity              | `stateDiagram-v2` | Showing status transitions, e.g. document or job state |

## Orientation: optimise for a narrow column

The docs content column is roughly **700 px**. A diagram wider than that is scaled down,
and past about 2× the labels stop being readable. Height is free — the page scrolls.

**So: tall and narrow renders well; wide and short renders badly.**

Mermaid lays siblings out across the flow direction, so orientation is the main lever:

| Shape                           | Use            | Why                                                          |
| ------------------------------- | -------------- | ------------------------------------------------------------ |
| Fan-in / fan-out, 2–3 ranks     | `flowchart LR` | ranks become columns; the many siblings stack **vertically** |
| Sequential pipeline, many steps | `flowchart TB` | each step is its own rank, so it stays one node wide         |

Getting this backwards is the most common cause of an unreadable diagram. A six-node
chain in `LR` renders 2228 × 95 — a single unreadable ribbon. The same chain in `TB` is
narrow and legible.

**Check before committing.** Render the diagram and look at its `viewBox` width. Aim for
under \~1200; treat anything over \~1400 as needing rework.

## Readability limits

* **Maximum \~20 nodes per diagram.** Past that, split it or move detail into a table
  underneath. A context diagram that needs more than 20 is really two diagrams.
* **Use `subgraph` for boundaries** — a deployment boundary, a package, a trust
  boundary. Never use a subgraph purely for visual grouping.
* **Label every edge with its mechanism**, not just its direction: `HTTPS`,
  `gRPC`, `Prisma`, `activity`, `signal`, `webhook`, `OAuth redirect`.
* Line breaks inside node labels use `<br/>`.

## Palette

Colours are semantic — a reader should be able to tell what kind of thing a node is
without reading its label. Values derive from the CONA brand palette in
`docs.json`.

| Kind of node          | Fill      | Stroke    | Meaning                               |
| --------------------- | --------- | --------- | ------------------------------------- |
| CONA application      | `#dbe2fb` | `#3B56C5` | Something we deploy and run           |
| Shared package        | `#e8eafd` | `#4967E6` | A `@cona/*` workspace package         |
| Data store            | `#fde8e8` | `#c53b3b` | Postgres, Redis, blob storage         |
| Async / orchestration | `#e3f7ea` | `#2f9e5c` | Temporal workflows, workers, queues   |
| External provider     | `#fff4dd` | `#c98a12` | Third party we do not control         |
| Observability         | `#f0e8fd` | `#7c3bc5` | Axiom, Sentry, OpenTelemetry, PostHog |
| Actor / user          | `#eceff4` | `#64748b` | A human or external caller            |
| Boundary (subgraph)   | `#f8fafc` | `#94a3b8` | A container, not a thing              |

Applied with a `classDef` block so every diagram shares one definition:

```
classDef app fill:#dbe2fb,stroke:#3B56C5,color:#111827
classDef pkg fill:#e8eafd,stroke:#4967E6,color:#111827
classDef data fill:#fde8e8,stroke:#c53b3b,color:#111827
classDef async fill:#e3f7ea,stroke:#2f9e5c,color:#111827
classDef external fill:#fff4dd,stroke:#c98a12,color:#111827
classDef observability fill:#f0e8fd,stroke:#7c3bc5,color:#111827
classDef actor fill:#eceff4,stroke:#64748b,color:#111827
classDef boundary fill:#f8fafc,stroke:#94a3b8,color:#334155
```

<Warning>
  **`classDef` does not style subgraphs.** Mermaid renders an unstyled subgraph in its
  default pale yellow, which collides with the `external` colour and makes a container
  look like a node. Every subgraph needs an explicit
  `class <SubgraphId> boundary` line.
</Warning>

<Note>
  The `no-hardcoded-colors` rule applies to application UI code, where semantic design tokens exist.
  Mermaid has no token layer and requires literal hex values, so these declarations are the intended
  exception rather than a violation.
</Note>

An explicit `color:` is set on every class because Mermaid does not adapt label text
to the fill when the docs site switches between light and dark appearance.

## Naming

* File names are kebab-case and match the page slug: `core-domain-map.mdx`.
* Node identifiers are short PascalCase tokens (`WebApp`, `TemporalCloud`); the
  human-readable name lives in the label.
* Node labels use the real name from the code — the package name, the workflow
  function, the route path — so readers can grep for it.

## Page structure

Each diagram page follows the same shape:

1. **Frontmatter** — `title` and `description`.
2. **One-paragraph summary** of what the diagram covers and what it deliberately omits.
3. **The diagram.**
4. **A key or component table** listing each node with its source path.
5. **Notes** — non-obvious behaviour, known gaps, drift callouts.

## Keeping diagrams current

* Architectural changes update the diagram in the same pull request.
* The component tables carry source paths precisely so a reviewer can check whether a
  moved or deleted path invalidates a diagram.
* Treat a diagram that cannot be verified as stale and fix or delete it.