# jpasholk/jpshlk-blog architecture

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

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

## Overview

##### Project type and purpose
- This is a static site blog built with Astro (a static-site generator) using MDX content, Tailwind CSS, and client-islands/components.
- The README confirms it’s a personal blog deployed via Netlify, with content in `src/content` and UI in `src/components` and `src/layouts`.

##### File structure for architectural clues
- Top-level files:
- `astro.config.mjs`, `package.json`, `tailwind.config.cjs`, `tsconfig.json` – config for build toolchain.
- `public/` – truly static assets (favicons, audio, JSON).
- Source tree (`src/`):
- `content/` holds Markdown/MDX for authors, blog posts, tags.
- `components/` contains reusable Astro “islands” (UI pieces).
- `layouts/` defines page templates (root, list, post, author).
- `pages/` defines routes (index, blog paging, tag pages, RSS feed generator).
- `styles/global.css` – global Tailwind styles.
- `functions.ts` and `src/env.d.ts` – any build-time helpers or typed environment.
- No traditional backend or database—data comes at build time from local files.

##### README for extra context
- Confirms Astro is the framework.
- Mentions deployment on Netlify (CI/CD pipeline).
- Credits an external JSON of quotes (fetched from `public/quotes.json`).

a. Main components:
1. Content Sources:
– MDX files under `src/content/`
– Static JSON (`public/quotes.json`), images, audio.
2. Build System:
– Astro compiler + Node.js
– Tailwind CSS processor
– TypeScript transpilation
– RSS feed generator (`src/pages/rss.xml.js`)
3. Output Artifacts:
– Static HTML, CSS, JS (in `dist/`)
4. Deployment Pipeline:
– GitHub repo → push triggers Netlify build → static site hosted on CDN
5. Client:
– Browser renders static pages, loads any Astro “islands”/hydrated components, applies theme switcher, dynamic quotes, etc.
b. Interactions/data flow:
– Developer commits to GitHub → Netlify CI picks up commit → runs `npm run build` using Astro/Tailwind → outputs `/dist` → Netlify publishes to CDN → end-user HTTP(S) request → CDN delivers static assets → browser renders.
– During build: Astro reads MDX + JSON → generates HTML pages and feeds → bundles CSS/JS.
c. Architectural patterns/design principles:
– Static-Site Generation (SSG)
– Component-based UI (Astro Islands)
– Content-driven routing (filesystem-based routing)
– CI/CD pipeline for automated deployment
d. Key technologies/frameworks:
– Astro
– Tailwind CSS
– MDX (Markdown + JSX)
– Netlify (CI/CD + CDN)
– TypeScript

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Content Sources"
        direction TB
        MDXPosts["MDX Posts"]:::green
        MDXAuthors["MDX Authors"]:::green
        MDXTags["MDX Tags"]:::green
        JSONQuotes["Static JSON"]:::green
        StaticAssets["Public Static Assets"]:::green
    end

    subgraph "Build System"
        direction TB
        AstroConfig["Astro Config"]:::blue
        TailwindConfig["Tailwind Config"]:::blue
        TSConfig["TypeScript Config"]:::blue
        EnvTypes["Typed Env"]:::blue
        NetlifyFuncs["Build Helpers"]:::blue
        AstroCompiler["Astro Compiler"]:::blue
        TailwindProcess["Tailwind Processor"]:::blue
        TSCompiler["TypeScript Transpilation"]:::blue
        RSSGen["RSS Feed Generator"]:::blue
    end

    subgraph "Page Routing & Layouts"
        direction TB
        RootPage["Root / Home"]:::blue
        BlogList["Blog Listing & Pagination"]:::blue
        BlogPost["Blog Post"]:::blue
        TagsIndex["Tags Listing"]:::blue
        TagPages["Tag Pages"]:::blue
        About["About & Projects"]:::blue
        RootLayout["Root Layout"]:::blue
        ListLayout["List Layout"]:::blue
        ListWithTags["List With Tags Layout"]:::blue
        PostLayout["Post Layout"]:::blue
        AuthorLayout["Author Layout"]:::blue
    end

    subgraph "UI Components"
        direction TB
        Components["Astro Islands / Components"]:::blue
        BaseHead["Site Metadata & Links"]:::blue
        ThemeSwitch["Theme Switcher"]:::blue
        RandomQuote["Random Quote"]:::blue
        PaginationComp["Pagination"]:::blue
        NavComps["Navigation Components"]:::blue
        UtilComps["Utility Components"]:::blue
    end

    subgraph "Deployment Pipeline"
        direction TB
        Dev["Developer"]:::orange
        GitHub["GitHub Repo"]:::orange
        NetlifyCI["Netlify CI/CD"]:::orange
        CDN["Netlify CDN"]:::orange
    end

    subgraph "Output Artifacts"
        direction TB
        Dist["/dist (HTML, CSS, JS)"]:::grey
    end

    subgraph "Client/Browser"
        direction TB
        Browser["Browser"]:::grey
    end

    Dev -->|commits| GitHub
    GitHub -->|trigger build| NetlifyCI
    NetlifyCI -->|runs build| AstroCompiler

    MDXPosts --> AstroCompiler
    MDXAuthors --> AstroCompiler
    MDXTags --> AstroCompiler
    JSONQuotes --> AstroCompiler
    StaticAssets --> Dist

    AstroConfig --> AstroCompiler
    TailwindConfig --> TailwindProcess
    TSConfig --> TSCompiler
    EnvTypes --> AstroCompiler
    NetlifyFuncs --> AstroCompiler
    AstroCompiler --> TailwindProcess
    AstroCompiler --> TSCompiler
    RSSGen --> AstroCompiler

    RootPage --> AstroCompiler
    BlogList --> AstroCompiler
    BlogPost --> AstroCompiler
    TagsIndex --> AstroCompiler
    TagPages --> AstroCompiler
    About --> AstroCompiler
    RootLayout --> AstroCompiler
    ListLayout --> AstroCompiler
    ListWithTags --> AstroCompiler
    PostLayout --> AstroCompiler
    AuthorLayout --> AstroCompiler

    Components --> AstroCompiler
    BaseHead --> AstroCompiler
    ThemeSwitch --> AstroCompiler
    RandomQuote --> AstroCompiler
    PaginationComp --> AstroCompiler
    NavComps --> AstroCompiler
    UtilComps --> AstroCompiler

    TailwindProcess --> Dist
    TSCompiler --> Dist
    AstroCompiler --> Dist

    Dist -->|published| CDN
    Browser -->|requests| CDN
    Browser -->|renders| Dist

    click MDXPosts "https://github.com/jpasholk/jpshlk-blog/tree/main/src/content/blog"
    click MDXAuthors "https://github.com/jpasholk/jpshlk-blog/tree/main/src/content/authors"
    click MDXTags "https://github.com/jpasholk/jpshlk-blog/tree/main/src/content/tags"
    click JSONQuotes "https://github.com/jpasholk/jpshlk-blog/blob/main/public/quotes.json"
    click StaticAssets "https://github.com/jpasholk/jpshlk-blog/tree/main/public/static"
    click AstroConfig "https://github.com/jpasholk/jpshlk-blog/blob/main/astro.config.mjs"
    click TailwindConfig "https://github.com/jpasholk/jpshlk-blog/blob/main/tailwind.config.cjs"
    click TSConfig "https://github.com/jpasholk/jpshlk-blog/blob/main/tsconfig.json"
    click EnvTypes "https://github.com/jpasholk/jpshlk-blog/blob/main/src/env.d.ts"
    click NetlifyFuncs "https://github.com/jpasholk/jpshlk-blog/blob/main/src/functions.ts"
    click RSSGen "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/rss.xml.js"
    click RootPage "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/index.astro"
    click BlogList "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/blog/[...page].astro"
    click BlogPost "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/blog/[...slug].astro"
    click TagsIndex "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/tags/index.astro"
    click TagPages "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/tags/[slug]/[...page].astro"
    click About "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/about.astro"
    click About "https://github.com/jpasholk/jpshlk-blog/blob/main/src/pages/projects.astro"
    click RootLayout "https://github.com/jpasholk/jpshlk-blog/blob/main/src/layouts/RootLayout.astro"
    click ListLayout "https://github.com/jpasholk/jpshlk-blog/blob/main/src/layouts/ListLayout.astro"
    click ListWithTags "https://github.com/jpasholk/jpshlk-blog/blob/main/src/layouts/ListWithTagsLayout.astro"
    click PostLayout "https://github.com/jpasholk/jpshlk-blog/blob/main/src/layouts/PostLayout.astro"
    click AuthorLayout "https://github.com/jpasholk/jpshlk-blog/blob/main/src/layouts/AuthorLayout.astro"
    click Components "https://github.com/jpasholk/jpshlk-blog/tree/main/src/components"
    click BaseHead "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/BaseHead.astro"
    click ThemeSwitch "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/ThemeSwitcher.astro"
    click RandomQuote "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/RandomQuote.astro"
    click PaginationComp "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/Pagination.astro"
    click NavComps "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/Header.astro"
    click NavComps "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/Footer.astro"
    click NavComps "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/MobileNav.astro"
    click UtilComps "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/FormattedDate.astro"
    click UtilComps "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/Logo.astro"
    click UtilComps "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/Link.astro"
    click UtilComps "https://github.com/jpasholk/jpshlk-blog/blob/main/src/components/Tag.astro"
    click UtilComps "https://github.com/jpasholk/jpshlk-blog/tree/main/src/components/social-icons"

    classDef green fill:#bbf7d0,stroke:#166534,color:#065f46
    classDef blue fill:#bfdbfe,stroke:#1e3a8a,color:#1e40af
    classDef orange fill:#fed7aa,stroke:#c2410c,color:#9a3412
    classDef grey fill:#e5e7eb,stroke:#374151,color:#1f2937
```
