# avisi-cloud/structurizr-site-generatr architecture

> Architecture diagram of the GitHub repository avisi-cloud/structurizr-site-generatr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avisi-cloud/structurizr-site-generatr
- Repository: https://github.com/avisi-cloud/structurizr-site-generatr

## Overview

##### Project Type and Purpose
- The README clearly explains that it supports generating sites from local DSL files as well as directly from Git repositories, and it includes a development web server mode to ease local previewing.

##### File Structure
- The top-level directories include configuration files (Dockerfile, build.gradle.kts, .editorconfig) plus extensive documentation under “docs” and the actual source code under “src/main/kotlin/nl/avisi/structurizr/site/generatr”.
- The presence of various Gradle files and Docker configuration hints at a CI/CD pipeline and containerized deployment scenarios.

##### README for Additional Insights
- The README presents usage examples for three command modes (help, generate-site, serve, version) and describes extensive customization (via properties for styling, search, assets, etc.), which suggests a multi-component design.

a. Main components:
- Command Line Interface (CLI) – Provides user entry points for commands such as generate-site, serve, and version.
- Input Handling / DSL Parser – Reads and parses the Structurizr DSL workspace files; supports local files and remote Git repositories.
- Site Generation Engine – The core module that transforms the parsed DSL model into a structured website. This includes:
⁃ Documentation and ADR Processor (merges Markdown/AsciiDoc documentation and architectural decision records).
⁃ Asset Management Module (loads static assets like CSS, JavaScript, logos, custom stylesheets).
- Development Server Module – Wraps the generated website into a local web server (default port 8080) with live reload capabilities.
- Build & Deployment – Modules related to Gradle and Docker configurations which support the build lifecycle, testing, and containerized deployment.

b. Relationships and Interactions:
- The CLI acts as an entry point, directing the input (either a local DSL file or Git repository URL) to the DSL Parser.
- The parsed C4 model is passed to the Site Generation Engine which then invokes:
⁃ The Documentation & ADR processors that collate content from defined directories.
- A configuration manager overlays custom properties (from the DSL model’s metadata) to affect styling and behavior across the generated site.
- External integrations like Docker come into play during build and deployment phases, but the core architectural flow remains modular.

c. Important Architectural Patterns/Design Principles:
- Separation of Concerns: Each aspect (CLI, parsing, site generation, server) is isolated in its own component.
- Modularity: The heavy use of subpackages (model, views, site, utilities) reinforces a layered design.
- Testability: A dedicated test suite enforces boundaries and supports continuous integration.

d. Relevant Technologies/Frameworks:
- Kotlin as the main programming language.
- Gradle as the build system.
- Docker for containerization and CI/CD integration.
- PlantUML (and its C4 extension) used by exporters.
- Web technologies for the static site (HTML/CSS/JavaScript) and related frameworks/libraries indicated by asset directories.
- Git for input source management.

##### Elements
- From “CLI” to “DSL Parser” (input of workspace file or Git URL)
- From “DSL Parser” to “Site Generation Engine” (transformation of the C4 model)
- Consolidation into “Static Website Build Directory”
- Core processing modules versus utility modules (e.g., round rectangles for processing, parallelograms for I/O components).
- Configuration components can be highlighted differently to emphasize their role in customizing the output.
- External systems like “Docker/CI” as a separate module that encompasses build, test, and deployment tools.

##### Final Recommendation
- Don’t overcomplicate: capture as many of the project's distinct components as possible, given its modular structure.
- Maintain consistency with the file structure and README features—this will give any stakeholder a clear view of how the system operates and how each module relates to the overall goal of converting C4 models into a rich static website.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Subgraph
    subgraph "Command Line Interface (CLI)"
        CLI_Gen["GenerateSiteCommand"]:::cli
        CLI_Serve["ServeCommand"]:::cli
        CLI_Version["VersionCommand"]:::cli
    end

    %% DSL Parser
    DSL_Parser["DSL Parser"]:::parser

    %% Configuration Manager
    ConfigManager["Configuration Manager"]:::config

    %% Main Processing Engine Subgraph
    subgraph "Site Generation Engine"
        Engine_Core["SiteGenerator"]:::engine
        GeneratorContext["GeneratorContext"]:::engine

        subgraph "Diagram Generation Subsystem"
            DiagramGen["DiagramGenerator"]:::subprocess
            PlantUmlExp["PlantUmlExporter"]:::subprocess
        end

        subgraph "Documentation & ADR Processor"
            DocProcessor_Model["DocProcessor (Model)"]:::subprocess
            DocProcessor_Views["DocProcessor (Views)"]:::subprocess
        end

        AssetManager["Asset Manager"]:::subprocess
    end

    %% Website Build Output and Serving
    StaticSite["Static Website Build Directory"]:::output
    DevServer["Development Server"]:::server

    %% External Build & Deployment
    BuildDeploy["Build & Deployment"]:::external
    TestSuite["Test Suite"]:::external

    %% Data Flow Connections
    CLI_Gen --> DSL_Parser
    CLI_Serve --> DSL_Parser
    CLI_Version --> DSL_Parser

    DSL_Parser --> ConfigManager
    DSL_Parser --> Engine_Core

    ConfigManager --> Engine_Core

    %% Within Site Generation Engine, consolidate outputs
    Engine_Core --> StaticSite
    GeneratorContext --> StaticSite
    DiagramGen --> StaticSite
    PlantUmlExp --> StaticSite
    DocProcessor_Model --> StaticSite
    DocProcessor_Views --> StaticSite
    AssetManager --> StaticSite

    %% Serve static site if in serve mode
    StaticSite --> DevServer

    %% External integrations (dashed connections)
    Engine_Core --- BuildDeploy
    Engine_Core --- TestSuite

    %% Click Events for CLI Components
    click CLI_Gen "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/GenerateSiteCommand.kt"
    click CLI_Serve "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/ServeCommand.kt"
    click CLI_Version "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/VersionCommand.kt"

    %% Click Event for DSL Parser
    click DSL_Parser "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/CreateStructurizrWorkspace.kt"

    %% Click Events for Site Generation Engine Components
    click Engine_Core "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/SiteGenerator.kt"
    click GeneratorContext "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/GeneratorContext.kt"
    click DiagramGen "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/DiagramGenerator.kt"
    click PlantUmlExp "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/PlantUmlExporter.kt"
    click DocProcessor_Model "https://github.com/avisi-cloud/structurizr-site-generatr/tree/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/model"
    click DocProcessor_Views "https://github.com/avisi-cloud/structurizr-site-generatr/tree/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/views"
    click AssetManager "https://github.com/avisi-cloud/structurizr-site-generatr/tree/main/src/main/resources/assets"

    %% Click Event for Development Server
    click DevServer "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/src/main/kotlin/nl/avisi/structurizr/site/generatr/ServeCommand.kt"

    %% Click Events for Build & Deployment
    click BuildDeploy "https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/build.gradle.kts"
    click BuildDeploy "https://github.com/avisi-cloud/structurizr-site-generatr/tree/main/Dockerfile"
    click BuildDeploy "https://github.com/avisi-cloud/structurizr-site-generatr/tree/main/gradle/wrapper"

    %% Click Event for Test Suite
    click TestSuite "https://github.com/avisi-cloud/structurizr-site-generatr/tree/main/src/test/kotlin/nl/avisi/structurizr/site/generatr"

    %% Styles
    classDef cli fill:#FFDD99,stroke:#D35400,stroke-width:2px;
    classDef parser fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef config fill:#D5F5E3,stroke:#239B56,stroke-width:2px;
    classDef engine fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef subprocess fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
    classDef output fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef server fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
