# mrxiaozhuox/karaty architecture

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

- Interactive diagram: https://gitdiagram.com/mrxiaozhuox/karaty
- Repository: https://github.com/mrxiaozhuox/karaty

## Overview

##### Project type and purpose
- Karaty is a Rust-based static site framework and WASM-powered SPA for blogs & docs, built on Dioxus.
- At build time it runs a CLI tool (`karaty` crate) that reads configs and source content; at runtime it serves a single `.wasm` UI that fetches and renders Markdown.

##### File structure
- Top-level crates/examples:
- `karaty/` – the main application (binary + library)
- `blueprint/`, `docsite/`, `template/` – example/template crates demonstrating custom themes or docs sites
- `karaty/` substructure:
- `src/config.rs` – loads `karaty.toml`
- `src/utils/markdown.rs` – parses Markdown
- `src/utils/template_loader.rs` – loads Dioxus templates
- `src/hooks/`, `src/components/`, `src/pages/` – Dioxus UI modules
- `public/` data and asset outputs for runtime fetch
- Build/deploy infrastructure:
- `.github/workflows/*.yml` – CI/CD pipelines
- `forked.py`, `version.py` – utility scripts
- `Cargo.toml` files in each crate

##### Extract insights from the README
- Single `.wasm` file delivers dynamic content without rebuild
- Config via `karaty.toml` controls site routing & templates
- Exported static files deployable to GitHub Pages or any static server
- Extensible via Dioxus templates and custom crates

##### Main components
a. Build-time pipeline (CLI tool)
- Input: `karaty.toml` config + Markdown source under `karaty/data/`
- Processing: Rust binary (`karaty` crate)
– Config loader → data source scanner → Markdown parser → template assembler
- Output: `public/` directory + `index.html` + `karaty.wasm` + assets
b. Runtime (Browser)
- Dioxus WASM frontend (`karaty.wasm`)
- Fetches Markdown/JSON content from `public/data/`
- Renders pages via Dioxus components (nav, markdown, footer, etc.)
c. Example/template crates
- `blueprint`, `docsite`, `template`
- Plug into the build process as custom themes or site examples
d. Deployment targets
- GitHub Pages (via `404.html` trick)
- Any static file server

##### Relationships & data flows
- Dependencies: CLI relies on Dioxus-CLI, Serde, TOML/JSON, Markdown library; Frontend uses Dioxus components & hooks

##### Architectural patterns & principles
- Modular multi-crate workspace (core + examples)
- Clear separation of concerns:
- Build-time static site generator vs. runtime WASM SPA
- Plugin-style templating (users supply custom Dioxus UIs)
- Data-driven routing: config file drives URL mapping

##### Relevant technologies & frameworks
- Rust (Cargo)
- Dioxus (WASM UI)
- Markdown, TOML, JSON
- GitHub Actions (CI/CD)
- Tailwind CSS (via `public/assets/tailwind`)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Build-time Pipeline
  subgraph "Build-time Pipeline"
    direction TB
    CLI["karaty CLI"]:::build
    Config["Config Loader"]:::build
    Scanner["Data Source Scanner"]:::build
    Parser["Markdown Parser"]:::build
    TLoader["Template Assembler"]:::build
    Static["Static Output"]:::build
  end

  %% Runtime SPA
  subgraph "Runtime (Browser)"
    direction TB
    WASM["karaty.wasm (Dioxus WASM SPA)"]:::runtime
    Fetch["Fetch content from public/data"]:::runtime
    UI["Dioxus Components & Hooks"]:::runtime
  end

  %% Example Plugins
  subgraph "Example/Template Crates"
    direction TB
    blueprint["blueprint crate"]:::plugin
    docsite["docsite crate"]:::plugin
    templateCr["template crate"]:::plugin
  end

  %% Deployment Targets
  subgraph "Deployment Targets"
    direction TB
    GH["GitHub Pages"]:::deploy
    SV["Static File Server"]:::deploy
  end

  %% Connections
  CLI -->|"loads config"| Config
  Config -->|"scans data"| Scanner
  Scanner -->|"parses Markdown"| Parser
  Parser -->|"assembles templates"| TLoader
  TLoader -->|"outputs static site"| Static

  Static -->|"serves wasm"| WASM
  WASM -->|"HTTP fetch"| Fetch
  Fetch -->|"renders with"| UI

  blueprint -->|"plugs into"| CLI
  docsite -->|"plugs into"| CLI
  templateCr -->|"plugs into"| CLI

  Static -->|"deploy"| GH
  Static -->|"deploy"| SV

  %% Click events
  click CLI "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/src/main.rs"
  click CLI "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/build.rs"
  click CLI "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/Cargo.toml"
  click Config "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/src/config.rs"
  click Config "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/karaty.toml"
  click Config "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/config/routing.toml"
  click Config "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/config/template.toml"
  click Scanner "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/src/utils/data.rs"
  click Scanner "https://github.com/mrxiaozhuox/karaty/tree/main/karaty/data/"
  click Parser "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/src/utils/markdown.rs"
  click TLoader "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/src/utils/template_loader.rs"
  click WASM "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/src/setup.rs"
  click UI "https://github.com/mrxiaozhuox/karaty/blob/main/karaty/src/components/mod.rs"
  click Static "https://github.com/mrxiaozhuox/karaty/tree/main/karaty/public/"
  click blueprint "https://github.com/mrxiaozhuox/karaty/tree/main/blueprint/"
  click docsite "https://github.com/mrxiaozhuox/karaty/tree/main/docsite/"
  click templateCr "https://github.com/mrxiaozhuox/karaty/tree/main/template/"

  %% Styles
  classDef build fill:#BBE1FA,stroke:#1B262C,color:#1B262C
  classDef runtime fill:#DFF7DF,stroke:#1B262C,color:#1B262C
  classDef plugin fill:#FFD8A9,stroke:#1B262C,color:#1B262C
  classDef deploy fill:#EDEDED,stroke:#1B262C,color:#1B262C
```
