Architecture diagrams

Run pnpm deps:graph, then open dist/architecture/index.html. The viewer shows upstream Temporal only, using the local sibling temporalio/temporal checkout.

The boundary page opens as an import matrix; descendant pages open as node diagrams. View → Import matrix shows the same imports without crossing edges: rows import columns, and a dot marks a direct dependency between groups. Click a row to select its package and filter concerns. This is useful for the dense boundary graph and large module views; Node diagram retains spatial navigation for smaller areas. Both views omit imports collapsed inside a grouped node (available in the evidence JSON).

Choose an area or click a diagram node to drill down. At the lowest level, nodes open source. Locate a node centers and highlights a package and filters the glossary context. Source folders / modules provides revision-pinned GitHub and local links.

Graphs open fitted to the viewport and refit on resizing until you zoom or select a node. Small graphs use their natural height. Large graphs have a bounded viewport with +/− zoom, drag-to-pan, Ctrl/⌘-scroll zoom, Fit all, and Reset · 100%. Focus the diagram to use arrows, +/−, and 0. Colors identify service roles and infrastructure. Graphs contain only the selected repository's nodes and imports; there are no comparison placeholders.

Temporal concerns

At the root, the concerns table includes the entire catalog, including SDK-only concepts outside the visible server graph. It is an ownership glossary, not a list inferred from visible imports. The table separates concern, meaning, all contributing owners, and references.

The Temporal concerns panel follows the area, selected node, and drill-down fragment. Each entry includes a meaning, owning packages, Temporal docs, and a link into the comparison glossary. Selected context shows the count and jumps to this panel.

Clearing the selection restores the page area. Package selections include descendant owners; an unmapped subpackage can inherit its nearest mapped ancestor, explicitly labeled as broader context. Unknown paths show an empty state. Owner links locate the associated diagram node and open source where available. SDK concerns refer to separate SDK repositories.

The source is scripts/concerns.json. python3 scripts/architecture.py --concerns-markdown exports the same data as Markdown for the comparison document.

Generation

pnpm deps:graph
pnpm deps:matching
pnpm deps:graph --focus service/history/queues --level intra
pnpm deps:graph --upstream ~/src/github.com/temporalio/temporal
# Optional separate tiny-temporal view:
pnpm deps:graph --tiny-only --out dist/tiny-architecture

--focus can be repeated. --level boundaries|modules|intra chooses the printed entry page; all three levels are generated. Prerequisites are installed pnpm dependencies, Python 3.9+, Graphviz, and upstream's Go toolchain. Go collection uses -mod=readonly and does not edit upstream source. The default generation does not collect tiny-temporal.

Arrows represent source imports, not runtime RPC, injection, or deployment. Go units are packages, not individual files. External libraries, test files, and dedicated test-support packages are excluded; generated contracts and mocks embedded in production packages remain included. OS, architecture, and build flags affect Go collection. Aggregation can create apparent cycles.

scripts/architecture.py groups Go imports and renders them through dependency-cruiser's DOT reporter and Graphviz. Output includes HTML, SVG, DOT, original import evidence, and a manifest of revisions, working-tree status, and scope. Generated files stay under ignored dist/. The viewer works with file:// and makes no network requests.

pnpm deps:mermaid retains the compact tiny-temporal diagram. pnpm lint:boundaries enforces policy, and pnpm test:architecture validates graph transformations and page generation.

Tracing large graphs

Hover a node or edge to emphasize its immediate imports. Incoming edges are blue, outgoing edges orange, and unrelated elements fade. Right-click pins the highlight; Escape or clicking empty canvas clears it. Left-click still drills down. Selecting through Locate a node also pins the trace and shows readable Imported by / Imports lists. Those lists let you move between neighbors and open the selected node while keeping glossary filtering synchronized.

The diagram viewport can be resized vertically using its lower-right handle. Small graphs retain hierarchical Graphviz dot routing; graphs above 40 nodes use sfdp with overlap removal to avoid extremely wide hierarchical layouts. No nodes or edges are removed by this layout choice. The matrix remains available.

Interactive standalone opens the same linked SVG through the installed depcruise-wrap-stream-in-html tool, providing dependency-cruiser's stock hover, right-click pin, and Escape interactions. The integrated viewer adds directional colors, neighbor lists, and glossary synchronization. See the options reference and CLI documentation.

Hosted export

Run pnpm deps:hosted to generate dist/architecture-hosted/ for static hosting. This export uses GitHub source links, omits local filesystem links, and removes checkout paths from the manifest. Upload this directory rather than the local dist/architecture/ directory, which may contain older exports and Mac-specific links. Generation remains local; no CI runner is required.

The public viewer is hosted at https://temporal-architecture.pages.dev/ on Cloudflare Pages. The GitHub repository remains private.

To regenerate and publish a new snapshot locally, run pnpm deps:publish. This requires Wrangler installed and logged into the Cloudflare account containing the temporal-architecture project (wrangler login). Publication is manual; merging a PR does not deploy it. No CI runner is used.

Learning material and discussion preparation

pnpm deps:graph also renders the learning guide, Matching ownership source trail, comparison, searchable 207-entry glossary, and existing labs into the same output directory. Open learning.html; shared navigation connects every page. Glossary links stay inside the generated site. Markdown remains the authored source, and scripts/learning.json explicitly associates reading/labs with packages. Related reading is separate from ownership and follows node selection; it does not add artificial dependency edges or owner mappings.

The static build uses Marked with GitHub heading IDs, and bundles Mermaid locally for the existing sequence/flow diagrams. Pages work from file:// and static hosting. Source-code links into this private repository still require GitHub access. Diagram and reference revisions are recorded separately; reference claims are not automatically revalidated when the graph is regenerated.

Private discussion notes can be included explicitly in a local export:

pnpm deps:graph --private-guide /path/to/discussion.md

This adds a private guide link to learning.html. Keep the Markdown outside tracked files (for example under ignored dist/meeting-prep/). --hosted rejects --private-guide; a subsequent build without that option removes the known private guide page. pnpm deps:hosted uses a separate output directory and publishes only the explicit repository document list. Internal proposals must not be added to that public list.