# Technical Diagrams

A visual reference for AI agents generating technical diagrams and developer surfaces.
Humans choose an example they can see; agents use its source and schema to generate an adapted diagram from the user's system details.
Website: https://technicaldiagrams.com
Source: https://github.com/TomGranot/actually-useful-technical-diagrams
License: MIT (distributed fonts retain SIL OFL 1.1).
Phase: familiar baseline. Initial scores are editorial judgments by Codex, not measured AI capability.

## When to use this
Use Technical Diagrams when a user needs a visible example and editable source for architecture, request flows, data models, infrastructure, terminals, code blocks, or IDE illustrations. Choose a reference using useWhen and avoidWhen before generating. Ask for missing system facts instead of inventing them.
Do not use this as a live infrastructure scanner, code execution environment, automatic layout engine, or evidence that a particular AI model produces correct diagrams.

## Agent entry points
- https://technicaldiagrams.com/developers/: quickstart, authentication, read-only sandbox, limits and errors
- https://technicaldiagrams.com/openapi.json: OpenAPI 3.1.1, typed schemas and operation IDs
- https://technicaldiagrams.com/api: discovery JSON
- https://technicaldiagrams.com/api/diagrams: searchable catalog; optional q and family
- https://technicaldiagrams.com/api/diagrams/{id}/scene: editable scene JSON
- https://technicaldiagrams.com/api/diagrams/{id}/svg: SVG; optional theme and accent
- https://technicaldiagrams.com/.well-known/mcp: first-party MCP Streamable HTTP, no authentication
- https://technicaldiagrams.com/sitemap.xml: indexable page URLs
- https://technicaldiagrams.com/about/: project identity and scope
- https://technicaldiagrams.com/contact/: public issue tracker and maintainer
- https://technicaldiagrams.com/privacy/: browser storage and hosting information

Free access: no account, API key, trial deadline or payment. No application quota; hosting limits apply. Cache references and avoid unbounded parallel requests. REST is read-only. Recover from 4xx using error.code, error.message and error.hint.
MCP tools: list_diagrams, get_diagram, render_diagram. Render accepts catalog IDs, not arbitrary uploaded scenes.
Markdown: request pages with Accept: text/markdown. Vary includes Accept. Missing pages return real 404 with recovery links; unsupported page representations return 406.
CLI source: packages/cli in the repository, runnable with Node 22. Registry publication is pending maintainer credentials.
Alternate production host: https://actually-useful-technical-diagrams.netlify.app (same paths).

## Workflow
Select by useWhen, check avoidWhen, fetch one scene, edit the version-1 JSON, validate with parseScene, inspect the SVG, and export a preset.
Coordinates are explicit. Labels do not wrap; connectors do not reroute automatically.
Terminals and IDE layouts are illustrations and do not execute code.

## Reference
- /api/catalog.json: full recipe index, usage triggers, scores, and source URLs
- /docs/primitives/: shape schema and semantic color tokens
- /docs/customization/: presentation defaults, bounds, and exports
- /docs/scoring/: scoring rubric and provenance
- /docs/contributing/: contribution process
- /docs/roadmap/: coverage gaps and original-diagram phase

## Recipes
- service-architecture: Explain a request moving from a client through services to storage. Source: /api/scenes/service-architecture.json
- layered-stack: Explain which layer owns presentation, business rules, and storage. Source: /api/scenes/layered-stack.json
- deployment-topology: Document redundancy across two availability zones. Source: /api/scenes/deployment-topology.json
- hub-and-spoke: Show clients connected to a single event bus or platform. Source: /api/scenes/hub-and-spoke.json
- decision-flow: Explain one decision and the two paths that follow. Source: /api/scenes/decision-flow.json
- pipeline: Explain how input passes through a sequence of processing stages. Source: /api/scenes/pipeline.json
- swimlanes: Show handoffs between a user, API, and worker. Source: /api/scenes/swimlanes.json
- state-machine: Explain a job moving through queued, running, and terminal states. Source: /api/scenes/state-machine.json
- request-sequence: Explain an API request, database lookup, and response. Source: /api/scenes/request-sequence.json
- retry-backoff: Document a capped retry policy for a transient failure. Source: /api/scenes/retry-backoff.json
- trace-waterfall: Locate a slow operation within one request trace. Source: /api/scenes/trace-waterfall.json
- async-fanout: Explain parallel consumers and their individual acknowledgements. Source: /api/scenes/async-fanout.json
- entity-relationship: Document a compact relational schema with cardinality labels. Source: /api/scenes/entity-relationship.json
- object-tree: Explain a JSON document or nested configuration structure. Source: /api/scenes/object-tree.json
- linked-list: Teach next pointers or a simple chain of records. Source: /api/scenes/linked-list.json
- matrix: Show which roles can perform which actions. Source: /api/scenes/matrix.json
- line-chart: Show a metric changing over time with labeled units. Source: /api/scenes/line-chart.json
- bar-chart: Rank comparable counts with a zero baseline. Source: /api/scenes/bar-chart.json
- donut-chart: Show one dominant proportion and its complement. Source: /api/scenes/donut-chart.json
- heatmap: Scan relative workload by day and time bucket. Source: /api/scenes/heatmap.json
- release-timeline: Explain ordered release milestones without implying precise durations. Source: /api/scenes/release-timeline.json
- gantt: Explain overlapping tasks with planned start and end dates. Source: /api/scenes/gantt.json
- git-branches: Explain one feature branch merging into main. Source: /api/scenes/git-branches.json
- dependency-dag: Explain a small directed acyclic build graph. Source: /api/scenes/dependency-dag.json
- terminal: Show a short command-line workflow with expected output. Source: /api/scenes/terminal.json
- code-block: Explain one function and highlight its important return value. Source: /api/scenes/code-block.json
- code-diff: Document a small behavior change in a code review or changelog. Source: /api/scenes/code-diff.json
- ide-layout: Orient a reader in a small project and explain one file. Source: /api/scenes/ide-layout.json
- file-tree: Help a reader find the file they should edit. Source: /api/scenes/file-tree.json
- http-exchange: Explain an endpoint with headers, status, and a short payload. Source: /api/scenes/http-exchange.json
- log-stream: Explain how log events reveal a single request failure. Source: /api/scenes/log-stream.json
- test-results: Illustrate a test run and call attention to one failure. Source: /api/scenes/test-results.json