---
name: archdoc
description: Generate docs/architecture.pdf — a concise document covering the architecture, workflow, dependencies, and operational environment, embedding the SVGs produced by the diagrams skill. Use when the user asks for an architecture document, design doc, or system overview PDF.
---

# Architecture document generator

Produce `docs/architecture.pdf`: concise (target 5-8 A4 pages), current, and
visual. The three diagrams from the `diagrams` skill are the backbone; the
prose fills in what pictures can't say. Never describe architecture from
memory — read the code first.

## Process

1. **Freshen the diagrams.** If `docs/diagrams/temporal.svg`, `infra.svg`, or
   `flow.svg` are missing — or the workflow/worker/chart files changed since
   they were generated — run the `diagrams` skill first. This document must
   embed diagrams that match the code it describes.
2. **Gather facts** from the same sources of truth the diagrams skill lists
   (workflows.py, activities.py, worker.py, shared.py, helm values,
   .env.example, Makefile), plus `requirements.txt`, `requirements-dev.txt`,
   `VERSION`, and `tests/`.
3. **Rasterize the diagrams** for embedding with cairosvg at print sharpness
   (`scale=1.4`) into the session scratchpad — not ImageMagick (it drops SVG
   features). Embed the PNGs, not the SVGs (WeasyPrint's own SVG support is
   partial).
4. **Author one self-contained HTML** in the scratchpad. Sections, in order:
   - Overview: what the system does, one paragraph + the artifact outputs.
   - Temporal architecture: embed temporal.png; prose on queues/pools/caps
     and why (per-resource quota protection), worker roles via WORKER_QUEUES.
   - Execution flow: embed flow.png; prose on ordering, parallelism,
     retry/heartbeat/resume behavior, fail-fast validations.
   - Cloud infrastructure: embed infra.png; prose on the resource group
     contents, images, public/private storage split.
   - Dependencies: Azure services table + Python packages (runtime and dev).
   - Operational environment: endpoints (Temporal frontend DNS, UI via
     admin.sh), config/secrets model (.env locally, helm secrets.yaml to
     Kubernetes Secrets, runtime listKeys, API-key gate), scaling knobs
     (replicas x per-pod caps), and the day-to-day commands (make targets,
     test.sh, admin.sh, local worker/start).
   Style: match output-template.html's look (same palette #16324f/#2a6fb0,
   Helvetica, A4 @page with page numbers). Full-width images, each with a
   short caption. Keep prose tight — bullets over paragraphs.
5. **Render** with WeasyPrint to `docs/architecture.pdf`. Include the project
   VERSION and generation date on the title header.
6. **Verify**: the file starts with `%PDF`; rasterize 2-3 pages with
   ghostscript (`gs -sDEVICE=png16m`) and visually inspect for overflowing
   text, blank/missing images, or awkward page breaks. Fix and re-render
   before finishing.