← All guides

Guide

How to generate C4 diagrams from a GitHub repo

Point Eraser at a repository and get context, container and component diagrams you can edit, then keep them current on every pull request.

The C4 model is easy to agree with and tedious to apply to a system that already exists. Someone has to read the code, list what runs, and draw each level by hand.

This guide skips that step. You point Eraser at a repository, ask for each level, and get context, container and component diagrams you can edit. Then you set them to update when the code changes. The title says GitHub; the same steps work with GitLab and Azure DevOps.

Three C4 diagrams of one order processing system side by side: a system context diagram, a container diagram and a component diagram, each zooming in on one box of the level before Example: three levels of the same system, from one repository

Before you start

You need two things:

  • Access to Eraser
  • Access to the repository. A public repository needs no connection at all

Decide which levels you need before you generate anything. The C4 model’s own guidance is that “the system context and container diagrams are sufficient for most software development teams”.

One limit to keep in mind: Eraser reads the files in the repository. It cannot see runtime configuration, or services that live in other repositories. Treat the first result as a draft to check, not a finished record.

Step 1. Connect the repository

For a private repository, you install the Eraser GitHub App and choose which repositories it can read. That is the whole setup.

GitLab and Azure DevOps repositories connect with an access token instead. The docs have the steps for each.

Step 2. Generate the system context diagram

Start a new AI diagram, attach the repository, and ask for level 1:

Draw a C4 system context diagram for this repository. Show the system as
one box, the people who use it and the external systems it calls. Label
every relationship with what flows over it.

A C4 system context diagram: a customer and a support agent use an order processing system, which depends on a payment provider, an email service, a warehouse system and an identity provider Example: a system context diagram

Check the external systems first. A payment provider or an email service shows up in code as an SDK import or a URL in a config file. That makes it the easiest thing for a scan to miss, and it is the first thing a reader of a context diagram looks for.

Step 3. Generate the container diagram

Level 2 opens the system box and shows what runs inside it:

Draw a C4 container diagram. Treat each deployable unit or data store as a
container: web app, API, worker, database, queue. Label each with its
technology, and each relationship with its purpose and protocol.

Naming the files that define what runs gives a better result. If the repository has a compose file or an infrastructure folder, add it to the prompt.

A C4 container diagram of an order processing system: a web app calls an API, which writes to a database and publishes events to a message queue that a worker consumes, with a payment provider, an email service and a warehouse system outside Example: a container diagram

Check for one box per thing that runs or stores data, a technology on every box, and no line without a label.

Step 4. Add a component diagram where it earns its place

Level 3 opens one container. Point the prompt at that container’s code:

Draw a C4 component diagram for the API container, using the code in
services/api/.

A C4 component diagram of an API container: an orders controller calls an order service, which uses an order repository, a payment client and an event publisher that reach a database, a payment provider and a message queue Example: a component diagram of one container

Draw a component diagram only for containers that are complex or shared. For most of a system, level 2 is where people stop reading.

Skip level 4. The C4 model calls the code diagram “very much an optional level of detail” and does not recommend it for long-lived documentation, because an IDE can generate it on demand.

The same approach covers C4’s supporting diagrams: a deployment diagram from your Terraform or Kubernetes files, and a dynamic diagram as a sequence diagram of a single request.

Refine the diagrams

  • Use your team’s names. Rename boxes to what people call them, not what the folders are called.
  • Keep names identical across levels. A container on level 2 should be the same box that level 3 opens up.
  • Fix by prompting or by hand. Ask for a change in words, or edit the diagram directly.

Keep them current

A C4 diagram is only useful while it matches the code. Eraserbot handles that. You give it a prompt and the files to watch.

A pull request changes watched files, Eraserbot redraws the diagram and posts it as a comment on the pull request, and the saved diagram updates on merge What happens when a pull request touches the files a diagram depends on

When a pull request changes those files, Eraserbot redraws the diagram and posts it as a comment within a minute or two. The saved diagram updates when the pull request merges. It works with GitHub and GitLab.

On GitHub you can also commit the diagram file to the repository. That keeps the diagrams next to the code they describe, which is the point of diagram as code.

Other ways to get C4 diagrams

  • Model it in Structurizr. The Structurizr DSL is a text language for defining one architecture model, from which every view is drawn. The C4 site lists modelling tools as its recommended kind. It is the right choice when you want a single source of truth. Someone writes and maintains the model by hand.
  • Write the diagrams as text. C4-PlantUML and Mermaid’s C4 syntax keep diagrams in the repository and render in Markdown. Both are written by hand, and Mermaid’s page lists unfinished features and a layout that is not fully automatic.
  • Ask your coding agent. An agent such as Claude Code or Cursor can read the repository and draw through a diagramming MCP server. Best diagramming MCP servers in 2026 compares them.
  • Draw them by hand. draw.io has a C4 shape library. That suits a workshop. Every level is a separate drawing to maintain afterwards.

Best C4 model tools in 2026 compares the tools built for C4. For a wider look at text-based tools, see Best diagram-as-code tools in 2025.

FAQ

Can AI generate C4 diagrams from code?

Yes, for the context, container and component levels. It reads the repository and drafts each one. The draft needs a check by someone who knows the system, mostly for external systems and anything defined outside the repository.

Which C4 levels should I generate?

Context and container for every system. Add a component diagram only where a container is complex or shared, and leave the code level to your IDE.

Does this work with private repositories, GitLab or Azure DevOps?

Yes. Private repositories need to be connected first. GitHub, GitLab and Azure DevOps are all supported, and a public repository needs no connection.

How do I keep C4 diagrams in sync with the code?

Set up Eraserbot on the diagrams that matter, with the files they depend on. It redraws each one when a pull request changes those files.

Can I store the diagrams in the repository?

Yes, on GitHub. Eraser can commit the diagram files to the repository and pull them back in.

Where to go next

To try a level without connecting anything, the C4 diagram generator draws one from a description. The glossary’s C4 model page covers the four levels, the notation and the common mistakes.