How avisi-cloud/structurizr-site-generatr works
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.