# vhquan/ssg architecture

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

- Interactive diagram: https://gitdiagram.com/vhquan/ssg
- Repository: https://github.com/vhquan/ssg

## Overview

##### Project Type and Purpose
- This is a modern, lightweight static site generator written in Rust. Its purpose is to take markdown content from the resources provided by the user, process it (applying syntax highlighting, templating, and markdown conversion), and generate a static HTML website complete with CSS styling.
- The README underlines features like tag-based content organization, responsive design, and code syntax highlighting, which point to a system that processes content and renders it through templates.

##### Analyzing the File Structure
- Top-level files include the Cargo configuration files (Cargo.toml and Cargo.lock) and the README. This denotes a typical Rust project.
- The src/ directory holds the core logic with modules like:
- generator.rs – likely orchestrates the generation process from markdown to HTML.
- markdown.rs – handles markdown parsing.
- models.rs – contains data structures.
- server.rs – probably provides functionality to run a local development server, allowing for live preview.
- utils.rs – contains helper functions.
- lib.rs and main.rs – expose library functions and define the executable entry point respectively.
- The templates/ directory contains Tera HTML templates which the generator uses to create the website pages.
- The style/ directory contains the CSS files.
- The resources/ directory contains the markdown and other source content from which the site is built.
- Although a static output folder (“static/”) is mentioned in the README, it isn’t directly seen in the file tree. It could be generated at runtime or simply not tracked in version control.

##### Main Components
a. Input/Content Layer:
- Resources/ directory as the source of markdown content.
b. Processing Layer:
- A block representing the core of the static site generator that includes:
- Markdown Parsing (handled in markdown.rs)
- Content Modeling (using models.rs)
- Code Syntax Highlighting (integrated via Highlight.js in the templates)
- Generation Logic (in generator.rs)
- Templating Integration (using the Tera engine in connection with templates/)
- A connection showing that content flows from the resources folder through the generator’s logic.
c. Output/Presentation Layer:
- A block for the templates/ and style/ directories:
- Templates are combined with the processed data to create HTML.
- The style folder supplies the CSS, and Highlight.js (referenced in base.html) provides syntax highlighting.
d. serving & Development:
- Server component (from server.rs) as a mechanism to host the generated site locally for development purposes, showing how it sits between the Generation Logic and the user’s browser.

##### Architectural Relationships & Patterns
- The separation between content input (resources/) and presentation (templates/ and style/) emphasizes a clear separation-of-concerns, similar to MVC principles:
- The “model” is represented by the data structures in models.rs.
- The “view” is handled via the Tera templates and CSS styles.
- The “controller” aspect is performed via the generator and server modules that orchestrate the flow.
- The build process (via Cargo and command-line instructions: “cargo run -- build” or “cargo run -- serve”) should be shown as the initial trigger that activates the core processing logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input/Content Layer
    subgraph "Input/Content Layer"
        RES("resources/"):::input
    end

    %% Processing Engine
    subgraph "Processing Engine"
        MD("Markdown Parsing Module"):::processing
        DM("Data Modeling Module"):::processing
        GEN("Generation Logic Module"):::processing
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        subgraph "Templates"
            BASE("Base Template"):::presentation
            INDEX("Index Template"):::presentation
            TAG("Tag Template"):::presentation
        end
        STYLE("CSS Styling"):::presentation
    end

    %% Build and Output
    BUILD("Cargo Build (cargo run)"):::build
    STATIC("Static Output (HTML/CSS)"):::presentation
    SERVER("Development Server"):::server
    BROWSER("User Browser"):::external

    %% Flow Connections
    BUILD -->|"triggers"| MD
    RES -->|"provides markdown"| MD
    MD -->|"populates"| DM
    DM -->|"feeds data to"| GEN
    GEN -->|"applies templating"| BASE
    GEN -->|"applies templating"| INDEX
    GEN -->|"applies templating"| TAG
    BASE -->|"renders page"| STATIC
    INDEX -->|"renders page"| STATIC
    TAG -->|"renders page"| STATIC
    STYLE -->|"styles output"| STATIC
    STATIC -->|"served by"| SERVER
    SERVER -->|"accessed by"| BROWSER

    %% Click Events for Component Mapping
    click RES "https://github.com/vhquan/ssg/tree/main/resources/"
    click MD "https://github.com/vhquan/ssg/blob/main/src/markdown.rs"
    click DM "https://github.com/vhquan/ssg/blob/main/src/models.rs"
    click GEN "https://github.com/vhquan/ssg/blob/main/src/generator.rs"
    click BASE "https://github.com/vhquan/ssg/blob/main/templates/base.html"
    click INDEX "https://github.com/vhquan/ssg/blob/main/templates/index.html"
    click TAG "https://github.com/vhquan/ssg/blob/main/templates/tag.html"
    click STYLE "https://github.com/vhquan/ssg/blob/main/style/style.css"
    click SERVER "https://github.com/vhquan/ssg/blob/main/src/server.rs"

    %% Styles
    classDef input fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef processing fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef presentation fill:#C8FACC,stroke:#333,stroke-width:2px;
    classDef server fill:#FFD1BA,stroke:#333,stroke-width:2px;
    classDef build fill:#F7A8A8,stroke:#333,stroke-width:2px;
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:2px;
```
