# swablab/documents architecture

> Architecture diagram of the GitHub repository swablab/documents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swablab/documents
- Repository: https://github.com/swablab/documents

## Overview

##### Project's Main Purpose and Components
- Purpose: The repository holds a set of document templates (with extension .typ) meant to be processed by Typst to generate official documents (such as spendenbescheinigung, protokoll, rechnung, etc.). It also includes configuration templates (.yml.template) for some documents, and tools for development automation.
- Main Components:
- Document Templates: These are the Typst files (e.g., spendenbescheinigung.typ, protokoll.typ) along with related YAML template files used for configuration.
- Common Template Directory: The "templates" folder contains shared template parts (e.g., common.typ, tmpl_doc.typ) that provide a reusable structure for various documents.
- Build and Execution Environment: This includes the Devcontainer configuration (.devcontainer folder), the Containerfile (for containerization), and VSCode settings (.vscode directory) that ensure consistency and automation in the development environment.
- CI/CD/Automation: The Forgejo workflows (inside the .forgejo/workflows directory) manage deployment or automated tasks like building or testing the templates.
- External Dependencies: Typst as the document compiler and external fonts (Noto and Ubuntu) are required to properly render the PDFs.

##### Relationships and Interactions
- Developers create or modify the Typst document files and their corresponding YAML configuration templates.
- When a change is made, the local development environment (using VSCode and Devcontainers) leverages the Containerfile configuration to provide a consistent Typst environment with all necessary fonts installed.
- The Typst compiler is then used (via commands shown in the README) to compile the template files into PDFs.
- The Forgejo CI/CD pipelines may pick up changes in the repository to automate tasks like deployment or further testing of the document generation process.
- The design also shows reusability: the "templates" folder provides common components that individual document templates include (via import mechanisms in Typst).

##### Architectural Patterns and Design Principles
- Modular Design: Each document template is a separate component that can reference common template blocks, making the system modular.
- Separation of Concerns: The system separates raw document content (the .typ files), configuration (YAML templates), and environment/setup (Devcontainer, Containerfile, VSCode configuration).
- DevOps Integration: The inclusion of CI/CD workflows in Forgejo shows a move towards automation and continuous integration in document generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Files
    subgraph "Source Files"
        subgraph "Document Templates"
            DT1["spendenbescheinigung.typ"]:::docTemplate
            DT2["protokoll.typ"]:::docTemplate
            DT3["rechnung.typ"]:::docTemplate
        end
        subgraph "Configuration Files"
            CF1["protokoll.yml.template"]:::configFile
        end
        subgraph "Template Partials"
            TP1["common.typ"]:::partial
        end
    end

    %% Development Environment
    subgraph "Development Environment"
        DEV1["Devcontainer"]:::devEnv
        DEV2["Containerfile"]:::devEnv
        DEV3["VSCode Settings"]:::devEnv
    end

    %% CI/CD Pipelines and External Dependencies
    CID["CI/CD Pipelines"]:::ciCd
    ED["External Dependencies"]:::external

    %% Processing and Output
    TC["Typst Compiler"]:::process
    PDF["PDF Documents"]:::process

    %% Connections from Source Files to Compiler
    DT1 -->|"compile"| TC
    DT2 -->|"compile"| TC
    DT3 -->|"compile"| TC
    CF1 -->|"config"| TC
    TP1 -->|"include"| TC

    %% Connections from Environment and Automation to Compiler
    DEV1 -->|"env"| TC
    CID -->|"automation"| TC
    ED -->|"dependency"| TC

    %% Final Output
    TC -->|"generates"| PDF

    %% Click Events
    click DT1 "https://github.com/swablab/documents/blob/main//spendenbescheinigung.typ"
    click DT2 "https://github.com/swablab/documents/blob/main//protokoll.typ"
    click DT3 "https://github.com/swablab/documents/blob/main//rechnung.typ"
    click CF1 "https://github.com/swablab/documents/blob/main//protokoll.yml.template"
    click TP1 "https://github.com/swablab/documents/blob/main//templates/common.typ"
    click DEV1 "https://github.com/swablab/documents/blob/main//.devcontainer/devcontainer.json"
    click DEV2 "https://github.com/swablab/documents/tree/main/Containerfile"
    click DEV3 "https://github.com/swablab/documents/blob/main/.vscode"
    click CID "https://github.com/swablab/documents/blob/main//.forgejo/workflows/deploy.yml"

    %% Styles
    classDef docTemplate fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef configFile fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef partial fill:#ffdd99,stroke:#333,stroke-width:2px;
    classDef devEnv fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef ciCd fill:#d9ccff,stroke:#333,stroke-width:2px;
    classDef external fill:#e6e6e6,stroke:#333,stroke-width:2px;
    classDef process fill:#ffffcc,stroke:#333,stroke-width:2px;
```
