# ss-vip/blog architecture

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

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

## Overview

##### Project Type and Purpose
- This is a static site / blog built with Hugo (a static site generator), enhanced with a headless CMS (DecapCMS) and serverless API endpoints, and deployed on Cloudflare Pages.
- Purpose: serve a simple, ad-free technical blog; allow non-technical editors to update content via a web UI (DecapCMS); host on a fast global CDN with serverless functions for CMS authentication.

##### Main Components
a. Content Repository (Git)
- Stores markdown files under `/content` (about, posts).
- Stores Hugo config (`hugo.toml`) and theme-related files.
- Stores DecapCMS admin UI under `/static/admin`.
- Stores serverless function code under `/functions/api`.
b. Build Service (Cloudflare Pages + Hugo)
- Listens for Git pushes/merges.
- Runs Hugo build using `hugo.toml` + FixIt theme + `/content` → generates static HTML/CSS/JS.
c. Static CDN (Cloudflare Pages)
- Hosts the generated static site at `is-cool.dev`.
- Serves `/index.html`, `/about`, `/posts/...`, `/robots.txt`, `/google25*.html`.
d. Headless CMS UI (DecapCMS)
- Served from `/admin/index.html` on the same CDN.
- Client-side JS reads `/static/admin/config.yml` for API endpoints.
e. Serverless API (Cloudflare Functions)
- Two endpoints: `api/auth.js` and `api/callback.js`.
- Handle OAuth handshake with Git provider (e.g., GitHub) to enable Git-based commits from the CMS.
f. External Service
- Git hosting (e.g., GitHub) for OAuth and repository updates.

##### Relationships & Data Flows
- Content Author / Editor uses Browser → visits `/admin` (CMS UI).
- CMS UI → calls `api/auth` → redirects to GitHub OAuth → returns via `api/callback` → issues JWT to CMS UI.
- CMS UI → uses Git Gateway (authenticated) → reads/writes the content repo (pulls markdown, commits changes).
- Git repo push triggers Cloudflare Pages → runs Hugo → updates static assets.
- End User’s Browser requests pages → served by CDN.

##### Architectural Patterns & Design Principles
- Static Site Generation: content is pre-rendered for performance, SEO, and security.
- Jamstack: JavaScript (CMS UI), APIs (serverless functions), Markup (static HTML).
- Git-based content workflow: CMS commits directly to Git.
- Serverless functions decouple auth logic from the static build.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Editor((Content Editor)):::user
    EndUser((End User)):::user

    subgraph "Content Repository (GitHub)" 
        ContentRepo["Content Repository<br/>(Markdown, Theme, Admin UI, Functions)"]:::external
        subgraph StaticAssets
            Robots["robots.txt"] 
            Google["google25a737ee848e6317.html"]
        end
    end

    subgraph "Headless CMS UI (DecapCMS)" 
        CMSUI["DecapCMS Admin UI<br/>(/admin)"]:::static
        Config["config.yml"] 
        Entry["index.html"]
    end

    subgraph "Serverless API (Cloudflare Functions)" 
        Auth["api/auth.js"]:::serverless
        Callback["api/callback.js"]:::serverless
    end

    subgraph "Build & Deploy" 
        Build["Cloudflare Pages<br/>(Hugo Build)"]:::static
        HugoConfig["hugo.toml"]
    end

    subgraph "CDN / Static Hosting" 
        CDN["is-cool.dev<br/>(Static Site)"]:::static
    end

    OAuth["GitHub OAuth"]:::external

    Editor -->|browses /admin| CMSUI
    CMSUI -->|"calls API"| Auth
    Auth -->|redirects| OAuth
    OAuth -->|callback| Callback
    Callback -->|issues JWT| CMSUI
    CMSUI -->|Git Gateway commits| ContentRepo
    ContentRepo -->|push triggers build| Build
    Build -->|deploys assets| CDN
    EndUser -->|loads pages| CDN

    click ContentRepo "https://github.com/ss-vip/blog/tree/main/content/"
    click Robots "https://github.com/ss-vip/blog/blob/main/static/robots.txt"
    click Google "https://github.com/ss-vip/blog/blob/main/static/google25a737ee848e6317.html"
    click CMSUI "https://github.com/ss-vip/blog/tree/main/static/admin/"
    click Config "https://github.com/ss-vip/blog/blob/main/static/admin/config.yml"
    click Entry "https://github.com/ss-vip/blog/blob/main/static/admin/index.html"
    click Auth "https://github.com/ss-vip/blog/blob/main/functions/api/auth.js"
    click Callback "https://github.com/ss-vip/blog/blob/main/functions/api/callback.js"
    click HugoConfig "https://github.com/ss-vip/blog/blob/main/hugo.toml"

    classDef static fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef serverless fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef user fill:#F5F5F5,stroke:#000,stroke-width:1px
```
