Comprehensive Guide: C4 Model for Software System Development

Introduction: Why C4 + AI + OpenDocs

Software architecture documentation is often a bottleneck—time-consuming, error-prone, and quickly outdated. The C4 model provides a structured hierarchy for visualizing architecture, while modern tools like Visual Paradigm's AI-powered C4 PlantUML Studio and OpenDocs platform transform how teams create, maintain, and share architectural documentation.

This guide covers the complete workflow: understanding the C4 model, generating diagrams with AI assistance, using PlantUML code, embedding artifacts in OpenDocs, and establishing a living documentation practice.

Part 1: Understanding the C4 Model

The C4 model, created by Simon Brown, provides four levels of abstraction that allow different stakeholders to view the system at the appropriate level of detail .

The power of C4 lies in treating diagrams like code—version-controlled, collaborative, and automatable .

Part 2: Tooling Overview – Visual Paradigm + AI + OpenDocs

The AI-Powered C4 PlantUML Studio

Visual Paradigm's AI-driven C4 PlantUML Studio provides a guided workflow that transforms natural language descriptions into complete, multi-level C4 models.

Core Capabilities:

• Natural language to diagrams: Describe your system in plain English; AI generates the PlantUML code and visual preview
• Step-by-step generation: Context → Container → Component → Supplementary views (Sequence, Deployment, Landscape)
• Real-time preview: Split-screen editor shows code and diagram side by side
• Manual refinement: Full control to edit PlantUML code for precision

OpenDocs – Living Documentation Hub

OpenDocs serves as the bridge between diagrams and documentation, functioning like a supercharged Notion with professional diagramming built in.

Key Features:

• Live, AI-assisted diagramming: Create and edit diagrams inline inside documents
• Artifact streaming: Auto-synchronize diagrams between creation tools and documentation
• Editability maintained: Diagrams remain connected to the model, never flat screenshots
• Centralized collaboration: Eliminates manual file transfers and version drift

Part 3: Step-by-Step Workflow with AI Assistance

Step 1: Define the Problem Statement

Start with a clear system description—this guides all subsequent AI generation. The AI can help generate a comprehensive problem statement from a simple project name.

Example for a Warehouse Management System :

Project: Warehouse Management System
Description: System for warehouse staff, managers, and logistics teams 
to manage inventory, optimize storage, and coordinate with ERP and 
Order Management systems.

Best Practice: The quality of AI-generated diagrams directly correlates with the clarity of your problem statement.

Step 2: Generate System Context Diagram (Level 1)

The AI reads your problem statement and generates a Context diagram showing the system as a single entity with external actors and systems.

PlantUML VPasCode Example – Context Diagram :

@startuml SystemContext
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

Person(customer, "Customer", "Manages tasks")
Person(admin, "Admin User", "Manages users")

System(taskManagement, "Task Management System", "Core task management platform")

System_Ext(emailSystem, "Email System", "Mailgun")
System_Ext(calendarSystem, "Calendar System", "Calendly")

Rel(customer, taskManagement, "Uses")
Rel(admin, taskManagement, "Administers")
Rel(taskManagement, emailSystem, "Sends emails")
Rel(taskManagement, calendarSystem, "Creates calendar events")

SHOW_LEGEND()
@enduml

Step 3: Generate Container Diagram (Level 2)

The AI leverages the context diagram to generate a more detailed view showing deployable units, technologies, and communication paths.

PlantUML VPasCode Example – Container Diagram :

@startuml ContainerDiagram
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

Person(customer, "Customer")
Person(admin, "Admin User")

System_Boundary(taskSystem, "Task Management System") {
    Container(webUI, "User Web UI", "React", "Frontend for customers")
    Container(adminUI, "Admin Web UI", "React", "Frontend for administrators")
    Container(api, "API", "Go", "Backend API service")
    ContainerDb(db, "Database", "PostgreSQL", "Persists task and user data")
}

System_Ext(emailSystem, "Email System")
System_Ext(calendarSystem, "Calendar System")

Rel(customer, webUI, "Uses", "HTTPS")
Rel(admin, adminUI, "Uses", "HTTPS")
Rel(webUI, api, "Makes API calls", "JSON/HTTPS")
Rel(adminUI, api, "Makes API calls", "JSON/HTTPS")
Rel(api, db, "Reads from and writes to", "JDBC")
Rel(api, emailSystem, "Sends emails")
Rel(api, calendarSystem, "Creates events")

SHOW_LEGEND()
@enduml

Step 4: Generate Component Diagram (Level 3)

The AI drills into a specific container to show internal components, their responsibilities, and interactions.

PlantUML VPasCode Example – Component Diagram:

@startuml ComponentDiagram
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

Person(customer, "Customer")
Person(admin, "Admin User")

System_Boundary(apiContainer, "API Container") {
    Component(auth, "Authentication", "JWT-based", "Handles user authentication")
    Component(crud, "CRUD Operations", "Business Logic", "Manages tasks and users")
    Component(validator, "Request Validator", "Validation", "Validates incoming requests")
}

ContainerDb(db, "Database", "PostgreSQL", "Persists data")

Rel(customer, auth, "Authenticates with", "JWT")
Rel(admin, auth, "Authenticates with", "JWT")
Rel(auth, crud, "Authorizes requests")
Rel(crud, db, "Reads from and writes to", "JDBC")
Rel(crud, validator, "Uses for validation")

SHOW_LEGEND()
@enduml

Step 5: Add Dynamic and Supplementary Views

Beyond the core four levels, generate Sequence, Deployment, and Landscape diagrams for specific audiences.

Sequence Diagram Example (C4_Sequence.puml):

@startuml SequenceDiagram
!theme C4_united from https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/themes
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Sequence.puml

Person(Alice, "User")
Person(Bob, "System")

activate Bob

Rel(Alice, Bob, "Authentication Request")

alt successful case
    Rel(Bob, Alice, "Authentication Accepted")
else failure case
    Rel(Alice, Bob, "Retry Request")
end

== Data Flow ==

Rel(Alice, Bob, "Fetch Tasks")
Rel(Bob, Alice, "Task List")

SHOW_LEGEND()
@enduml

Part 4: Advanced PlantUML Techniques

Layout Control

C4-PlantUML provides layout macros for controlling diagram orientation:

!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

' Default – top to bottom
LAYOUT_TOP_DOWN()

' Left to right layout
LAYOUT_LEFT_RIGHT()

' Landscape mode (left to right with directed relations)
LAYOUT_LANDSCAPE()

' Add legend
LAYOUT_WITH_LEGEND()

' Sketch mode (indicates diagram is a draft)
LAYOUT_AS_SKETCH()

Person Sprites

Customize person representations :

Person(userA, "User A", "Default sprite", "person")
Person(userB, "User B", "Custom sprite", "person2")

' Hide sprites entirely
HIDE_PERSON_SPRITE()

' Show with custom sprite
SHOW_PERSON_SPRITE(spriteName)

Best Practices for C4-PlantUML

1. Include the correct library for each diagram level:
   • Context: C4_Context.puml
   • Container: C4_Container.puml
   • Component: C4_Component.puml
   • Sequence: C4_Sequence.puml
2. Call SHOW_LEGEND() last in the diagram file
3. Use descriptive relationships: Rel(from, to, "Description", "Technology")

Part 5: AI-Assisted Architecture Design

AI Strengths and Limitations

Recent research on LLMs for C4 diagram generation reveals important insights :

Strengths:

• Quickly generates template diagrams for prototyping
• Good at identifying system actors and external systems
• Can produce consistent baseline designs

Limitations:

• Often struggles with Component vs. Code diagram distinctions
• Tends toward "perfect world" designs lacking real-world constraints
• May select technologies based on patterns rather than contextual reasoning
• Less effective for pragmatic architectural decisions

LLM Performance Comparison:

• Claude 4.0 Sonnet: Best performer, better abstraction and decomposition
• GPT-4o: Good at Context, weaker on Component and Container views
• Grok 3: Similar to GPT-4o, fixates on Code diagrams
• Sonar: Too high-level, incoherent symbols

Effective AI Prompting

Bad Prompt:

"Generate C4 diagrams for my banking app"

Good Prompt:

"You are a software architect. Create C4 diagrams for the Panda Service – an ML-based product recommendation service for a bank. The system must:

• Leverage user account behavior and transaction history
• Generate personalized product recommendations
• Be accessible via internal banking apps, web, and mobile
• Consider banking regulations and security

Generate:

• Level 1: System Context Diagram
• Level 2: Container Diagram showing deployable services
• Level 3: Component Diagram for the Model Inference Service"

Multi-Agent Systems

Emerging approaches use collaborative LLM agents that simulate role-specific experts (architect, developer, security expert) to analyze requirements and generate C4 views simultaneously . This improves structural integrity and consistency across diagram levels.

Part 6: OpenDocs – Living Documentation

Publishing from C4 Studio to OpenDocs

1. Generate diagrams in AI C4 PlantUML Studio
2. Save project to Visual Paradigm Cloud
3. Open OpenDocs and embed diagrams as living artifacts
4. Stream changes: Updates to diagrams automatically sync to documentation

OpenDocs Capabilities

OpenDocs Supported Diagrams

OpenDocs provides AI-powered generation for C4 diagrams, including System Context, Container, Component, and Deployment diagrams .

Part 7: Best Practices

Diagram Creation

1. Start with a clear problem statement – quality in = quality out
2. Generate holistically – let AI propagate changes across all levels from one description
3. Refine manually – AI provides 80% solution; adjust technologies, relationships, and descriptions
4. Use consistent terminology – "Level 1 System Context", "Level 2 Containers", "Level 3 Components"

Documentation Maintenance

1. Treat as living documents – update when architecture changes
2. Bridge tools – use OpenDocs to keep diagrams and text in sync
3. Audience matters – CTO sees Level 1, developers see Level 3

Conclusion

The combination of the C4 model, AI-assisted generation, and living documentation platforms transforms software architecture practice from a tedious, manual chore into a streamlined, collaborative workflow.

Key Takeaways:

• The C4 model provides the right level of abstraction for every stakeholder
• AI accelerates diagram generation from natural language descriptions
• Visual Paradigm's C4 PlantUML Studio and OpenDocs bridge generation to documentation
• AI is a powerful accelerator but requires human architectural judgment

By adopting these practices, teams maintain clear, accurate, and evolving architectural documentation without the traditional maintenance burden.