# cot-rs/cot-site architecture

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

- Interactive diagram: https://gitdiagram.com/cot-rs/cot-site
- Repository: https://github.com/cot-rs/cot-site

## Overview

##### Project type and purpose
- Cot-site is a Rust-based static/dynamic website generator for the Cot web framework’s documentation.
- It reads Markdown “guides” and “md-pages”, processes them via Rust macros and templates, then serves them over HTTP (or builds static assets for Nginx).

##### File structure
- Top-level “src/” contains the Rust web-server code (`main.rs`, `guides.rs`, MD pages).
- “cot-site-common/” and “cot-site-macros/” are internal libraries:
- common: shared logic for loading MD pages, serving paths
- macros: compile-time MD→HTML embedding
- “templates/” holds all HTML templates (`.html`).
- “static/” houses images, JS, and webmanifest.
- “scss/” & “syntax-highlighting/” feed SCSS and syntax themes into the front end.
- “nginx/” defines a Dockerized static-file server.
- Dockerfiles, docker-compose, CI YAMLs show containerization and CI pipeline.
- “scripts/” includes helper scripts (e.g. favicons).

##### Extract insights from the README
- No external services (DB/etc).
- Dev flow: `cargo run` to launch the Rust HTTP server.
- Nightly + features for live MD macro reload.
- Optionally use “bacon” for live-reload.

##### Main components
a. Developer environment
- Rust toolchain (stable + nightly)
- bacon (optional live-reload)
- Docker & Docker-Compose (for production build)
b. Build pipeline
- cot-site-macros → procedural macro transforms `.md` → Rust functions
- cot-site-common → MD page loader & shared utilities
- scss compiler → CSS assets
- syntax-highlighting assets → JS/CSS
- Rust compiler (build.rs, Cargo) → binary
c. Runtime / Server
- Rust HTTP server (serves dynamic docs)
- Template engine renders HTML
- Static assets (CSS/JS/images) served from memory or disk
d. Deployment
- Docker container running the Rust binary behind an Nginx reverse proxy
- Optional separate Nginx container for pure static hosting
e. External tools/services
- GitHub Actions (CI for Rust build & Docker images)
- Docker Hub (or registry)

##### Relationships & data-flow
- Developer → triggers build (Cargo or Docker-Compose)
- MD files + macros + templates → compile → Rust binary
- SCSS & syntax themes → compiled static assets
- At runtime: HTTP request → Rust server → template + HTML → HTTP response
- Browser ← served HTML + CSS/JS ← Nginx or Rust server
- CI pipeline → validates build → publishes Docker image

##### Architectural patterns & design principles
- Monolithic Rust application using modular internal crates
- Compile-time code generation (procedural macros) for MD processing
- Separation of concerns:
- Content (Markdown)
- Presentation (Templates + SCSS)
- Logic (Rust server + common lib)
- Infrastructure (Docker, Nginx)
- Dev/Prod parity via Docker-Compose

##### Next steps for the principal software engineer
- Out each node/component as above.
- Related items (e.g., internal crates vs external tools).
- Sketch arrowed flows, validate with team.
- Iterate: add infrastructure (Docker-Compose networks, volumes) if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        RustToolchain["Rust Toolchain"]:::tool
        Bacon["bacon (Live-Reload)"]:::tool
        DockerComposeDev["Docker & Docker-Compose"]:::tool
    end

    %% Content
    subgraph "Content Source"
        MDContent["Markdown Content"]:::content
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        Macros["cot-site-macros"]:::code
        Common["cot-site-common"]:::code
        SCSSCompiler["SCSS Compiler"]:::tool
        SyntaxAssets["Syntax Highlighting Themes"]:::asset
        RustCompiler["Rust Compiler (Cargo)"]:::tool
    end

    %% Runtime Server
    subgraph "Runtime / Server"
        RustServer["Rust HTTP Server"]:::runtime
        TemplateEngine["Template Engine"]:::runtime
        StaticAssets["Static Assets (CSS/JS/Images)"]:::asset
    end

    %% Deployment
    subgraph "Deployment"
        DockerBuild["Docker Build"]:::infra
        NginxStatic["Nginx Static-File Server"]:::infra
        DockerComposeProd["Docker-Compose Orchestration"]:::infra
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        GitHubActions["GitHub Actions"]:::external
        DockerRegistry["Docker Registry"]:::external
    end

    %% Developer to Build
    RustToolchain -->|"runs build"| RustCompiler
    Bacon -->|"enables live-reload"| Macros
    DockerComposeDev -->|"orchestrates build"| DockerBuild

    %% Build Flow
    MDContent -->|"source for"| Macros
    Macros -->|"generates code used by"| Common
    Common -->|"provides utilities to"| RustCompiler
    SCSSCompiler -->|"compiles to CSS"| StaticAssets
    SyntaxAssets -->|"packaged into"| StaticAssets
    RustCompiler -->|"outputs binary"| RustServer

    %% Runtime Flow
    RustServer -->|"uses"| TemplateEngine
    RustServer -->|"serves"| StaticAssets
    Browser[Browser]:::externalClient
    Browser -->|"HTTP Request"| RustServer
    RustServer -->|"HTTP Response"| Browser

    %% Static Deployment Flow
    StaticAssets -->|"deployed to"| NginxStatic
    Browser -->|"fetch static assets"| NginxStatic

    %% Deployment Orchestration
    DockerBuild -->|"builds image for"| RustServer
    DockerBuild -->|"includes config for"| NginxStatic
    DockerComposeProd -->|"runs services"| RustServer
    DockerComposeProd -->|"runs services"| NginxStatic

    %% CI/CD Flow
    GitHubActions -->|"validates build"| RustCompiler
    GitHubActions -->|"builds images"| DockerBuild
    GitHubActions -->|"pushes images to"| DockerRegistry

    %% Click Events
    click Common "https://github.com/cot-rs/cot-site/blob/master/cot-site-common/src/lib.rs"
    click Macros "https://github.com/cot-rs/cot-site/blob/master/cot-site-macros/src/lib.rs"
    click RustServer "https://github.com/cot-rs/cot-site/blob/master/src/main.rs"
    click Guides "https://github.com/cot-rs/cot-site/blob/master/src/guides.rs"
    click MDContent "https://github.com/cot-rs/cot-site/tree/master/src/md-pages/"
    click TemplateEngine "https://github.com/cot-rs/cot-site/blob/master/templates/_base.html"
    click StaticAssets "https://github.com/cot-rs/cot-site/tree/master/static/images/"
    click SCSSCompiler "https://github.com/cot-rs/cot-site/blob/master/scss/main.scss"
    click SyntaxAssets "https://github.com/cot-rs/cot-site/tree/master/syntax-highlighting/Packages"
    click NginxStatic "https://github.com/cot-rs/cot-site/blob/master/nginx/nginx.conf"
    click DockerBuild "https://github.com/cot-rs/cot-site/tree/master/Dockerfile"
    click DockerComposeDev "https://github.com/cot-rs/cot-site/blob/master/compose.yml"
    click DockerComposeProd "https://github.com/cot-rs/cot-site/blob/master/compose.yml"
    click RustCompiler "https://github.com/cot-rs/cot-site/blob/master/build.rs"
    click Bacon "https://github.com/cot-rs/cot-site/blob/master/bacon.toml"
    click GitHubActions "https://github.com/cot-rs/cot-site/blob/master/.github/workflows/rust.yml"

    %% Styles
    classDef tool fill:#E3F2FD,stroke:#90CAF9
    classDef code fill:#E8F5E9,stroke:#A5D6A7
    classDef content fill:#FFF3E0,stroke:#FFB74D
    classDef asset fill:#F3E5F5,stroke:#CE93D8
    classDef runtime fill:#E0F2F1,stroke:#80CBC4
    classDef infra fill:#FBE9E7,stroke:#FF8A65
    classDef external fill:#ECEFF1,stroke:#B0BEC5
    classDef externalClient fill:#FFEBEE,stroke:#EF9A9A
```
