# satnaing/astro-paper architecture

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

- Interactive diagram: https://gitdiagram.com/satnaing/astro-paper
- Repository: https://github.com/satnaing/astro-paper

## Overview

##### Project type and purpose
- **Type**: Static site generator / frontend‐only blog theme
- **Purpose**: Provide a minimal, responsive, SEO‐friendly blog framework (Astro + TypeScript + TailwindCSS), generate dynamic OG images at build time, support search (FuseJS/Pagefind), and deliver via CDN/Cloudflare Pages.

##### File structure
- **src/**:
- `pages/`: Astro & MD pages → routes
- `layouts/` & `components/`: UI building blocks (Header, Footer, PostDetails, etc.)
- `data/blog/`: Markdown blog content, drafts, release notes
- `utils/`: helper scripts (OG image generation, slugify, search index)
- `config.ts`, `constants.ts`, `content.config.ts`: global config
- **Root config**: `astro.config.ts`, `package.json`, `docker-compose.yml`, GitHub Actions workflow (`.github/workflows/ci.yml`).

##### Readme insights
- **Tech stack**: Astro, TypeScript, TailwindCSS, FuseJS (static search), Pagefind, ESLint, Prettier
- **Build & deploy**:
- Local dev: `pnpm run dev` or Docker (`docker-compose up`)
- CI: GitHub Actions runs lint, build, sync
- Production: Deploy to Cloudflare Pages or any static‐hosting CDN

##### Main components & interactions
a. **Developer workstation**
- Writes code & content → pushes to GitHub
- Runs local dev server (pnpm/Docker)
b. **Source Code Repository (GitHub)**
- Hosts code, content, CI workflows
c. **CI/CD Pipeline (GitHub Actions)**
- On push: installs dependencies → lint/format checks → builds static site → runs tests (if any) → emits production `dist/`
d. **Containerization (Docker/Docker Compose)**
- Optional dev/prod containers for consistent environment
e. **Static Site Generator (Astro Engine)**
- Reads `src/pages`, `data/blog`, `assets`
- Applies layouts & components
- Generates HTML/CSS/JS + dynamic OG images via `generateOgImages.ts`
- Emits search index files under `public/pagefind`
f. **Deployment & Hosting**
- Deploy build output (`dist/`) to Cloudflare Pages (or any CDN)
- CDN caches assets globally, serves static files
g. **End User (Browser)**
- Requests pages → receives pre‐rendered HTML, CSS, JS
- Client‐side behavior: theme toggle, fuzzy search, navigation

##### Architectural patterns & design principles
- **Static Site Generation (SSG)**: all pages are prebuilt
- **Componentized UI**: Astro components + Tailwind utility classes
- **Separation of concerns**:
- Content (Markdown) vs. Layout/Presentation
- Build scripts (utils) vs. Runtime code (toggle- theme.js)
- **Infrastructure as code**: Dockerfile + docker-compose + GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Developer["Developer Workstation"]:::external
    GitHub["GitHub Repository"]:::external
    EndUser["End User (Browser)"]:::external

    %% CI/CD & Container
    subgraph "CI/CD & Container" 
        CI["GitHub Actions CI/CD"]:::ci
        Docker["Docker / Docker Compose"]:::ci
    end

    %% Build-Time Components
    subgraph "Build-Time (Astro SSG)" 
        Astro["Astro Engine"]:::build
        StaticAssets["Static Assets"]:::build
        Pages["Pages / Routes"]:::build
        Layouts["Layout Components"]:::build
        Components["UI Components"]:::build
        BlogContent["Blog Content (Markdown)"]:::build
        Configs["Global & Astro Config"]:::build
        Utils["Build Utilities & OG Generator"]:::build
        SearchIndex["Search Index Generation"]:::build
        Dist["dist/ (Static Output)"]:::runtime
    end

    %% Hosting & Runtime
    subgraph "Hosting & CDN" 
        CDN["CDN / Cloudflare Pages"]:::runtime
    end

    %% Flows
    Developer -->|"push code / content"| GitHub
    GitHub -->|"trigger workflow"| CI
    CI -->|"lint / format / test"| CI
    CI -->|"build pipeline"| Astro
    CI -->|"optional dev container"| Docker
    Developer -->|"local dev (pnpm / Docker)"| Docker
    Docker -->|"runs Astro dev server"| Astro

    Astro -->|"reads"| StaticAssets
    Astro -->|"reads"| Pages
    Astro -->|"reads"| Layouts
    Astro -->|"reads"| Components
    Astro -->|"reads"| BlogContent
    Astro -->|"reads"| Configs
    Astro -->|"executes"| Utils
    Astro -->|"generates"| SearchIndex
    Astro -->|"emits"| Dist

    Dist -->|"deploy"| CDN
    EndUser -->|"fetch pages"| CDN

    %% Click Events
    click StaticAssets "https://github.com/satnaing/astro-paper/tree/main/public/"
    click StaticAssets "https://github.com/satnaing/astro-paper/tree/main/public/assets/"
    click StaticAssets "https://github.com/satnaing/astro-paper/blob/main/public/toggle-theme.js"
    click Pages "https://github.com/satnaing/astro-paper/tree/main/src/pages/"
    click Layouts "https://github.com/satnaing/astro-paper/tree/main/src/layouts/"
    click Components "https://github.com/satnaing/astro-paper/tree/main/src/components/"
    click BlogContent "https://github.com/satnaing/astro-paper/tree/main/src/data/blog/"
    click Configs "https://github.com/satnaing/astro-paper/blob/main/src/config.ts"
    click Configs "https://github.com/satnaing/astro-paper/blob/main/src/constants.ts"
    click Configs "https://github.com/satnaing/astro-paper/blob/main/src/content.config.ts"
    click Configs "https://github.com/satnaing/astro-paper/blob/main/astro.config.ts"
    click Utils "https://github.com/satnaing/astro-paper/tree/main/src/utils/"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/generateOgImages.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/slugify.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/postFilter.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/getSortedPosts.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/getUniqueTags.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/getPostsByTag.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/getPostsByGroupCondition.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/getPath.ts"
    click Utils "https://github.com/satnaing/astro-paper/blob/main/src/utils/loadGoogleFont.ts"
    click Utils "https://github.com/satnaing/astro-paper/tree/main/src/utils/og-templates/"
    click Utils "https://github.com/satnaing/astro-paper/tree/main/src/utils/transformers/"
    click CI "https://github.com/satnaing/astro-paper/blob/main/.github/workflows/ci.yml"
    click Docker "https://github.com/satnaing/astro-paper/blob/main/docker-compose.yml"
    click Docker "https://github.com/satnaing/astro-paper/tree/main/Dockerfile"

    %% Styles
    classDef build fill:#d0e1f9,stroke:#0366d6,color:#000
    classDef runtime fill:#d8f5e9,stroke:#28a745,color:#000
    classDef ci fill:#ffe5b4,stroke:#d2691e,color:#000
    classDef external fill:#f0f0f0,stroke:#666,color:#000
```
