Topogram’s structured graph: concept and implementation

Audience: Organizations who maintain product specs, API contracts, and delivery artifacts and want those to stay aligned with code and process.

Reading time: ~4 minutes.

What this post covers: What Topogram means by a structured graph, how that differs from informal documentation, and how the implementation supports validation, querying, and generation — without requiring you to adopt every workflow on day one.

Learn more in the Topogram repository
Content Approval Proof
Brownfield Content Approval Proof

Why a graph, and why “structured”?

Product knowledge naturally looks like a graph: features depend on services, screens consume APIs, requirements spawn tasks, and verification ties back to acceptance criteria. In many organizations, that graph exists only in people’s heads, or across loosely linked files and tickets. Tools cannot reliably traverse what was never declared.

Topogram’s approach is to make that graph explicit and typed.

You maintain a workspace (topo/) where you express intent using Topogram statements (.tg files) and supporting markdown. A parser normalizes everything under topo/ — regardless of folder layout — into one graph the CLI can validate, query, and hand off to generators or agents.

“Structured” here means: kinds of nodes, declared relationships, and constraints the tool can enforce. It is not the same as “we use consistent headings in Confluence.”

Concept: intent versus realization

Topogram separates two layers:

Durable intent — What the product is and must do: entities, capabilities, rules, user journeys, UI/API/DB/CLI contracts as projections, SDLC objects (for example pitches, requirements, acceptance criteria, tasks), and decisions.
Stack realization — How a specific runtime or codebase implements that intent (web app, API service, database, mobile surface, and so on), driven by project configuration and generator bindings.

Keeping intent in a single, checkable model reduces the classic failure mode where the wiki, the OpenAPI file, and the implementation each tell a slightly different story.

What goes in the graph

Common statement kinds include domain vocabulary (actor, role, term, domain), structural modeling (entity, shape, enum), behavioral and quality layers (rule, capability, orchestration, verification), UI semantics (widget), journey (ordered steps and branches), projections (contracts and surfaces), decisions, and — when SDLC is adopted — linked lifecycle artifacts.

Journeys are worth highlighting for software teams: they can represent sequences and alternatives as graph-native structure, so procedural truth is not trapped only in prose.

Projections describe surfaces such as UI contracts, web/iOS/Android surfaces, API contracts, database contracts, and CLI surfaces. That gives downstream tools a normalized contract instead of each stack inventing its own parallel spec.

Implementation from files to consumable output

At a high level, the pipeline is:

Stage	Role
Authoring	Humans and agents edit `.tg` (and markdown where appropriate) under `topo/`. `topogram.project.json` declares workspace paths, output ownership (generated vs maintained), topology runtimes, and how generators bind to projections.
Ingestion	The parser flattens the directory tree into one graph; folder structure is organizational, not semantic identity.
Validation	The CLI checks the model so errors surface before they propagate to generated artifacts or reviews.
Consumption	Teams run targeted queries (for example task slices, SDLC packets, proof-gap reports) and bind generators to normalized contracts.

Agents are guided toward read-only briefings and query packets rather than scanning the entire repository — the graph makes “just the relevant subgraph” a first-class output.

What this gives documentation and engineering teams

Traceability: Links between requirements, criteria, tasks, and verification can live in the same model you validate — not only in prose or ticket comments.
Discoverability: Queries return consistent, structured views of the graph instead of duplicating context in chat or ad-hoc exports.
Contract alignment: API, UI, data, and CLI intent share a backbone; stacks realize projections instead of re-deriving product meaning locally.
Operational honesty: Missing edges and incomplete intent show up as validation or query gaps, which is easier to prioritize than silent wiki decay.

Summary

Topogram’s structured graph is not a diagramming exercise; it is an authored, typed model of product and system intent under topo/, normalized by the tool into contracts and queries that generators and SDLC workflows can share.

If you are evaluating it, start with a small slice: one capability, one projection, and one journey — then use the CLI checks and queries to see whether your team’s implicit graph matches what you declare.