AI System Architecture C4 Diagram from Code

Almost every codebase has an architecture diagram somewhere, and almost every architecture diagram is out of date. The diagram was drawn at launch, when the system had three services and the data flow was simple. The system now has eight services, two of them are deprecated but still running, the data flow has grown a queue and a cache and an analytics pipeline, and nobody has updated the diagram because the cost of updating it (open Lucid, find the right tab, hope the link still works) outweighs the immediate value of doing so. The diagram persists as a historical artifact rather than a current map, and the team uses it for onboarding the way you use a tourist map: it gets you in the right neighborhood, but you do not navigate by it.

An architecture diagram that is generated from the codebase rather than drawn from memory has a different update story. When a new service joins, the diagram updates by re-running the generator. When a service is deprecated, it disappears from the diagram. When the data flow changes, the diagram reflects the new flow. The discipline is the C4 model (context, containers, components, code) which produces a small number of clearly-scoped diagrams rather than one cluttered all-in-one. The /atlas-map skill encodes the discipline: read the codebase, produce the C4 Level 1 (system context) and Level 2 (container) diagrams in Mermaid, and let the team regenerate them whenever the system changes.

Why generalist AI produces stale or generic diagrams

Ask Cursor or ChatGPT for an architecture diagram and you get a generic three-tier diagram with boxes labeled "Frontend," "API," and "Database." The diagram is technically a representation of your system in the same way a stick figure is a representation of a person. It does not show the actual services, the actual data stores, the actual external integrations, or the actual data flows. Without that specificity, the diagram is decoration rather than navigation. The team cannot use it to onboard a new engineer because it does not show what they need to know.

The other failure mode is the cluttered diagram. A diagram that tries to show every service, every database, every queue, every external integration, every internal data flow, and every observability hook in one image is the diagram nobody reads. The C4 model exists specifically to address this: each level zooms in on a specific concern, with explicit names for what shows up at each level. The Level 1 diagram answers "what is this system and what does it talk to"; the Level 2 diagram answers "what services and data stores does it have"; the Level 3 diagram (when needed) answers "how is one service structured internally." Each diagram is small and useful; the all-in-one diagram is neither.

What useful architecture mapping requires

A useful architecture map has three properties. First, it is generated from the actual codebase. The services in the diagram are the services in the repository; the data stores are the ones the services connect to; the external integrations are the ones the code calls. Generated from code, the diagram cannot lie about what is running. Second, it follows the C4 levels: a Level 1 context diagram showing the system as a single box with users, external systems, and data flows; a Level 2 container diagram showing the services and data stores inside the system. Third, it is regenerable: when the codebase changes, running the generator again produces an updated diagram without redrawing anything.

The C4 levels are not arbitrary. Level 1 is what you show a non-engineering stakeholder asking "what does this system do." Level 2 is what you show a new engineer asking "how is the system put together." Level 3 is what you show an engineer joining a specific service asking "how does this service work internally." Different audiences, different diagrams, all kept in sync because they come from the same source. /atlas-map produces Level 1 and Level 2 by default; Level 3 is generated per service on demand.

How /atlas-map works

Step one: read the codebase

When invoked, /atlas-map reads the repository to identify the services (packages, apps, microservices), the data stores (database connection strings, ORM configurations, S3 buckets), the queues and caches, and the external integrations (HTTP clients, SDK initializations). The inventory is the input to the diagrams; everything that appears on the map is grounded in something the code actually does.

Step two: build the Level 1 context diagram

The Level 1 diagram shows the system as a single box with arrows to and from external actors and systems. Customers, internal users (admin, support), payment providers, email providers, third-party integrations. The arrows are labeled with the type of interaction (HTTP, webhooks, scheduled syncs). The diagram is small (typically 8-15 nodes) and answers the "what does this system talk to" question that stakeholders and new engineers both have.

Step three: build the Level 2 container diagram

The Level 2 diagram zooms inside the system box and shows the containers (services, databases, queues, caches) that comprise it. Each container is labeled with its responsibility and its technology (Postgres, Redis, NestJS API, Next.js frontend). The arrows show the actual connections: which services read from which database, which services publish to which queue, which services call which others. The diagram is medium-sized (typically 10-20 nodes) and answers the "how is the system put together" question.

Step four: written descriptions per node

Each node in each diagram has a short written description: what the container does, what data it owns, who calls it. The descriptions live alongside the diagrams in the repository so they are version-controlled and reviewable. The combination of diagram and description is what makes the map navigable: the diagram orients the reader spatially, the descriptions answer the questions the diagram raises.

Tonone's /atlas-map skill produces C4-style architecture diagrams in Mermaid, generated from the actual codebase so the diagrams stay in sync with what is running.

When to use /atlas-map, and when not to

/atlas-map is the right call when needing a visual architecture overview for a design review, an onboarding session, or a stakeholder conversation. The skill is also the right call when an existing diagram has drifted from the actual system and needs to be reconstructed accurately. Regenerate the diagrams whenever the system changes meaningfully (new service, removed service, significant data flow change).

Skip the skill for ad-hoc whiteboard sketches during a design conversation; the value of /atlas-map is in producing the persistent artifact. For full onboarding documentation that includes the diagram, /atlas-onboard is the right call. For Architecture Decision Records that explain the choices visible in the diagram, /atlas-adr produces them.

A worked example: C4 for a billing platform

Suppose the brief is: produce the architecture map for the billing platform. Run /atlas-map.

# C4 Level 1: Context

```mermaid
flowchart TB
  CUSTOMER([Customer])
  ADMIN([Internal admin])
  STRIPE[Stripe]
  EMAIL[SendGrid]
  CRM[HubSpot]

  subgraph BILLING [Billing Platform]
    direction TB
    SYS[(All services)]
  end

  CUSTOMER -->|HTTPS| BILLING
  ADMIN -->|HTTPS| BILLING
  BILLING -->|Charge API| STRIPE
  STRIPE -->|Webhooks| BILLING
  BILLING -->|Send email| EMAIL
  BILLING -->|Sync customer data| CRM
```

## Description (Level 1)
- Customer: end users who view invoices and pay subscriptions.
- Internal admin: support and ops staff using the back-office tool.
- Stripe: payment provider; outbound charge API + inbound webhooks.
- SendGrid: transactional email for invoice notifications.
- HubSpot: CRM that syncs customer state from the billing platform.

# C4 Level 2: Containers

```mermaid
flowchart LR
  subgraph BILLING [Billing Platform]
    WEB[web<br/>Next.js]
    ADMIN[admin<br/>Next.js]
    API[billing-api<br/>NestJS]
    WH[webhook-handler<br/>Express]
    CRON[dunning-cron<br/>BullMQ]
    DB[(billing-db<br/>Postgres)]
    REDIS[(redis<br/>cache + queue)]
  end

  CUSTOMER([Customer]) --> WEB
  ADMIN_USER([Internal admin]) --> ADMIN
  WEB --> API
  ADMIN --> API
  API <--> DB
  API <--> REDIS
  CRON --> DB
  CRON --> STRIPE_EXT[Stripe]
  WH --> DB
  STRIPE_EXT -- Webhooks --> WH
```

## Description (Level 2)
- web: customer-facing app (Next.js, served from Vercel)
- admin: internal tool for support and ops
- billing-api: REST API; owns invoice and subscription state
- webhook-handler: idempotent ingest of Stripe events
- dunning-cron: scheduled job; retries failed payments per policy
- billing-db: source of truth for billing state (Postgres)
- redis: cache for read paths and job queue for dunning

Two diagrams, each scoped to its level, with descriptions alongside. The team can regenerate them whenever the system changes. Stakeholders read the Level 1, new engineers read the Level 2, the architecture review uses both. The all-in-one decoration diagram is replaced by a navigable map.

Related skills

/atlas-map produces architecture diagrams. For onboarding documentation that includes the diagrams plus runnable setup, /atlas-onboard is the right call. For Architecture Decision Records that explain the choices visible in the map, /atlas-adr produces them. For changelog entries that record system changes affecting the map, /atlas-changelog is calibrated to that work.

Install

/atlas-map ships with the Atlas agent in the Tonone for Claude Code package. Install Tonone, invoke /atlas-map from any Claude Code session inside the project, and the skill produces the C4 diagrams generated from the actual codebase.

Architecture diagrams that stay current are the ones generated from the source of truth. The skill is built to make the generation cheap enough to run as the system evolves.