# sinotca529/zakki architecture

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

- Interactive diagram: https://gitdiagram.com/sinotca529/zakki
- Repository: https://github.com/sinotca529/zakki

## Overview

##### Project Type and Purpose
- zakki is a CLI-based static site generator written in Rust.
- It reads Markdown from a source directory (public, private, draft), applies a configurable pipeline of renderer passes, manages assets and templates, optionally encrypts pages, builds a search index using a Bloom filter, and writes pure HTML/CSS/JS to a build directory.

##### High-Level Components
- CLI Layer
- `src/main.rs` + `src/command/*` (init, build, clean)
- Dispatches subcommands and parses flags (e.g. `-d` for drafts).
- Configuration Loader
- `zakki.toml` → parsed by `src/config.rs`.
- Source File System
- `src/public/`, `src/private/`, `src/draft/` (per README)
- Markdown + optional assets per page folder.
- Build Pipeline (Build Command)
- Entry: `src/command/build.rs` → `build::renderer::RenderingContext`
- Template Engine: `html_template.rs` + asset HTML fragments under `asset/`
- Pipeline of Passes (under `renderer/pass/`):
- assign_header_id, get_title, toc_pass, convert_math (KaTeX), highlight_code, image_convert, link_adjust, table_wrapper, read_header, etc.
- Utility Modules
- `util/file_io.rs`, `util/path_ext.rs` (I/O & path helpers)
- `util/aes_256_cbc.rs` (encryption for private pages)
- `util/bloom_filter.rs` + `util/segmenter.rs` (search index generator)
- `util/fxhash.rs`, `util/vec_ext.rs` (performance helpers).
- Asset Manager
- Static assets (`asset/style.css`, `asset/script.js`, fonts, KaTeX assets).
- Copied wholesale into output or injected into templates.
- Output File System
- `build/` directory mirroring the final site structure with HTML/CSS/JS.
- Continuous Integration / Release
- `.github/workflows/release.yml` handles build & publish to crates.io/GitHub Releases.

##### Relationships & Data Flow
- User invokes `zakki build` → CLI Layer
→ Configuration Loader reads `zakki.toml`
→ Source File System scan
→ Build Pipeline:
- For each Markdown page, pass through Renderer Context → sequence of Pass modules → HTML string injected into page template → encryption module (if in private) → write to Output FS
→ Asset Manager copies over CSS/JS/fonts → generate Bloom filter index → write index to Output FS
- `zakki init` scaffolds new project tree.
- CI Workflow triggers on tag → runs tests, builds binary, publishes.

##### Architectural Patterns & Principles
- Command Pattern (one module per subcommand).
- Pipeline / Chain-of-Responsibility for renderer passes.
- Modular utilities for cross-cutting concerns (I/O, crypto, hashing, filtering).
- Template-driven code generation (HTML fragments under `asset/`).
- Separation of concerns: parsing, rendering, templating, encryption, search indexing, asset management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Components
    subgraph "CLI Layer"
        direction TB
        CLI["CLI Layer"]:::core
        Main["main.rs"]:::core
        CommandRs["command.rs"]:::core
        BuildCmd["build.rs"]:::core
        InitCmd["init.rs"]:::core
        CleanCmd["clean.rs"]:::core
    end

    subgraph "Configuration Loader"
        direction TB
        Toml["zakki.toml"]:::io
        ConfigRs["config.rs"]:::io
    end

    subgraph "Source File System" 
        direction TB
        Public["src/public/"]:::io
        Private["src/private/"]:::io
        Draft["src/draft/"]:::io
    end

    subgraph "Build Pipeline" 
        direction TB
        BuildEntry["build command"]:::core
        RendererCtx["RenderingContext"]:::core
        TemplateEng["html_template.rs"]:::core
        subgraph "Passes"
            direction TB
            AssignID["assign_header_id_pass"]:::core
            Title["get_title_pass"]:::core
            TOC["toc_pass"]:::core
            TocUtil["toc.rs"]:::core
            Math["convert_math_pass"]:::core
            Highlight["highlight_code_pass"]:::core
            ImgConv["image_convert_pass"]:::core
            LinkAdj["link_adjust_pass"]:::core
            ReadHdr["read_header_pass"]:::core
            TableWrap["table_wrapper_pass"]:::core
        end
    end

    subgraph "Utility Modules"
        direction TB
        FileIO["file_io.rs"]:::io
        PathExt["path_ext.rs"]:::io
        AES["aes_256_cbc.rs"]:::sec
        Bloom["bloom_filter.rs"]:::search
        Segmenter["segmenter.rs"]:::search
        FxHash["fxhash.rs"]:::perf
        VecExt["vec_ext.rs"]:::perf
    end

    subgraph "Asset Manager"
        direction TB
        StyleCSS["style.css"]:::assets
        ScriptJS["script.js"]:::assets
        SegJS["segmenter.js"]:::assets
        ThemeJS["theme.js"]:::assets
        CryptoHTML["crypto.html"]:::assets
        HeadHTML["head.html"]:::assets
        HeaderHTML["header.html"]:::assets
        IndexHTML["index.html"]:::assets
        PageHTML["page.html"]:::assets
        FontDir["font/"]:::assets
        KatexDir["katex/"]:::assets
    end

    subgraph "Output File System"
        direction TB
        BuildDir["build/"]:::io
    end

    subgraph "CI / Release"
        direction TB
        CIFlow["release.yml"]:::ext
        GitHub["GitHub Actions"]:::ext
        Crates["crates.io"]:::ext
    end

    %% Connections
    CLI -->|invokes| BuildEntry
    CLI -->|invokes| InitCmd
    CLI -->|invokes| CleanCmd
    CLI -->|parses flags| ConfigRs
    Toml -->|parsed by| ConfigRs
    BuildEntry -->|reads| Public
    BuildEntry -->|reads| Private
    BuildEntry -->|reads| Draft
    BuildEntry --> RendererCtx
    RendererCtx --> TemplateEng
    TemplateEng -->|injects fragments| StyleCSS
    TemplateEng -->|injects fragments| HeadHTML
    TemplateEng -->|injects fragments| HeaderHTML
    RendererCtx --> AssignID
    RendererCtx --> Title
    Title --> TOC
    TOC --> TocUtil
    RendererCtx --> Math
    RendererCtx --> Highlight
    RendererCtx --> ImgConv
    RendererCtx --> LinkAdj
    RendererCtx --> ReadHdr
    RendererCtx --> TableWrap
    RendererCtx --> AES
    RendererCtx -->|calls| Bloom
    Bloom --> Segmenter
    RendererCtx -->|output html| BuildDir
    StyleCSS --> BuildDir
    ScriptJS --> BuildDir
    SegJS --> BuildDir
    ThemeJS --> BuildDir
    FontDir --> BuildDir
    KatexDir --> BuildDir
    CIFlow -->|uses| GitHub
    CIFlow -->|publishes| Crates

    %% Click Events
    click Main "https://github.com/sinotca529/zakki/blob/main/src/main.rs"
    click CommandRs "https://github.com/sinotca529/zakki/blob/main/src/command.rs"
    click BuildCmd "https://github.com/sinotca529/zakki/blob/main/src/command/build.rs"
    click InitCmd "https://github.com/sinotca529/zakki/blob/main/src/command/init.rs"
    click CleanCmd "https://github.com/sinotca529/zakki/blob/main/src/command/clean.rs"
    click Toml "https://github.com/sinotca529/zakki/blob/main/zakki.toml"
    click ConfigRs "https://github.com/sinotca529/zakki/blob/main/src/config.rs"
    click BuildEntry "https://github.com/sinotca529/zakki/blob/main/src/command/build.rs"
    click RendererCtx "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/context.rs"
    click TemplateEng "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/html_template.rs"
    click AssignID "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/assign_header_id.rs"
    click Title "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/get_title_pass.rs"
    click TOC "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/toc_pass.rs"
    click TocUtil "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/toc_pass/toc.rs"
    click Math "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/convert_math_pass.rs"
    click Highlight "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/highlight_code_pass.rs"
    click ImgConv "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/image_convert_pass.rs"
    click LinkAdj "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/link_adjust_pass.rs"
    click ReadHdr "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/read_header_pass.rs"
    click TableWrap "https://github.com/sinotca529/zakki/blob/main/src/command/build/renderer/pass/table_wrapper_pass.rs"
    click FileIO "https://github.com/sinotca529/zakki/blob/main/src/util/file_io.rs"
    click PathExt "https://github.com/sinotca529/zakki/blob/main/src/util/path_ext.rs"
    click AES "https://github.com/sinotca529/zakki/blob/main/src/util/aes_256_cbc.rs"
    click Bloom "https://github.com/sinotca529/zakki/blob/main/src/util/bloom_filter.rs"
    click Segmenter "https://github.com/sinotca529/zakki/blob/main/src/util/segmenter.rs"
    click FxHash "https://github.com/sinotca529/zakki/blob/main/src/util/fxhash.rs"
    click VecExt "https://github.com/sinotca529/zakki/blob/main/src/util/vec_ext.rs"
    click StyleCSS "https://github.com/sinotca529/zakki/blob/main/asset/style.css"
    click ScriptJS "https://github.com/sinotca529/zakki/blob/main/asset/script.js"
    click SegJS "https://github.com/sinotca529/zakki/blob/main/asset/segmenter.js"
    click ThemeJS "https://github.com/sinotca529/zakki/blob/main/asset/theme.js"
    click CryptoHTML "https://github.com/sinotca529/zakki/blob/main/asset/crypto.html"
    click HeadHTML "https://github.com/sinotca529/zakki/blob/main/asset/head.html"
    click HeaderHTML "https://github.com/sinotca529/zakki/blob/main/asset/header.html"
    click IndexHTML "https://github.com/sinotca529/zakki/blob/main/asset/index.html"
    click PageHTML "https://github.com/sinotca529/zakki/blob/main/asset/page.html"
    click FontDir "https://github.com/sinotca529/zakki/tree/main/asset/font/"
    click KatexDir "https://github.com/sinotca529/zakki/tree/main/asset/katex/"
    click CIFlow "https://github.com/sinotca529/zakki/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef core fill:#d0e7ff,stroke:#023e8a,color:#03045e;
    classDef io fill:#d8f3dc,stroke:#40916c,color:#1b4332;
    classDef sec fill:#ffe5d9,stroke:#f94144,color:#9d0208;
    classDef search fill:#e5dbff,stroke:#6930c3,color:#3a0ca3;
    classDef perf fill:#f0efeb,stroke:#495057,color:#343a40;
    classDef assets fill:#f8f9fa,stroke:#868e96,color:#495057;
    classDef ext fill:#f1f3f5,stroke:#adb5bd,color:#495057;
```
