# rustlanges/blog architecture

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

- Interactive diagram: https://gitdiagram.com/rustlanges/blog
- Repository: https://github.com/rustlanges/blog

## Overview

##### Project type and purpose
- This is a static‐site blog generator built in Rust (using Leptos for component‐based SSR/SSG) plus a Tailwind CSS pipeline via Node.js.
- It consumes Markdown files under `articles/` and `esta_semana_en_rust/`, generates HTML pages with a Rust SSG (`src/ssg.rs`, `src/render.rs`), runs CSS builds (`tailwind.config.js` + `input.css`), and outputs a static site in `out/`.
- A secondary Rust crate (`preview_generator/`) produces share‐image previews; a Python or Rust HTTP server serves the site locally. CI/CD is configured via GitHub Actions.

##### File structure
- Top‐level scripts and configs
- `.github/workflows/` – CI pipelines for build, tests, deploy
- `server` / `server.bat` – helper scripts that orchestrate `cargo watch`, CSS rebuilds, and static‐file serving
- `gen_translated.py` – custom script (e.g., for generating translations)
- `package.json` + `tailwind.config.js` – Node.js dependencies for Tailwind CSS
- `Cargo.toml`, `rust-toolchain.toml` – Rust toolchain and dependencies for the main app
- Source code for the main SSG
- `src/` – Leptos components (`components/`), pages (`pages/`), models, utilities, `ssg.rs` and `render.rs` entrypoints
- Secondary crate
- `preview_generator/` – its own `Cargo.toml` and Rust code to produce social‐media preview images
- Content
- `articles/`, `esta_semana_en_rust/` – Markdown content
- `assets/images/` – static assets for the site
- Build‐and‐deploy helpers
- `.github/workflows/*.yml` for CI and deployment
- `leptosfmt.toml`, `clippy.toml`, husky/githooks for linting

##### README insights
- Describes local dev requirements: Rust, Node.js, `cargo-watch`, `leptosfmt`
- Instructions to run parallel watchers: Rust rebuild + Tailwind CSS compiler + optional HTTP server
- Mentions Git hooks to enforce linting and formatting

a. Main components
1. Developer Workstation (IDE, Git CLI)
2. Content source: Markdown files (`articles/`, `esta_semana_en_rust/`) + assets
3. Rust SSG (Leptos app in `src/` + `ssg.rs`)
4. Tailwind CSS pipeline (Node.js + `input.css` → `output.css`)
5. Preview Generator (`preview_generator/` crate)
6. Build orchestrator (`cargo-watch`, `server` script)
7. Output directory (`out/`)
8. Local static server (Python `http.server` or `basic-http-server`)
9. CI/CD (GitHub Actions) → Deployment (e.g., GitHub Pages, Netlify)
b. Relationships and interactions
- Developer edits Markdown → Git → triggers local build or CI
- `cargo-watch` detects code/content changes → runs Rust SSG → generates HTML
- Simultaneously, Node.js Tailwind process compiles CSS → writes `out/output.css`
- `preview_generator` can be invoked during build to generate social preview images under `out/`
- Final static site (`out/`) served locally or deployed by CI to hosting
c. Architectural patterns and design principles
- Component‐based rendering (Leptos) with SSG for performance and SEO
- File‐watcher orchestration for rapid developer feedback
- Separation of concerns: content (Markdown), presentation (Leptos components + CSS), build logic (Rust + Node)
- Extensible plugin‐like preview generator as a separate crate
d. Key technologies
- Rust + Leptos for SSG and page components
- Node.js + Tailwind CSS for styling
- cargo-watch for live rebuilds
- Python or Rust HTTP server for local preview
- GitHub Actions for CI and deploy
- Markdown content with front‐matter

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Sources
    subgraph "Content Sources"
        A1["Markdown Articles"]:::node_content
        A2["This Week in Rust Markdown"]:::node_content
        A3["Assets (images)"]:::node_content
    end

    %% Build Tools & Scripts
    subgraph "Build Orchestrator" 
        B1["server"]:::scripts
        B2["server.bat"]:::scripts
        B3["cargo-watch"]:::rust
    end

    %% Static-Site Generator (Rust)
    subgraph "Rust SSG" 
        C1["src/ssg.rs"]:::rust
        C2["src/render.rs"]:::rust
        subgraph "Leptos App"
            C3["src/main.rs"]:::rust
            C4["src/components/"]:::rust
            C5["src/pages/"]:::rust
            C6["src/models/"]:::rust
            C7["src/utils/"]:::rust
            C8["src/meta.rs"]:::rust
            C9["src/async_component.rs"]:::rust
        end
    end

    %% Tailwind CSS Pipeline
    subgraph "Tailwind CSS Pipeline" 
        D1["input.css"]:::nodejs
        D2["tailwind.config.js"]:::nodejs
        D3["package.json"]:::nodejs
        D4["package-lock.json"]:::nodejs
    end

    %% Preview Generator
    subgraph "Preview Image Generator" 
        E1["preview_generator/"]:::rust
    end

    %% Output and Deployment
    subgraph "Output & Deployment"
        F1["out/ (Static Site)"]:::output
        F2["Local Server"]:::scripts
        F3["CI/CD (GitHub Actions)"]:::ci
    end

    %% Flows
    A1 -->|provides Markdown| C1
    A2 -->|provides Markdown| C1
    A3 -->|static assets| F1

    B1 -->|watches changes| C1
    B2 -->|watches changes| C1
    B3 -->|watches changes| C1

    C1 -->|uses| C2
    C2 -->|renders HTML| F1

    C1 -->|calls| E1
    E1 -->|generates previews| F1

    D1 -->|input to| D2
    D2 -->|compiles CSS| F1
    D3 -->|manages deps| D2
    D4 -->|locks deps| D2

    F1 -->|serves via| F2
    F1 -->|deploys via| F3

    %% Click Events
    click A1 "https://github.com/rustlanges/blog/tree/main/articles/"
    click A2 "https://github.com/rustlanges/blog/tree/main/esta_semana_en_rust/"
    click C1 "https://github.com/rustlanges/blog/blob/main/src/ssg.rs"
    click C2 "https://github.com/rustlanges/blog/blob/main/src/render.rs"
    click C3 "https://github.com/rustlanges/blog/blob/main/src/main.rs"
    click C4 "https://github.com/rustlanges/blog/tree/main/src/components/"
    click C5 "https://github.com/rustlanges/blog/tree/main/src/pages/"
    click C6 "https://github.com/rustlanges/blog/tree/main/src/models/"
    click C7 "https://github.com/rustlanges/blog/tree/main/src/utils/"
    click C8 "https://github.com/rustlanges/blog/blob/main/src/meta.rs"
    click C9 "https://github.com/rustlanges/blog/blob/main/src/async_component.rs"
    click D1 "https://github.com/rustlanges/blog/blob/main/input.css"
    click D2 "https://github.com/rustlanges/blog/blob/main/tailwind.config.js"
    click D3 "https://github.com/rustlanges/blog/blob/main/package.json"
    click D4 "https://github.com/rustlanges/blog/blob/main/package-lock.json"
    click E1 "https://github.com/rustlanges/blog/tree/main/preview_generator/"
    click B1 "https://github.com/rustlanges/blog/tree/main/server"
    click B2 "https://github.com/rustlanges/blog/blob/main/server.bat"
    click F3 "https://github.com/rustlanges/blog/tree/main/.github/workflows/"

    %% Styles
    classDef rust fill:#fcae1e,stroke:#333,stroke-width:1px;
    classDef nodejs fill:#1e90ff,stroke:#333,stroke-width:1px;
    classDef scripts fill:#32cd32,stroke:#333,stroke-width:1px;
    classDef ci fill:#9370db,stroke:#333,stroke-width:1px;
    classDef output fill:#eeeeee,stroke:#333,stroke-width:1px;
    classDef node_content fill:#fff5ba,stroke:#333,stroke-width:1px;
```
