pal-e-docs

Architecture Template

template-architecture Template

active template
Project

Architecture Template

Every project gets three architecture diagram notes — one per facet. These are separate notes (not inline on the project page) so diagrams evolve independently and stay lean. Together the three notes answer what (domain), when (data flow), and where (deployment).

The Triplet

Facet Slug Pattern Mermaid Type Question It Answers
<strong>Domain Model</strong> <code>arch-domain-{project}</code> <code>erDiagram</code> What are the business entities and how do they relate?
<strong>Data Flow</strong> <code>arch-dataflow-{project}</code> <code>sequenceDiagram</code> How does information move through the system at runtime?
<strong>Deployment</strong> <code>arch-deployment-{project}</code> <code>graph TB</code> Where do services run and how do they connect?

Required Sections

All three variants follow the same section skeleton. The h2 title and Diagram content differ by facet; Components, Key Decisions, and Related are universal.

Section Order

  • h2 Title — {Facet}: {project-display-name} (e.g., "Domain Model: westside-basketball")
  • Diagram — Mermaid code block
  • Components — table: Component | Purpose | Notes
  • Key Decisions — bulleted list of architectural decisions
  • Related — links to siblings, project page, SOPs
Additional sections are allowed between Key Decisions and Related when the facet warrants it (e.g., a Domain Model note might add a "Rolling Window Logic" section with SQL examples). The five required sections must always be present in order.

Facet Guidance

Domain Model

  • Diagram type: erDiagram
  • Entities map to database tables, API resources, or domain objects
  • Include attribute types and PK/FK annotations
  • Relationship labels describe the verb (e.g., USER ||--o{ RECEIPT : "captures")
  • Components table lists each entity with its purpose and implementation notes (e.g., "SQLAlchemy model", "Keycloak JWT — no local table")
  • Key Decisions focus on: why entities exist, what was intentionally excluded, denormalization choices

Data Flow

  • Diagram type: sequenceDiagram
  • One sequence diagram per major user flow or system interaction
  • Participants are actors (User, Admin) or services (API, DB, Keycloak, MinIO)
  • Multiple flows allowed — each gets its own h3 subsection under Diagram (e.g., "Flow 1: Scan Receipt")
  • Components table lists each participant with its purpose and connection details
  • Key Decisions focus on: async vs sync, error handling strategy, auth flow choices

Deployment

  • Diagram type: graph TB
  • Nodes are infrastructure components: pods, services, databases, ingress, storage
  • Use Mermaid subgraphs to group by namespace or tier (e.g., subgraph k3s)
  • Include external dependencies (Tailscale, DNS, Harbor, CI)
  • Components table lists each service with its purpose, namespace, and connection notes
  • Key Decisions focus on: why this hosting model, scaling strategy, secret management

Naming Convention

Field Value
Slug <code>arch-{facet}-{project}</code> where facet is <code>domain</code> | <code>dataflow</code> | <code>deployment</code>
Title <code>{Facet Display}: {project-display-name}</code> (e.g., "Domain Model: westside-basketball")
Note type <code>architecture</code>
Tag <code>architecture</code> (topic tag) + <code>active</code>
Status <code>active</code>, <code>draft</code>, or <code>archived</code>
Project Same project as the project page they belong to
Parent None — arch notes are children of the project (via project association), not via parent_slug

Relationship to Projects and Boards

  • One triplet per project. Every project page references its three arch notes in its Architecture section.
  • Children of the project. Arch notes belong to the same project as the project page. They are not children of the project page note (no parent_slug); the project association is the link.
  • Referenced by boards. Board tickets carry arch: labels that reference components defined in these diagrams. The arch: label values come from the Components table.
  • Traceability triangle. User Story <> Architecture <> Board Item. The arch notes are the Architecture vertex. Every board item's arch: label points into one of the three diagrams.

Existing Examples

Project Domain Data Flow Deployment
westside-basketball <code>arch-domain-westside-basketball</code> <code>arch-dataflow-westside-basketball</code> <code>arch-deployment-westside-basketball</code>
mcd-tracker <code>arch-domain-mcd-tracker</code> <code>arch-dataflow-mcd-tracker</code> <code>arch-deployment-mcd-tracker</code>
pal-e-pac <code>arch-domain-pal-e-pac</code> <code>arch-dataflow-pal-e-pac</code> <code>arch-deployment-pal-e-pac</code>
  • template-project-page — where architecture notes are referenced from
  • template-board — board notes reference parent arch diagrams
  • template-ticket — traceability triangle: story + arch + type labels
  • convention-architecture-ids — how arch: labels are derived from diagram components
  • sop-board-workflow — board column semantics