c4-structurizr

c4-structurizr is a Codex skill for producing a compact, evidence-backed C4 architecture model for one focal system. It creates seven Structurizr-styled C4-PlantUML diagrams, renders them with Java PlantUML, and verifies that every output is traceable to the source code rather than generated from vague assumptions.

Why this skill exists

Most generated architecture diagrams are either too generic or too disconnected from the code. This skill takes the opposite approach: it first inventories the actors, systems, containers, components, external dependencies, stores, queues, and deployment targets found in the repository. It then maps those elements into seven focused views and renders them through a consistent custom style.

The result is useful for onboarding documents, architecture reviews, AI-system reviews, design discussions, and technical reports where the diagram must explain the real system rather than a stylized abstraction.

What it produces

By default, the skill produces these seven views:

1. system-landscape
2. system-context
3. container
4. component
5. dynamic-flow
6. deployment
7. critical-path

Each diagram is a PlantUML source file. The renderer writes SVG output beside the diagram sources. Optional PNG previews can be generated for visual inspection.

How it works

The skill follows this sequence:

1. Resolve the target repository and focal system.
2. Read the repository structure, manifests, configuration, infrastructure files, tests, and existing documentation.
3. Inventory people, systems, containers, components, external systems, stores, queues, and relationships.
4. Detect AI workflow semantics when the repository contains agents, prompts, model adapters, executors, context stores, trace stores, or related runtime boundaries.
5. Select and generate the seven views.
6. Render the diagrams with the bundled renderer.
7. Verify that all SVG outputs are nonblank and consistent with the evidence.

It is intentionally conservative. If the repository does not provide enough evidence for a view or relationship, the skill should report the gap instead of inventing an architecture.

Installation

Copy the folder into your Codex skills directory:

~/.codex/skills/c4-structurizr

The skill has no external Python dependencies. It uses the Python standard library for the renderer.

Rendering requirements

To render diagrams, you need one of the following:

• Java plus plantuml.jar
• A plantuml executable available on PATH

The renderer looks for plantuml.jar in these places:

1. The --plantuml-jar argument
2. The PLANTUML_JAR environment variable
3. Common docs/architecture/tools/ and tools/ locations near the diagram directory

If neither Java nor a PlantUML executable is available, the skill can still generate PlantUML sources, but rendering will fail until a renderer is available.

Usage

The normal Codex request is simple:

Use c4-structurizr to analyze this repository and generate the seven C4 views.

For manual rendering:

python "<skill-directory>/scripts/render_c4.py" --source "docs/architecture/structurizr/plantuml"

Useful options:

Option	Purpose
--source <dir>	Directory containing the diagram .puml files
--plantuml-jar <path>	Use a specific plantuml.jar
--plantuml <exe>	Use a specific PlantUML executable
--output-dir <dir>	Write rendered files to a separate directory
--preview	Also generate PNG previews in _preview/
--check-only	Run PlantUML syntax validation without writing outputs
--verbose	Print the exact rendering command

Expected layout

The default diagram workspace is:

docs/architecture/structurizr/plantuml/
  system-landscape.puml
  system-context.puml
  container.puml
  component.puml
  dynamic-flow.puml
  deployment.puml
  critical-path.puml
  c4-style.puml

The shared C4-PlantUML assets are staged in:

docs/architecture/tools/c4-plantuml/

This separation keeps generated diagrams readable while preserving consistent styling and reusable C4 macros.

Design rules

• Use one focal system per diagram set.
• Derive entities from evidence in the repository.
• Prefer domain and technology terms already used by the project.
• Keep relationships explicit and traceable.
• Do not invent stores, queues, services, or trust boundaries.
• Use the shared style instead of one-off diagram colors.
• Mark AI elements only when the repository actually contains AI runtime behavior.

License

MIT