# davidvkimball/astro-modular architecture

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

- Interactive diagram: https://gitdiagram.com/davidvkimball/astro-modular
- Repository: https://github.com/davidvkimball/astro-modular

## Overview

##### Project type and purpose
- This is a Jamstack-style static site (blog theme) built with Astro, using Obsidian as a headless CMS via Vault CMS.
- Purpose: provide a highly customizable, performance-focused Astro theme for Obsidian users, with built-in SSG and some serverless JSON APIs for search, feeds, etc.

##### File structure
- Top-level:
- package.json / pnpm-lock.json / tsconfig.json / astro.config.mjs / tailwind.config.mjs / vite.config.mjs – ecosystem & build configs
- netlify.toml / wrangler.toml – deployment configs for Netlify & Cloudflare Workers
- scripts/ – custom Node scripts for setup, alias processing, graph data generation, image sync, deployment config
- public/ – static assets (images, docs, generated graph-data.json)
- src/ – all Astro source code:
– components/ (UI atoms & molecules)
– layouts/ (page templates)
– pages/ (Astro routes + API endpoints under pages/api/*.ts)
– content.config.ts + content/ (Obsidian vault markdown & attachments)
– config.ts (site settings & feature toggles)
– utils/ & scripts/ (helper functions & client bundles)

##### README for additional insights
- Built on Obsidian Astro Suite; uses Vault CMS plugin to map obsidian vault (.md files & attachments) into collections
- Generates sitemap, RSS, Open Graph images
- Supports multiple deployment targets (Netlify, Vercel, Cloudflare) via dynamic build script

##### Main components & interactions
a. Content Store
- “Obsidian Vault” folder (src/content) with markdown posts, docs, pages, projects, attachments, plugins, themes
b. Build Pipeline (Jamstack SSG)
- Node.js + PNPM → runs custom scripts (sync-images, generate-graph-data, process-aliases, generate-deployment-config)
- Astro / Vite / TailwindCSS compile components, layouts, style, generate static HTML/CSS/JS
- content.config.ts & Vault CMS plugin ingest markdown & frontmatter
- pages/api/*.ts compile into serverless JSON endpoints (search index, docs.json, pages.json, etc.)
c. Deployment Targets
- Static assets → CDN (hosted via Netlify / Vercel / Cloudflare Pages)
- Serverless functions → Netlify Functions / Vercel Serverless / Cloudflare Workers (wrangler.toml)
d. Client-side features
- React-style Astro client components (CommandPalette, SearchResults, GraphModal) fetch JSON APIs
- Graph view loads public/graph/graph-data.json
- GiscusComments widget calls external GitHub API

##### Architectural patterns & design principles
- Jamstack / Static Site Generation + serverless micro-APIs
- Component-driven UI (Astro + Islands architecture)
- Feature toggles & modular settings via config.ts
- Precomputed data artifacts (graph-data.json, JSON feeds) for performance

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Content Layer
    subgraph "Content Layer"
        Vault["Content Store (Obsidian Vault)"]:::content
        ContentSchema["Content Schema (content.config.ts)"]:::config
        SiteConfig["Site Config & Feature Toggles (config.ts)"]:::config
    end
    click Vault "https://github.com/davidvkimball/astro-modular/tree/master/src/content"
    click ContentSchema "https://github.com/davidvkimball/astro-modular/blob/master/src/content.config.ts"
    click SiteConfig "https://github.com/davidvkimball/astro-modular/blob/master/src/config.ts"

    %% Build Layer
    subgraph "Build Layer"
        subgraph "Custom Node Scripts"
            checkImg["check-missing-images.js"]:::scripts
            devPort["dev-with-port.js"]:::scripts
            genDeploy["generate-deployment-config.js"]:::scripts
            genGraph["generate-graph-data.js"]:::scripts
            getPlat["get-deployment-platform.js"]:::scripts
            getVer["get-version.js"]:::scripts
            procAlias["process-aliases.js"]:::scripts
            setupDev["setup-dev.mjs"]:::scripts
            syncImg["sync-images.js"]:::scripts
        end
        subgraph "Tooling & Config"
            AstroConfig["astro.config.mjs"]:::config
            Tailwind["tailwind.config.mjs"]:::config
            Vite["vite.config.mjs"]:::config
            TSConfig["tsconfig.json"]:::config
            Pkg["package.json"]:::config
            Lock["pnpm-lock.yaml"]:::config
        end
        subgraph "Content Ingestion"
            CMSPlugin["Vault CMS Plugin"]:::code
            ContentIngest["Astro Content Config"]:::code
        end
        subgraph "Static Site Generation"
            AstroBuild["Astro / Vite / Tailwind"]:::code
            Components["UI Components (Astro Islands)"]:::ui
            Layouts["Layouts (Page Templates)"]:::ui
            Routes["Pages & Routes"]:::ui
        end
        subgraph "API Generation"
            APIEndpoints["Serverless JSON Endpoints"]:::api
        end
    end

    click checkImg "https://github.com/davidvkimball/astro-modular/blob/master/scripts/check-missing-images.js"
    click devPort "https://github.com/davidvkimball/astro-modular/blob/master/scripts/dev-with-port.js"
    click genDeploy "https://github.com/davidvkimball/astro-modular/blob/master/scripts/generate-deployment-config.js"
    click genGraph "https://github.com/davidvkimball/astro-modular/blob/master/scripts/generate-graph-data.js"
    click getPlat "https://github.com/davidvkimball/astro-modular/blob/master/scripts/get-deployment-platform.js"
    click getVer "https://github.com/davidvkimball/astro-modular/blob/master/scripts/get-version.js"
    click procAlias "https://github.com/davidvkimball/astro-modular/blob/master/scripts/process-aliases.js"
    click setupDev "https://github.com/davidvkimball/astro-modular/blob/master/scripts/setup-dev.mjs"
    click syncImg "https://github.com/davidvkimball/astro-modular/blob/master/scripts/sync-images.js"
    click AstroConfig "https://github.com/davidvkimball/astro-modular/blob/master/astro.config.mjs"
    click Tailwind "https://github.com/davidvkimball/astro-modular/blob/master/tailwind.config.mjs"
    click Vite "https://github.com/davidvkimball/astro-modular/blob/master/vite.config.mjs"
    click TSConfig "https://github.com/davidvkimball/astro-modular/blob/master/tsconfig.json"
    click Pkg "https://github.com/davidvkimball/astro-modular/blob/master/package.json"
    click Lock "https://github.com/davidvkimball/astro-modular/blob/master/pnpm-lock.yaml"
    click ContentIngest "https://github.com/davidvkimball/astro-modular/blob/master/src/content.config.ts"
    click Components "https://github.com/davidvkimball/astro-modular/blob/master/src/components/CommandPalette.astro"
    click Components "https://github.com/davidvkimball/astro-modular/blob/master/src/components/SearchResults.astro"
    click Components "https://github.com/davidvkimball/astro-modular/blob/master/src/components/GraphModal.astro"
    click Layouts "https://github.com/davidvkimball/astro-modular/blob/master/src/layouts/BaseLayout.astro"
    click Routes "https://github.com/davidvkimball/astro-modular/blob/master/src/pages/index.astro"
    click APIEndpoints "https://github.com/davidvkimball/astro-modular/blob/master/src/pages/api/docs.json.ts"

    %% Hosting Layer
    subgraph "Hosting Layer"
        CDN["CDN (Netlify / Vercel / Cloudflare Pages)"]:::host
        Functions["Serverless Functions"]:::host
        DeployPresets["Deploy Presets"]:::host
    end
    click Functions "https://github.com/davidvkimball/astro-modular/blob/master/netlify.toml"
    click Functions "https://github.com/davidvkimball/astro-modular/blob/master/wrangler.toml"
    click DeployPresets "https://github.com/davidvkimball/astro-modular/blob/master/.config/astro/config.json"

    %% Client Runtime
    subgraph "Client Runtime"
        Islands["Astro Client Islands"]:::client
        GraphData["Graph Data JSON"]:::data
        CategoryJS["Category Filtering Bundle"]:::client
        Giscus["Giscus Comments Widget"]:::external
    end
    click GraphData "https://github.com/davidvkimball/astro-modular/blob/master/public/graph/graph-data.json"
    click CategoryJS "https://github.com/davidvkimball/astro-modular/blob/master/public/scripts/category-filtering.js"

    %% Data Flows
    Vault -->|"Markdown & Attachments"| CMSPlugin
    CMSPlugin --> ContentIngest
    ContentIngest --> AstroBuild
    checkImg & devPort & genDeploy & genGraph & getPlat & getVer & procAlias & setupDev & syncImg --> AstroBuild
    AstroConfig & Tailwind & Vite & TSConfig & Pkg & Lock --> AstroBuild
    AstroBuild -->|"Static HTML/CSS/JS"| CDN
    AstroBuild -->|"JSON APIs"| APIEndpoints
    CDN -->|"Served & Cached"| Islands
    Functions -->|"Hosts JSON Endpoints"| APIEndpoints
    Islands -->|"Fetch JSON"| APIEndpoints
    Islands -->|"Load Graph Data"| GraphData
    Islands -->|"Load Category Bundle"| CategoryJS
    Islands -->|"Embed Comments"| Giscus

    %% Styles
    classDef content fill:#e6ffed,stroke:#0a662a,stroke-width:2px
    classDef config fill:#fff4e6,stroke:#cc7000,stroke-width:2px
    classDef scripts fill:#fff4e6,stroke:#cc7000,stroke-width:2px
    classDef code fill:#e6f2ff,stroke:#1c4587,stroke-width:2px
    classDef ui fill:#dceeff,stroke:#1c4587,stroke-width:2px
    classDef api fill:#e8eaff,stroke:#5c2e91,stroke-width:2px
    classDef host fill:#f3e8ff,stroke:#6e1e8e,stroke-width:2px
    classDef client fill:#e0f7fa,stroke:#006064,stroke-width:2px
    classDef data fill:#e0f7fa,stroke:#006064,stroke-width:2px
    classDef external fill:#f0f0f0,stroke:#888888,stroke-width:2px,module
```
