How to create a project’s C4 model in just a few steps using an AI tool

When designing new projects — particularly in roles such as senior developer, technical lead, or specialist — professionals are often responsible for a comprehensive range of tasks, from business definitions to creating technical solutions. The C4 Model has gained recognition as a practical approach for visually representing the system’s architecture,  facilitating communication between the technology and business areas.

Leveraging tools such as StackSpot AI, which streamlines and speeds up software development, generative artificial intelligence can be embedded into the process to optimize the creation of architecture diagrams and ensure that the expectations of all parties involved are addressed with clarity and precision.

In this article, we’ll explore how to efficiently and pragmatically build a C4 model by harnessing the power of contextualized AI provided by StackSpot AI.

Meet StackSpot AI

StackSpot AI is a contextualized Artificial Intelligence assistant that integrates generative AI models throughout the software development cycle. It provides assertive answers for your project and quick commands to automate repetitive tasks.

Now, let’s take a look at some of StackSpot AI’s functionality concepts:

StackSpot AI’s Knowledge Sources

One of the key features of StackSpot AI is Knowledge Sources (KS), which play a vital role in generating contextualized and accurate responses.

With Knowledge Sources, we can even add context to our prompts, significantly improving results.

Learn about Knowledge Sources in the StackSpot AI documentation.

StackSpot AI’s Quick Commands

One of the standout features of StackSpot AI is Quick Commands — predefined instructions that can be sent to the Large Language Model (LLM) to execute specific actions. These commands provide fast and efficient means of contextualizing the LLM.

In other words, it’s a way of automating a command prompt workflow.

Learn about Quick Commands in the StackSpot AI documentation.

What is the C4 Model, and what are its benefits?

Anyone in Software Engineering knows how difficult it is to maintain various levels of documentation, such as project installation and usage guides, software architecture, release history, and more.

The C4 Model, which focuses on software architecture, has emerged to increase efficiency in document creation.

Now, imagine using a programming language like PlantUML to create diagrams at multiple levels while keeping the documentation versioned within the project or in a dedicated repository.

The productivity gains are substantial. What used to take a sprint (typically two weeks) to document can now be completed in just 2 or 3 days. Moreover, collaborative strategies, such as Pull Requests, add even more flexibility to the process.

If this scenario already seems promising, picture reducing the time required from days to hours.

Creating a project’s C4 model with StackSpot AI

Using my C4 Model Generation Quick Command, I was able to create all the diagrams in about two hours. The most complex part was describing the project, where I only needed to outline the technologies used and clearly define the objective I wanted to achieve with the microservice.

Now that we’ve understood the main features of StackSpot AI and the importance of the C4 Model in a development project, it’s time to dive into the practical side.

Adding Knowledge Sources

First, I added two Knowledge Sources to my StackSpot AI account. A key strategy for creating knowledge sources is to consider their intended use.

1st Knowledge Source – Definition of the C4 Model: I included the definition of the C4 Model and all its layers (System Context, Container, Component, UML, etc.). I copied all the content from the official C4 Model documentation site and manually added it to StackSpot AI.

Important: I can use this Knowledge Source whenever I want to contextualize the C4 model in future projects, eliminating the need to repeat this step each time.

2nd Knowledge Source – Project Definition:

I added the Project definition as a Knowledge Source using the following text:

Bankly API Integration Project for bank slips Generation

This project aims to develop a microservice responsible for integrating the front end and the Bankly API to generate bank slips.

Technologies Defined:

Language: Java
Framework: Spring
External integrations: OpenFeign for communication with external systems
Database: Relational, used to retrieve user information needed to generate the bank slip via integration
Monitoring: Logs for monitoring and analyzing events
Observability: Grafana and Prometheus for monitoring and metrics
Deployment: AWS EKS (Elastic Kubernetes Service) for container orchestration and management

This structure guarantees a robust and scalable solution, focusing on efficient integration and continuous monitoring.

Implementing Quick Command

Now comes the fun part: implementing the command prompt workflow, i.e., creating our Quick Command. Click “Quick Commands” and “Create Custom Quick Commands” to start building your automation in the portal.

Once you’ve gone through this stage, you can create your commands and link them together to form a workflow.

Project understanding: The first prompt I created was “project understanding.” This prompt is responsible for taking the entire project definition, understanding what it’s about, addressing potential architecture, security, and business gaps, and generating all the technical documentation based on a Stack I’ve provided as a command.

Input: “{{selected_code}}”

Output: “Understand the above project, add any missing execution steps, and define a technology stack including the technologies mentioned in the context of the project, as well as other necessary technologies.”

1. Architectural drawings: The second prompt is to create the project’s architectural drawings based on the C4 Model definitions and all their respective layers. 

Input: “{{understanding-project.answer}}”

Output: "Based on the answer above, generate a C4 architecture model in C4-PlantUML as a reference, including a System Context diagram (level 1), a Container diagram (level 2), and a Component diagram (level 3), all in English."

Running Quick Command in VS Code

You’ll see a confirmation message after installing and connecting to the StackSpot AI extension for VS Code.

Since I customized my project understanding command to receive a “selected code,” I copied the description of the microservice that needs to be developed into a new VSCode tab, selected all the content, and ran the command.

After waiting for the workflow to complete, I obtained three diagrams, each containing information from a specific level of the standard defined by the C4 Model.

Result achieved

These diagrams provide a clear and detailed view of the system’s architecture, from user interactions to the internal implementation of its components.

Below are the C4 architecture diagrams in Mermaid Diagram format, along with their respective explanations:

1 – System Context Diagram (Level 1)

This diagram shows an overview of the system and its interactions with external actors. The front end user submits a request to generate bank slips through the front end interface. The bank slip generation microservice processes these requests, retrieves data from the relational database, and communicates with the Bankly API to generate the bank slips.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_LEFT_RIGHT()
title System Context -  Bank slips Generation Microservice

    Person(frontendUser, "Front end User", "User who interacts with the system via the front end")
    Person(banklyAPI, "API da Bankly", "External API for generating bank slips")

    System_Boundary(system, "Bank slips Generation Microservice") {
        System(frontend, "Front end", "User interface for requesting the generation of bank slips")
        System(microservice, "Bank slips Generation Microservice", "Microservice that processes requests and generates bank slips")
       SystemDb(database, “Relational Database”, “Stores user data and transactions”)
    }

    Rel(frontendUser, frontend, “Request bank slips generation”)
    Rel(frontend, microservice, “Sends bank slips generation request”)
    Rel(microservice, banklyAPI, “Communicates with the Bankly API to generate bank slips”)
    Rel(microservice, database, “Retrieves user data and transactions”)

@enduml

2 – Container Diagram (Level 2):

The container diagram outlines the system’s main components. The front end is implemented in React and communicates with the bank slips generation microservice developed in Spring Boot. The microservice retrieves data from a relational database (PostgreSQL) and utilizes Prometheus and Grafana for monitoring and visualizing metrics. Deployment is done in AWS EKS for container orchestration.

@startuml
!define C4Container
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_LEFT_RIGHT()

Person(user, "User", "User who interacts with the system via the front end")
Container(frontend, "Front-end", "React", "User interface to request the generation of invoices")
System_Boundary(system, "Microservice for Bill Generation") {
    Container(awseks, "Deploy", "AWS EKS", "Container Orchestrator")
    Container(prometheus, "Prometheus", "Prometheus", "Collects information from applications and sends it to Grafana")
    Container(microservice, "Bill Generation Microservice", "Spring Boot", "Microservice that integrates with Bankly's API to generate invoices")
    ContainerDb(database, "Database", "PostgreSQL", "Stores user information and generated bills")
    ContainerDb(grafana, "Metrics", "Grafana", "Stores application metrics information")
}
Container_Ext(api_bankly, "API Bankly", "API externa", "External API for generating bank slips")

Rel(user, frontend, "Request the generation of invoices")
Rel(frontend, microservice, "Send request for bill generation via HTTP")
Rel(microservice, api_bankly, "Integrates with the Bankly API via OpenFeign")
Rel(microservice, awseks, "Application deployment")
Rel(microservice, database, "Stores and retrieves user and bill information")
Rel(microservice, prometheus, "Send metrics to Prometheus")
Rel(prometheus, grafana, "Save the information in grafana")
@enduml

3 – Component Diagram (Level 3):

The component diagram focuses on the bank slip generation microservice, which consists of the following:

• BoletoController: A REST controller that receives requests from the front end.
• BoletoService: A service that contains the bank slip generation logic.
• BanklyFeignClient: A Feign client that communicates with the Bankly API.
• UserRepository: A JPA repository that accesses data from the database.
• PrometheusMetrics: A component that collects metrics and sends them to Prometheus.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
LAYOUT_LEFT_RIGHT()
    title System Context - Bank slips Generation Microservice

Container_Boundary(microservice, "Bank slips Generation Microservice") {
    Component(controller, "BoletoController", "Spring REST Controller", "Recebe requisições do front end")
    Component(service, "BoletoService", "Spring Service", "Processes the Bank slip generation logic")
    Component(feignClient, "BanklyFeignClient", "OpenFeign Client", "Comunica-se com a API da Bankly")
    Component(repository, "UserRepository", "JPA Repository", "Accesses user data in the database")
    Component(prometheusMetrics, "PrometheusMetrics", "Prometheus", "Collect microservice metrics")
}

Rel(controller, service, “Calls the service to process bank slips generation”)
Rel(service, feignClient, “Uses Feign Client to communicate with the Bankly API”)
Rel(service, repository, “Retrieves user data and transactions”)
Rel(service, prometheusMetrics, “Sends metrics to Prometheus”)
@enduml

Conclusion

By combining the C4 Model with StackSpot AI, software architectures can be built and documented quickly and accurately.

The C4 Model offers a clear perspective at various levels of abstraction, facilitating communication between technical and business teams. StackSpot AI further enhances this modeling by automating diagram creation and organization, streamlining repetitive tasks, minimizing manual work, and ensuring greater consistency across projects.

Together, these approaches deliver scalable, well-documented, and easy-to-manage solutions, fostering agility and improving quality in software development.

What did you think of this tutorial on how to create a C4 Model with StackSpot AI? Let us know in the comments!