# bakate/astro-theme-starter architecture

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

- Interactive diagram: https://gitdiagram.com/bakate/astro-theme-starter
- Repository: https://github.com/bakate/astro-theme-starter

## Overview

##### Project type and purpose
- This is primarily a **static site generator** built with **Astro**, TypeScript, Tailwind CSS, and MDX.
- It produces a personal portfolio and bilingual blog (EN/FR), with a small serverless contact-form endpoint.

##### Main components
a. **Source Code Modules** (developer-facing)
- Astro pages & routes (`src/pages/…`)
- Feature modules (`src/features/blog`, `…/projects`, `…/tips`, `…/contact`)
- Reusable UI components (`src/components`, `src/components/ui`)
- Layouts (`src/layouts`)
- Assets & styles (`src/assets`, `src/styles`, `tailwind.config.mjs`)
- i18n config (`src/i18n`)
- Build/config files (`astro.config.mjs`, `content.config.ts`, `package.json`)
b. **Build Pipeline**
- Astro compiler & renderer
- TypeScript transpiler
- Tailwind CSS → generated CSS
- MDX + remark plugins → HTML + interactive React components
c. **Generated Output**
- Static HTML pages (e.g. `/blog`, `/projects`, `/tips`, `/contact`)
- Static assets (CSS, JS bundles, images, favicons under `/public`)
d. **Hosting & Delivery**
- CDN / Static-site hosting (e.g., Vercel, Netlify, or S3 + CloudFront)
- GitHub repository / CI pipeline (optional)
e. **Runtime Interactivity**
- Client-side scripts: theme toggle, language selector, UI state stores
- Serverless function for contact form: `src/pages/api/contact.ts`
- External email service / form‐processing API

##### Relationships & Data Flow
- **Developers → Source Code**: Push to Git.
- **CI/CD → Build Pipeline**: On push, run `bun install` → `bun astro build`
- **Build Pipeline → Generated Output**: Produces a `/dist` folder containing HTML/CSS/JS/images.
- **Hosting/CDN → End Users**: Serves static assets; caches on edge.
- **Browser → Static Pages**: User navigates to pre-rendered pages.
- **Browser → /api/contact**: Form POST → Serverless function → External email API → Response back to browser.

##### Architectural patterns & design principles
- **Separation of Concerns**:
- Content in `features/*/content` (MDX)
- Presentation in Astro/React components (`components`, `layouts`)
- Styling via Tailwind CSS + shadcn/ui primitives
- **Modular Feature Structure**: Each feature (blog, tips, projects, contact) in its own folder with type definitions, service logic, components, and screens.
- **Static-First / JAMstack**: Pre-render most pages; only minimal serverless for dynamic form.
- **Internationalization**: UI strings centralized in `src/i18n/ui.ts`; content folders split by language.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Developer and Source Code
    Dev["Developer"]:::user
    Git["Git Repository"]:::code
    Dev --> Git

    subgraph "Source Code Modules"
        direction TB
        subgraph "Pages & Features"
            direction TB
            Pages["Astro Pages & Routes"]:::code
            BlogModule["Blog Feature Module"]:::code
            ProjectsModule["Projects Feature Module"]:::code
            TipsModule["Tips Feature Module"]:::code
            ContactModule["Contact Feature Module"]:::code
        end
        subgraph "Components & Layouts"
            direction TB
            UIComponents["Reusable UI Components"]:::code
            UIPrimitives["Shadcn/UI Primitives"]:::code
            Layouts["Layouts"]:::code
        end
        subgraph "Config & Assets"
            direction TB
            ContentConfig["Content Configuration"]:::code
            AstroConfig["Astro Configuration"]:::code
            PackageJSON["Package Definitions & Scripts"]:::code
            TSConfig["TypeScript Configuration"]:::code
            TailwindConfig["Tailwind Configuration"]:::code
            GlobalStyles["Global Styles"]:::code
            StaticAssets["Static Assets & Favicons"]:::code
        end
        subgraph "Internationalization & Utilities"
            direction TB
            i18nConfig["Internationalization Config"]:::code
            ZodMap["Zod Error Map (i18n)"]:::code
            i18nUtils["i18n Utility Functions"]:::code
            RemarkPlugin["MDX Reading Time Plugin"]:::code
            Utils["General Utilities"]:::code
            Store["Client-Side Store"]:::code
            AssetsFolder["Assets Folder"]:::code
            ServerlessAPI["Serverless Contact API"]:::code
        end
    end
    Git --> Source_Code_Modules
    Source_Code_Modules --> CICD

    %% Layer 2: CI/CD and Build Pipeline
    subgraph "CI/CD"
        CICD["CI/CD (bun install & build)"]:::pipeline
    end
    subgraph "Build Pipeline"
        direction TB
        TS["TypeScript Compiler"]:::pipeline
        MDX["MDX & remark plugins"]:::pipeline
        TW["Tailwind Processor"]:::pipeline
        ASTRO["Astro Compiler"]:::pipeline
    end
    CICD --> TS
    TS --> MDX
    MDX --> TW
    TW --> ASTRO

    %% Content Source feeding build
    subgraph "Content Source"
        direction TB
        ContentMDX["Content Source (MDX EN/FR)"]:::code
        BlogModule
        ProjectsModule
        TipsModule
        ContactModule
    end
    ContentMDX --> ASTRO

    %% Layer 3: Static Output and Hosting
    ASTRO --> StaticOutput
    StaticOutput["Static Output (/dist)"]:::output
    StaticOutput --> CDN["CDN / Hosting"]:::cdn

    %% Layer 4: Runtime - Browser and Serverless
    subgraph "Client / Browser"
        Browser["Browser / User"]:::client
        UI["Client-side: theme toggle, language selector, UI stores"]:::client
    end
    CDN ---|“Fetch static HTML/CSS/JS”| Browser
    Browser --> UI

    Browser ---|“POST /api/contact”| Serverless
    Serverless["Serverless Function\nPOST /api/contact"]:::serverless
    Serverless -->|“Send email via API”| Email
    Email["External Email Service"]:::external

    %% Click Events
    click Pages "https://github.com/bakate/astro-theme-starter/tree/main/src/pages"
    click BlogModule "https://github.com/bakate/astro-theme-starter/tree/main/src/features/blog"
    click ProjectsModule "https://github.com/bakate/astro-theme-starter/tree/main/src/features/projects"
    click TipsModule "https://github.com/bakate/astro-theme-starter/tree/main/src/features/tips"
    click ContactModule "https://github.com/bakate/astro-theme-starter/tree/main/src/features/contact"
    click UIComponents "https://github.com/bakate/astro-theme-starter/tree/main/src/components"
    click UIPrimitives "https://github.com/bakate/astro-theme-starter/tree/main/src/components/ui"
    click Layouts "https://github.com/bakate/astro-theme-starter/tree/main/src/layouts"
    click ContentConfig "https://github.com/bakate/astro-theme-starter/blob/main/src/content.config.ts"
    click AstroConfig "https://github.com/bakate/astro-theme-starter/blob/main/astro.config.mjs"
    click PackageJSON "https://github.com/bakate/astro-theme-starter/blob/main/package.json"
    click TSConfig "https://github.com/bakate/astro-theme-starter/blob/main/tsconfig.json"
    click TailwindConfig "https://github.com/bakate/astro-theme-starter/blob/main/tailwind.config.mjs"
    click GlobalStyles "https://github.com/bakate/astro-theme-starter/blob/main/src/styles/global.css"
    click StaticAssets "https://github.com/bakate/astro-theme-starter/tree/main/public/favicons"
    click i18nConfig "https://github.com/bakate/astro-theme-starter/blob/main/src/i18n/ui.ts"
    click ZodMap "https://github.com/bakate/astro-theme-starter/blob/main/src/i18n/zodErrorMap.ts"
    click i18nUtils "https://github.com/bakate/astro-theme-starter/blob/main/src/lib/i18n-utils.ts"
    click RemarkPlugin "https://github.com/bakate/astro-theme-starter/blob/main/src/lib/remark-reading-time.mjs"
    click Utils "https://github.com/bakate/astro-theme-starter/blob/main/src/lib/utils.ts"
    click Store "https://github.com/bakate/astro-theme-starter/blob/main/src/stores/blogFilterStore.ts"
    click AssetsFolder "https://github.com/bakate/astro-theme-starter/tree/main/src/assets"
    click ServerlessAPI "https://github.com/bakate/astro-theme-starter/blob/main/src/pages/api/contact.ts"

    %% Styles
    classDef code fill:#DCEEFB,stroke:#0B5394;
    classDef pipeline fill:#E0E0E0,stroke:#737373;
    classDef output fill:#FFE8B0,stroke:#FFB300;
    classDef cdn fill:#FFD59E,stroke:#E69138;
    classDef client fill:#FFF2CC,stroke:#BF9000;
    classDef serverless fill:#EAD0FA,stroke:#8E7CC3;
    classDef external fill:#D9EAD3,stroke:#6AA84F;
    classDef user fill:#FFF2CC,stroke:#BF9000;
```
