C4BUILDER – Web project for building C4 model diagrams

What is c4builder?

c4builder: Literally understood as a builder that generates C4 architecture diagrams.

  • c4builder is a lightweight nodejscli tool for building, maintaining and sharing software architecture projects using only text.

  • c4builder is an architecture design tool that helps developers and architects describe and visualize the architecture of a software system, including the system’s components, relationships, dependencies, and interactions. It is based on the concepts of C4 model (Context, Container, Component and Code) and DSL (Domain-specific language), allowing designers to create clear, maintainable, easy-to-understand architecture diagrams, and supports automatic code generation to improve system reliability. stability, maintainability and collaboration.
    The main idea of c4builder is that developers can use familiar tools to define software.

Combined with git, any changes to the architecture defined in these documents are easily tracked. Pull requests, branches, cherry picks, and all git features serve as an easier way to track changes to your project’s architecture.

I’m probably still a little confused at this point. What exactly is c4builder?
c4builder is an extended function module based on NodeJS. After the installation is completed, some command lines are provided. Using the command line, you can quickly create a Web project framework that can be used to write C4 model diagrams. The effect after the project is started is as follows:

With this, developers, project management, users and manufacturers can easily view the architecture diagrams related to these systems online.

c4builder’s dependent projects

c4builder depends on the following projects:

  • PlantUml: Create diagrams from plain text. https://plantuml.com/zh/

  • Markdown: Create rich text documents from plain text. https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

  • C4Model: C4 model, https://c4model.com/

  • C4 PlantUML: C4 syntax support for generating PlantUML diagrams https://github.com/plantuml-stdlib/C4-PlantUML

  • Docsify: Create a single-page site based on markdown files. https://docsify.js.org/

  • vscode-plantuml: vscode-plantuml plugin for visualstudio code, for viewing diagrams at design time, https://github.com/qjebbs/vscode-plantuml

It is recommended to familiarize yourself with the above content first

Create c4 project

  1. Install c4builder
npm i -g c4builder
  • Here is the extension to install c4builder globally.
    The installation screen is as follows:
  1. Create project: c4builder new

This step will require some input, such as project name, etc. You can just keep clicking Enter. The project name here is c4project

E:\workspace\
odejs\c4builder>c4builder new
       _ _ _ _ _ _
   ___| || | |__ _ _(_) | __| | ___ _ __
  / __| || |_| '_ \| | | | | |/ _` |/ _ \ '__|
 | (__|__ _| |_) | |_| | | | (_| | __/ |
  \___| |_| |_.__/ \__,_|_|_|\__,_|\___|_|

Blow up your software documentation writing skills

This will create a new folder with the name of the project
? Project Name c4project
? PlantUML version: latest (compatible with plantuml online server)
? Include the VSCode autocomplete? Yes
true

  1. Name the line to switch to the project directory: cd c4project

  2. Project configuration: c4builder

Some interactive input is also required here, and you can press Enter by default.

E:\workspace\
odejs\c4builder\c4project>c4builder
       _ _ _ _ _ _
   ___| || | |__ _ _(_) | __| | ___ _ __
  / __| || |_| '_ \| | | | | |/ _` |/ _ \ '__|
 | (__|__ _| |_) | |_| | | | (_| | __/ |
  \___| |_| |_.__/ \__,_|_|_|\__,_|\___|_|

Blow up your software documentation writing skills

if you created the project using the 'c4model new' command you can just press enter and go with the default options to get a basic idea of how it works.

you can always change the configuration by running > c4builder config

? HomePage Name MyHome
?Root documentation folder src
? Destination folder docs
? Compilation format: Generate multiple pdf files, Generate a single complete pdf file, Generate website
? Change the default docsify theme? //unpkg.com/docsify/lib/themes/vue.css
? Support search on navbar? true
? Include a repository url?
? Path to a specific Docsify template?
? Change the default serve port? 3000
? Add a custom css for the pdf (filename)? xx\
ode_modules\c4builder\pdf.css
? Compilation format: Include breadcrumbs, Place diagrams before text
?PlantUML Server URL https://www.plantuml.com/plantuml
? Diagram Image Format svg
? Change the default charset UTF-8

building documentation in ./docs
parsed 7 folders
generating docsify site
generating complete pdf file

This command will create docs, src and other directories or files in the project directory.

  1. To start the project, you can use c4builder site or docsify.
    c4builder site or
docsify serve docs

Enter in the browser: http://localhost:3000/#/ to see the effect.

c4builder

command parameters

Named parameters can be viewed via c4builder --help.

  • -V or --version, version number
  • new : Create a project based on a template
  • config: Change the configuration of the current directory
  • list: List the current configuration
  • reset: Clear all configurations
  • site: Provide services for the generated site, that is, start the service
  • -w or --watch: Follow changes and refactorings
  • docs: Brief description of configuration options
  • -p port, --port port: The port of the service
  • -h or --help: Help

By default, running c4builder will attempt to build the project
If no configuration is set, it will ask for it and then do the actual build. Simply running c4builder after configuration will no longer display the wizard.
To change the configuration after the first build, just run c4builder-config. The default will be the previously set configuration, so you can edit the options that interest you.

Project structure

The generated project contains two main directories: the source code directory (src) and the target directory (docs).
Following the C4 model, the src directory represents Systems/Containers/Components or any other type of information about software.

The directory structure is as follows:

│ .gitignore
│ README.MD
├───docs # Target directory
└───src # source directory
    │ context.md
    │ context.puml
    └───Internet Banking System
        │ system.puml
        │ system.md
        ├───API Application
        │ container.puml
        │ container.md
        └───Single Page Application
            │ container.puml
            │ container.md
            └───Additional Information
                    additionalDetails.md
                    class.puml
                    sequence.puml
                    class.1.md

The target folder is automatically generated by the build process and can be in various formats. This folder can provide an in-depth view of the system/containers/components in different ways. Either push it to gitpages as a site and use it directly as a navigable markup in the repository, or generate the pdf and use traditional mail.

Online example

  • https://github.com/adrianvlupu/C4Builder-Demo

Installation problem: Failed to set up Chrome r116.0.5845.96! Set “PUPPETEER_SKIP_DO

complete error message

npm ERR! command C:\windows\system32\cmd.exe /d /s /c node install.js
npm ERR! ERROR: Failed to set up Chrome r116.0.5845.96! Set "PUPPETEER_SKIP_DOWNLOAD" env variable to skip download.
npm ERR! Error: write EPROTO 206C0000:error:0A000152:SSL routines:final_renegotiate:unsafe legacy renegotiation disabled:c:\ws\deps\openssl\openssl\ssl\statem\extensions.c:922:

Solution:

set PUPPETEER_SKIP_DOWNLOAD=true

Full analysis:




This error message indicates that an attempt to download Chrome (for Puppeteer, a headless browser library for Node.js) failed, possibly due to an SSL certification issue.

Several possible solutions are as follows:

1. Skip the Puppeteer download step by setting environment variables. You can set `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` before installation to skip the download of Chromium during the Puppeteer installation process. But this method requires you to manually specify or have a Chromium browser installed.

```bash
# Windows
set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
npm install puppeteer

#Linux/macOS
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install puppeteer
  1. If you are on a company or school network, you may need a proxy for external network access. The proxy can be configured through environment variable settings:
# Windows
set HTTP_PROXY=http://your-proxy.com:8080
set HTTPS_PROXY=http://your-proxy.com:8080

#Linux/macOS
export HTTP_PROXY=http://your-proxy.com:8080
export HTTPS_PROXY=http://your-proxy.com:8080
  1. Upgrade Node.js and npm to the latest versions. This may resolve SSL handshake issues. The latest versions of Node.js and npm can be downloaded from the official Node.js website.

Note: The above solutions may require some adjustments based on actual circumstances.

## References and links
*Official site: [https://adrianvlupu.github.io/C4-Builder/#/](https://adrianvlupu.github.io/C4-Builder/#/)

*****
*****