en_US

The C4 model, developed by Simon Brown, is a powerful, hierarchical approach to visualizing software architecture. It uses four levels of abstraction to provide the right level of detail for different audiences, from business stakeholders to developers. This makes it ideal for creating clear, maintainable, and audience-focused documentation.

Introduction to C4 Model: a Quick Guide - Visual Paradigm Blog

This comprehensive guide draws from the well-known case study of Big Bank plc’s Internet Banking System — a fictional but realistic example of building an online banking platform for personal customers to view accounts and make payments. The case study demonstrates how to apply the C4 model progressively, using PlantUML for “architecture as code.” It also incorporates modern tools like Visual Paradigm’s AI-powered C4 PlantUML Studio (released in late 2025) to accelerate creation and maintenance.

Overview of the C4 Model

The model includes four levels:

  1. Level 1: System Context — The big picture: the system, users, and external dependencies.

  2. Level 2: Containers — Major deployable units (applications, services, databases) and high-level technology choices.

  3. Level 3: Components — Internal logical building blocks within a container.

  4. Level 4: Code — Optional low-level details (e.g., classes); often skipped in favor of source code references.

Additional supporting views include dynamic (runtime flows) and deployment diagrams.

Applying the C4 Model: Big Bank plc Internet Banking System Case Study

Level 1: System Context Diagram

Purpose: Provide a high-level overview for business stakeholders and non-technical audiences, showing how the Internet Banking System fits into the broader environment without technical jargon.

Key Elements:

  • Person: Personal Banking Customer — A customer with one or more personal bank accounts.

  • Software System: Internet Banking System — Allows customers to view account information and make payments.

  • External Systems:

    • Core Banking System (existing mainframe) — Handles customer data, accounts, and transactions.

    • Email System (e.g., AWS SES) — Sends confirmations and notifications.

Relationships:

  • Customer uses the Internet Banking System.

  • Internet Banking System uses the Core Banking System for data and transactions.

  • Internet Banking System sends email via the Email System.

This level keeps things simple and explicit about scope and integrations.

PlantUML Example (adapted from the case study):

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()
title System Context Diagram (Level 1) for Internet Banking System
Person(customer, "Personal Banking Customer", "A customer with one or more personal bank accounts.")
System(internet_banking_system, "Internet Banking System", "Allows customers to view accounts and make payments.")
System(core_banking_system, "Core Banking System", "Existing mainframe handling customer data, accounts, and transactions.")
System_Ext(email_system, "Email System", "Amazon Web Services Simple Email Service (AWS SES) for sending confirmations.")
Rel(customer, internet_banking_system, "Uses")
Rel(internet_banking_system, core_banking_system, "Uses")
Rel(internet_banking_system, email_system, "Sends email via")
@enduml

Level 2: Container Diagram

Purpose: Zoom in to show the major building blocks (containers) and technology choices, targeted at architects, developers, and DevOps teams.

Key Elements (inside Internet Banking System boundary):

  • Single-Page Application (SPA) — JavaScript + Angular, full UI in web browser.

  • Mobile App — iOS/Android with React Native (or similar), limited functionality.

  • API Application — Java + Spring Boot, JSON/HTTPS API serving both front-ends.

  • Database — PostgreSQL, stores session data, preferences, and cached summaries (core data stays in mainframe).

External — Core Banking System and Email System.

Relationships:

  • Customer uses SPA and Mobile App via HTTPS.

  • SPA and Mobile App call API Application (JSON/HTTPS).

  • API Application reads/writes Database (JDBC/SQL).

  • API Application interacts with Core Banking System (JSON/HTTPS) and Email System (HTTPS).

This diagram acts as the “single source of truth” for technology decisions.

PlantUML Example (uses sprites for icons):

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!include https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons/angular.puml
!include https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons/java.puml
!include https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons/postgresql.puml
LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()
title C4 Container Diagram for Internet Banking System
Person(customer, "Personal Banking Customer", "A customer with one or more personal bank accounts.")
System_Boundary(internet_banking_system, "Internet Banking System") {
    Container(spa, "Single-Page Application", "JavaScript + Angular", "Full internet banking UI", $sprite="angular")
    Container(mobile_app, "Mobile App", "iOS/Android (React Native)", "Limited functionality", $sprite="react")
    Container(api_app, "API Application", "Java + Spring Boot", "JSON/HTTPS API", $sprite="java")
    ContainerDb(database, "Database", "PostgreSQL", "Session data, preferences, cached summaries", $sprite="postgresql")
}
System(core_banking_system, "Core Banking System", "Existing mainframe...")
System_Ext(email_system, "Email System", "AWS SES...")
Rel(customer, spa, "Uses", "HTTPS")
Rel(customer, mobile_app, "Uses", "HTTPS")
Rel(spa, api_app, "Calls", "JSON/HTTPS")
Rel(mobile_app, api_app, "Calls", "JSON/HTTPS")
Rel(api_app, database, "Reads from and writes to", "JDBC/SQL")
Rel(api_app, core_banking_system, "Queries / Updates", "JSON/HTTPS")
Rel(api_app, email_system, "Sends email via", "HTTPS")
@enduml

Level 3: Component Diagram

Purpose: Detail internal structure of a key container (here, the API Application) for development teams.

Key Components (inside API Application):

  • Accounts Controller (Spring MVC) — Provides summaries and balances.

  • Authentication Controller (Spring MVC) — Login, sessions, tokens.

  • Reset Password Controller (Spring MVC) — Password resets via email.

  • Security Component (Spring Bean) — Authentication, JWT, hashing.

  • Account Management Component (Spring Bean) — Orchestrates Core Banking calls.

  • Email Notification Component (Spring Bean) — Sends emails.

Interactions — Controllers use Security; Account Management uses Core Banking; Email uses Database; front-ends call controllers.

PlantUML Example:

PlantUML Diagram

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
LAYOUT_WITH_LEGEND()
title Component diagram for Internet Banking System - API Application
Container(spa, "Single Page Application", "javascript and angular", "...")
Container(ma, "Mobile App", "...", "...")
ContainerDb(db, "Database", "...", "...")
System_Ext(mbs, "Mainframe Banking System", "...")
Container_Boundary(api, "API Application") {
    Component(accounts, "Accounts Controller", "Spring MVC", "...")
    Component(auth, "Authentication Controller", "Spring MVC", "...")
    Component(reset, "Reset Password Controller", "Spring MVC", "...")
    Component(security, "Security Component", "Spring Bean", "...")
    Component(accountmgmt, "Account Management Component", "Spring Bean", "...")
    Component(email, "Email Notification Component", "Spring Bean", "...")
    Rel(accounts, security, "Uses")
    Rel(auth, security, "Uses")
    Rel(reset, security, "Uses")
    Rel(accountmgmt, mbs, "Uses", "XML/HTTPS")
    Rel(email, db, "Reads", "JDBC")
}
Rel(spa, accounts, "Uses", "JSON/HTTPS")
Rel(spa, auth, "Uses", "JSON/HTTPS")
Rel(spa, reset, "Uses", "JSON/HTTPS")
Rel(ma, accounts, "Uses", "JSON/HTTPS")
Rel(ma, auth, "Uses", "JSON/HTTPS")
Rel(ma, reset, "Uses", "JSON/HTTPS")
@enduml

Level 4: Code Diagram (Optional)

Purpose: Show class-level details for specific areas (e.g., Authentication).

Often omitted — point to source code instead.

Example — UML class diagram for Authentication:

  • AuthenticationController uses JwtTokenProvider and UserRepository.

PlantUML Example:

@startuml
classDiagram
class "AuthenticationController" {
    +login(credentials)
    +refreshToken()
}
class "JwtTokenProvider" {
    +generateToken(user)
    +validateToken(token)
}
class "UserRepository" {
    +findByUsername()
}
AuthenticationController ..> JwtTokenProvider : "uses"
AuthenticationController ..> UserRepository : "uses"
@enduml

Supporting Views

  • Dynamic Diagram (e.g., “View Account Summary” sequence): Customer → SPA → API → Database/Core Banking → Response.

  • Deployment Diagram: Maps containers to infrastructure (e.g., AWS EC2 for API, RDS for Database, on-premises mainframe).

Leveraging Visual Paradigm’s AI-Powered Tools

Visual Paradigm’s AI-Powered C4 PlantUML Studio (late 2025 release) revolutionizes this process:

  • Input natural language (e.g., “Create a C4 model for an internet banking system with SPA, mobile app, Spring Boot API, PostgreSQL, and mainframe integration”).

  • AI generates PlantUML code and diagrams for all levels.

  • Use the AI chatbot to iterate (e.g., “Add MFA to the authentication component” or “Generate deployment view on AWS”).

  • Maintain consistency across levels and support “living documentation.”

  • Export, version, and integrate with repositories.

This tool provides structured, C4-compliant output far more reliably than general-purpose AIs.

Best Practices

  1. Start with workshops — Use whiteboards for Level 1 to align stakeholders.

  2. Treat architecture as code — Store PlantUML files in your repo for automatic updates with code changes.

  3. Automate with AI — Use Visual Paradigm to generate and refine diagrams quickly.

  4. Audience focus — Omit tech details from Level 1; add them progressively.

  5. Keep it lightweight — Only detail complex containers at Level 3; skip Level 4 unless essential.

  6. Evolve documentation — Make diagrams “living” to prevent outdated artifacts.

The Big Bank plc case study remains a canonical example of the C4 model’s effectiveness in real-world scenarios, promoting clarity, collaboration, and scalable architecture communication. For more, explore the official C4 site or Visual Paradigm’s AI tools.