[c4builder](https://adrianvlupu.github.io/C4-Builder/#/) is a lightweight [[command line application]] for building, maintaining and sharing a [[software architecture model]] using only text. Documentation is written in [[Markdown]] and diagrams are written in [[c4-PlantUML]]. You can export or share documentation and diagrams as Markdown, PDF, or [[docsify]] site on [[GitHub pages]]. The primary alternative to c4builder is [[Structurizr]]. Structurizr has great functionality with its paid tier, including embeddable interactive diagrams, hosted documentation, and decision logs; check it out if you are able. At the free tier Structurizr only permits exports of diagrams in formats including HTML, PNG, and Mermaid (download the [Structurizr CLI](https://structurizr.com/help/cli) or use the [web interface](https://structurizr.com/dsl)). ## Installation You will need to install [[Node.js]] to access [[npm]]. You also need to install [[Java]] and [[GraphViz]]. ```bash npm i -g c4builder ``` Install the [VS Code extension PlantUML](https://github.com/qjebbs/vscode-plantuml) to work with c4-PlantUML in VS Code. Launch VS Code Quick Open ( `Ctrl + P` ), paste the following command, and press enter. ``` ext install plantuml ``` Use `Alt + D` to render a preview of the diagram right in VS Code. ## Getting Started 1. Create a project directory and open it. ```bash mkdir <my-software-docs> cd <my-software-docs> ``` 3. Create a directory called `src/`. ```bash mkdir src ``` 4. Open the folder in VSCode. ```bash code . ``` 5. In the `src/` directory, create a `.md` file and `.puml` file with the same base name: `context` (this is by convention, you can name it however you want). Write the documentation in Markdown and the diagram in [[c4-PlantUML]]. See the [demo project](https://github.com/adrianvlupu/C4Builder-Demo/blob/master/docs/1%20Internet%20Banking%20System/README.md) for guidance on documentation and [[c4-PlantUML]] for syntax. 6. Repeat this process for all the systems and components of the software, nesting folders for each level of the C4 model (see [[#Project structure]], below). 7. Build the documentation with `c4builder`. (The active directory should contain the `src/` directory when executing this command). ```bash c4builder ``` 8. On the first run, the CLI Wizard will help you configure the project. To update the project run the command `c4builder` again. If you need to change configuration settings, use `c4builder config. ### Project structure The `src/` directory includes `.md` files for documentation and `.puml` files which contain the [[c4-PlantUML]] definitions of each diagram. The folder structure is based on the C4 model. The root directory (`src/`) should contain the context documentation and diagram. Second-level directories describe each system. Third-level directories describe components. You can also include an `Additional Information/` directory within any directory. Documentation at the level of code is generally not recommended. ``` . +-- src/ +-- context.md +-- context.puml +-- system1/ +-- system1.md +-- system2.puml +-- container1/ +-- container1.md +-- container1.puml +-- component1/ +-- component1.md +-- component1.puml +-- component2/ ... +-- system2/ ... ``` Check out the [demo project](https://github.com/adrianvlupu/C4Builder-Demo/blob/master/docs/1%20Internet%20Banking%20System/README.md) for an example. ## Sharing your software architecture c4Builder provides many options for sharing the software architecture documentation and diagrams, however I recommend using one of the following two. 1. Create a GitHub repo dedicated to the documentation and diagrams. Serve the docsify site through GitHub Pages. Choose this option when the system will comprise multiple repositories. 2. Create a directory within the root project folder and build a single, navigable markdown document within it. Choose this option for smaller systems that are fully contained in a single repository. You can also create a PDF for a non-technical audience. ## Configuration Run `c4builder config` to update the configuration settings. The CLI wizard will walk you through the same configuration options you first selected, using those initial selections as the default. You can also edit the `.c4builder` file directly in VS Code. ### Embedding diagrams The default configuration will serve diagrams generated by the PlantUML server. I have found that the PlantUML server can be inconsistent, resulting display of an error message that might confuse your audience. I recommend instead enabling the option to embed SVG images (if sharing as a static site) or generate images locally (if sharing as Markdown). ## Common Errors The most common error occurs when the PlantUML server is down or can't be reached by c4builder when building the documentation. If you are embedding diagrams or generating diagrams locally, this could pop up for you. The solution is to wait a few seconds and try again. You can also copy the url (it will be very long) in the error message, paste it into the browser, and see if the PlantUML server will return anything that way.