Beyond Use Cases: Mapping Architecture with the C4 Model
Stop writing endless "The user shall" sentences. Learn how the C4 Model and Mermaid.js provide a visual, code-backed alternative for documenting system architecture, featuring a practical Django user-auth example.
The Problem with Traditional Use Cases
Traditional use cases focus on behavior—narrating every step a user takes. While useful for business logic, they often fail to show the structural reality of the system. For developers, a visual map of the architecture is often a far more efficient alternative.
The C4 Model (Context, Containers, Components, Code) allows you to zoom in and out of your system just like Google Maps. Instead of reading a 10-page document, you can see the architecture at a glance.
Example: Django User Management
Rather than writing out steps for login, registration, and secured access, we can "code" our architecture using Mermaid.js. This allows us to keep our diagrams right in the repository alongside our source code.
Level 2: The Container View
This view shows the high-level boundaries: what runs in the browser, what runs on the server, and where the data is stored.
`
C4Container
title Container diagram for User Management System
Person(user, "User", "A customer interacting with the app.")
System_Boundary(c1, "Django Web Application") {
Container(spa, "Frontend (SPA)", "React", "Handles public/secured UI.")
Container(backend, "Django Backend", "Python", "Processes auth logic and data.")
ContainerDb(db, "PostgreSQL", "SQL", "Stores user accounts.")
}
Rel(user, spa, "Uses", "HTTPS")
Rel(spa, backend, "API requests", "JSON/HTTPS")
Rel(backend, db, "Reads/Writes", "SQL/TCP")
`
Level 3: The Component View (The "Secured" Logic)
By zooming into the Django Backend, we see exactly how built-in features like LoginRequiredMixin replace the need for manual "If/Then" use case logic.
`
C4Component
title Component diagram for Django Backend
Container_Boundary(django_boundary, "Django Backend") {
Component(urls, "URL Conf", "urls.py", "Routes requests.")
Component(public_view, "Public View", "TemplateView", "Renders public pages.")
Component(login_view, "Login View", "LoginView", "Handles auth.")
Component(secure_view, "Dashboard", "LoginRequiredMixin", "Guards secured pages.")
Component(user_model, "User Model", "AbstractUser", "The data model.")
}
Rel(urls, public_view, "Routes to")
Rel(urls, login_view, "Routes to")
Rel(urls, secure_view, "Routes to")
Rel(secure_view, user_model, "Queries")
`
Why This is a Superior Alternative
-
No More Repetition: One diagram explains the "Public" vs. "Secured" flow instantly.
-
Architectural Intent: You see the boundary between the frontend and the database, which text often obscures.
-
Developer-First: Using Mermaid means your documentation is version-controlled and lives in your IDE.
Start Mapping Your Own Projects
The C4 Model turns documentation from a chore into a design tool. By mapping your Django app visually, you build a shared understanding that is easier to maintain than any text file.
Ready to skip the manual syntax?
If you want to jumpstart your architectural diagrams using AI, I highly recommend using Mermaid.ai. It makes creating C4 models as simple as describing your system in plain English.
Special Offer: Use my referral link below to get 10% off your plan: