# queue-ri/til architecture

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

- Interactive diagram: https://gitdiagram.com/queue-ri/til
- Repository: https://github.com/queue-ri/til

## Overview

##### Project Type and Purpose
- This is a JAMstack-style static documentation site (“Today I Learned”) built with Docusaurus (React/Node.js SSG).
- Purpose: Collate and render markdown/MDX notes (docs/, md/, dev-note/) into a static website deployed via CI/CD pipelines to Cloudflare Pages (and Netlify preview).
- No custom backend or database—content is rendered at build time; runtime is purely client-side.

##### File Structure & Architectural Insights
- Top-Level
- docusaurus.config.js, sidebars.js, package.json → site configuration, theming, plugins (Algolia, MDX Crypto).
- docs/, md/, dev-note/ → three content sources (primary docs, dated journals, developer notes).
- src/ → React components and theme overrides (components/, pages/, theme/CodeBlock, theme/DocItem, theme/DocSidebar).
- static/ → static assets (images, manifest).
- prism-custom/ → custom syntax-highlight themes.
- .github/workflows/ → CI/CD definitions (build, preview, update).
- algolia-config.json → search indexing setup.

##### Key Components
a. Developer Environment
– Local machine: git, Node.js, npm/yarn, Docusaurus CLI
b. Source Repository & CI/CD
– GitHub repo → triggers GitHub Actions workflows (node-js.yml for build/test, pr-deploy-preview.yml for pre-release previews, update-md-and-index.yml for search indexing).
c. Static Site Generator
– Docusaurus (React + MDX + Babel + SCSS) processes content and theme customizations into static HTML/CSS/JS.
– MDX Crypto Plugin: encrypts/decrypts sections of MDX at build time.
d. Hosting & Delivery
– Cloudflare Pages (primary host) with CDN layer. Netlify badge indicates preview usage.
– static assets and JS served from CDN edge.
e. External Services
– Algolia (DocSearch) for client-side full-text search.
– (Optional) any analytics or third-party scripts integrated via Docusaurus config.

##### Relationships & Data Flows
- Code Commit → GitHub → GitHub Actions
- Actions build site (Docusaurus SSG) → artifact (static bundle) → deploy to Cloudflare Pages → CDN propagation
- End-User HTTP(S) Request → CDN Edge → static site (HTML/CSS/JS) → client-side React hydration
- In-browser search UI → Algolia API queries → search results back to user

##### Architectural Patterns & Principles
- JAMstack: Pre-render all pages at build time, serve via CDN, client-side enhancements only where needed.
- Component-Based UI: src/components + theme overrides following React best practices.
- Plugin/Extension Points: MDX plugins, custom CodeBlock buttons, search bar component, theming layers.
- CI/CD as Code: .github/workflows define build/test/deploy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    Dev["Developer Workstation\n(git, Node.js, npm/yarn,\nDocusaurus CLI)"]:::blue

    %% Source Repository & CI/CD
    Dev -->|"git push"| GH["GitHub Repo"]:::blue

    subgraph "Source Repository & CI/CD"
        subgraph "Repository"
            Config["Site Config\n(docusaurus.config.js)"]:::blue
            Sidebars["Sidebar Config\n(sidebars.js,\nsidebars-custom.js)"]:::blue
            Babel["Babel Config\n(babel.config.js)"]:::blue
            Package["package.json,\npackage-lock.json"]:::blue
            AlgoliaCfg["algolia-config.json"]:::blue
            Gitignore[".gitignore"]:::blue
            License["LICENSE"]:::blue
            Readme["README.md"]:::blue
        end
        subgraph "Content Sources"
            Docs["docs/"]:::green
            MD["md/"]:::green
            DevNote["dev-note/"]:::green
        end
        GH -->|"trigger workflows"| Actions["GitHub Actions\n(node-js.yml,\npr-deploy-preview.yml,\nupdate-md-and-index.yml)"]:::blue
    end

    %% Build Process
    Actions -->|"build & test"| SSG["Docusaurus SSG"]:::green

    subgraph "SSG Build"
        SSG
        subgraph "Plugins & Themes"
            MDXCrypto["MDX Crypto Plugin"]:::yellow
            PrismThemes1["one-dark-pro-flat"]:::yellow
            PrismThemes2["one-light"]:::yellow
        end
        subgraph "UI Layer"
            Components["src/components/"]:::gray
            MDXCryptoComp["src/components/mdx-crypto/"]:::gray
            SearchBar["src/components/mdx-searchbar/"]:::gray
            MDXUtil["src/components/mdx-util/"]:::gray
            Hook["src/components/useOnScreen.js"]:::gray
            Pages["src/pages/"]:::gray
            Styles["src/css/custom.scss"]:::gray
            CodeBlock["src/theme/CodeBlock/"]:::gray
            DocItem["src/theme/DocItem/"]:::gray
            DocSidebar["src/theme/DocSidebar/"]:::gray
        end
    end

    %% Deployment & Hosting
    Actions -->|"deploy"| CF["Cloudflare Pages"]:::orange

    subgraph "Hosting & CDN"
        CF
        CDN["CDN Edge"]:::orange
    end

    %% End-User Flow
    Browser["User Browser"]:::gray
    Browser -->|"HTTP(S) Request"| CDN
    CDN -->|"serve static bundle"| Browser
    Browser -->|"search query"| Algolia["Algolia DocSearch"]:::yellow
    Algolia -->|"results"| Browser

    %% Click Events
    click Config "https://github.com/queue-ri/til/blob/main/docusaurus.config.js"
    click Sidebars "https://github.com/queue-ri/til/blob/main/sidebars.js"
    click Sidebars "https://github.com/queue-ri/til/blob/main/sidebars-custom.js"
    click Babel "https://github.com/queue-ri/til/blob/main/babel.config.js"
    click Package "https://github.com/queue-ri/til/blob/main/package.json"
    click Package "https://github.com/queue-ri/til/blob/main/package-lock.json"
    click AlgoliaCfg "https://github.com/queue-ri/til/blob/main/algolia-config.json"
    click Docs "https://github.com/queue-ri/til/tree/main/docs/"
    click MD "https://github.com/queue-ri/til/tree/main/md/"
    click DevNote "https://github.com/queue-ri/til/tree/main/dev-note/"
    click Components "https://github.com/queue-ri/til/tree/main/src/components/"
    click MDXCryptoComp "https://github.com/queue-ri/til/tree/main/src/components/mdx-crypto/"
    click SearchBar "https://github.com/queue-ri/til/tree/main/src/components/mdx-searchbar/"
    click MDXUtil "https://github.com/queue-ri/til/tree/main/src/components/mdx-util/"
    click Hook "https://github.com/queue-ri/til/blob/main/src/components/useOnScreen.js"
    click Pages "https://github.com/queue-ri/til/tree/main/src/pages/"
    click Styles "https://github.com/queue-ri/til/blob/main/src/css/custom.scss"
    click CodeBlock "https://github.com/queue-ri/til/tree/main/src/theme/CodeBlock/"
    click DocItem "https://github.com/queue-ri/til/tree/main/src/theme/DocItem/"
    click DocSidebar "https://github.com/queue-ri/til/tree/main/src/theme/DocSidebar/"
    click PrismThemes1 "https://github.com/queue-ri/til/tree/main/prism-custom/one-dark-pro-flat/"
    click PrismThemes2 "https://github.com/queue-ri/til/tree/main/prism-custom/one-light/"
    click Actions "https://github.com/queue-ri/til/blob/main/.github/workflows/node-js.yml"
    click Actions "https://github.com/queue-ri/til/blob/main/.github/workflows/pr-deploy-preview.yml"
    click Actions "https://github.com/queue-ri/til/blob/main/.github/workflows/update-md-and-index.yml"
    click CF "https://github.com/queue-ri/til/tree/main/static/"

    %% Styles
    classDef blue fill:#D0E7FF,stroke:#0366d6,stroke-width:1px;
    classDef green fill:#DFFFE0,stroke:#28a745,stroke-width:1px;
    classDef orange fill:#FFE5B4,stroke:#FF8C00,stroke-width:1px;
    classDef yellow fill:#FFF4C1,stroke:#DAA520,stroke-width:1px;
    classDef gray fill:#F2F2F2,stroke:#6c757d,stroke-width:1px;
```
