Trazo
Architecture docs that can't go stale.
Trazo extracts your system's structure from code and infrastructure files, generates Mermaid diagrams and flags architecture changes on every pull request.
It is a personal, open-source project of mine: it wasn't built for or with any company.
- Type
- Personal project · no company
- Role
- Author & maintainer
- Focus
- Developer tooling · Architecture as code · CI
Diagrams rot
Someone draws an architecture diagram, the system changes, and a few weeks later the diagram is wrong and nobody trusts it.
Trazo takes a different approach: the diagram is never drawn by hand and never guessed.
Generated from the files that already define your system
The structure comes from parsing the files that already describe the system, and it is re-checked on every pull request, so a change to the architecture shows up in review instead of being discovered months later.
- Deterministic. Structure comes from parsing files, not from a language model, so the diagram can't invent things that aren't there.
- Lives in the PR. Reviewers see which components and dependencies a change adds or removes, next to the code.
- No server, no account. It reads files in your repository and runs locally, in any CI, or as a GitHub Action that needs nothing beyond a workflow file.
An example
Given a Docker Compose file with six services, Trazo generates the diagram below.
Databases, caches and queues are recognised from their image and drawn with their own shape and border colour: blue services, orange databases, teal caches, yellow queues. A component added by a pull request is bordered green instead.
%%{init: {'theme':'base','themeVariables':{'lineColor':'#6b7280'}}}%%
flowchart LR
n_api["api"]
n_cache(["cache"])
n_db[("db")]
n_queue>"queue"]
n_web["web"]
n_worker["worker"]
n_api --> n_cache
n_api --> n_db
n_api --> n_queue
n_web --> n_api
n_worker --> n_db
n_worker --> n_queue
classDef kind_service fill:#e5effa,stroke:#2a78d6,stroke-width:2px,color:#1a1a1a
class n_api,n_web,n_worker kind_service
classDef kind_database fill:#fdede7,stroke:#eb6834,stroke-width:2px,color:#1a1a1a
class n_db kind_database
classDef kind_cache fill:#e4f5ef,stroke:#1baf7a,stroke-width:2px,color:#1a1a1a
class n_cache kind_cache
classDef kind_queue fill:#fdf4e0,stroke:#eda100,stroke-width:2px,color:#1a1a1a
class n_queue kind_queueWhat it reads
Today Trazo reads Docker Compose files (services, depends_on and links) and Kubernetes manifests.
In Kubernetes, Deployments, StatefulSets, DaemonSets, Jobs, CronJobs and Pods each become a component, and an Ingress is linked to the workload its backend Service selects.
Where it runs
GitHub Action
Comments on pull requests that change the architecture and updates that same comment on every push. Pull requests that don't touch the architecture stay quiet.
Bitbucket Pipelines
The same behaviour as a pipeline step: quiet when nothing changed, one comment kept up to date otherwise.
Command line
Prints the architecture as Mermaid, JSON or a full Markdown document, and reports what changed since a git revision, reading the base straight from git without touching the working tree.
A live ARCHITECTURE.md
A workflow regenerates the document on every push to main and commits it back when it changed, so nobody has to remember to update it.
How it's built
A small TypeScript monorepo. The flow is: files, extractor, architecture model, diff against the base, and finally a Markdown report with a Mermaid diagram.
Adding a format means writing one extractor, a check on the path plus a function that returns components and dependencies, registering it and covering it with a test. Nothing else needs to change.
@edgaragg/trazo-core
The library: extractors that read files into a model, model diffing, and Mermaid and Markdown rendering. It never touches the filesystem, so it is easy to test and reuse.
@edgaragg/trazo-cli
The command line. Finds files, reads them from disk or from git, and calls core. It also carries the Bitbucket Pipelines step: the same thin layer, aimed at Bitbucket's API instead of GitHub's.
@edgaragg/trazo-action
The GitHub Action, kept private because GitHub runs it straight from the repository: a thin layer over the CLI that posts the comment. It ships as a committed bundle, rebuilt by a pre-commit hook and verified in CI.
Where it is today
Trazo is early, but it works end to end.
Only declared relationships are detected, in keeping with never guessing: a service that finds its database through an environment variable is not linked to it.
On the roadmap:
- CloudFormation and SAM templates, including AWS Amplify backends.
- A check command that fails a build when the architecture changed without an update to the docs.
- An ignore file to skip paths that are illustrative rather than real.
- Optional LLM-written descriptions on top of the extracted model, bringing your own API key.
Contact
Let's talk.
Open to conversations about architecture, platforms and teams. The fastest way to reach me is LinkedIn.
