# bliss-e-v/webpage architecture

> Architecture diagram of the GitHub repository bliss-e-v/webpage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bliss-e-v/webpage
- Repository: https://github.com/bliss-e-v/webpage

## Overview

##### Project type and purpose
- This is a static, content-driven website built with the Astro framework.
- It uses component-based .astro and .tsx files to assemble pages, with Markdown frontmatter driving the blog.
- Styling is handled by Tailwind (via @astrojs/tailwind + PostCSS), and there’s a 3D effect via Three.js and three-noise.
- Output is a set of purely static files deployed to Vercel (vercel.json).

##### Main components
a. Developer Environment
- Code repos (GitHub)
- Local dev server (astro dev)
- Scripts (generate_final_newsletter.cjs, postcss-replace-attribute-selectors.cjs)
b. Source Code
- src/pages → route definitions (.astro pages + Markdown posts)
- src/layouts → Layout.astro (site-wide) & Newsletter.astro (email layout)
- src/components → UI primitives, 3D scenes, data modules (members, media, events)
- src/utils → helpers (getSortedPosts, types)
- src/global.css & tailwind.config.cjs → global styles
- astro.config.mjs → build configuration
c. Public Assets
- public/ → all static assets (images, fonts, site.webmanifest, _headers)
- subdivided into authors/, images/, posts/, assets/
d. Build Pipeline
- Astro compiler → parses .astro/.tsx, injects components, resolves frontmatter → HTML
- Tailwind JIT → transforms classes → CSS
- PostCSS plugin → attribute-selector rewrite
- Output → /dist (static site)
e. Deployment & Hosting
- Vercel pulls from GitHub → runs build → serves /dist behind CDN

##### Relationships & data flows
- Developer commits code → GitHub
- Vercel CI/CD → runs astro build (uses astro.config.mjs + tailwind.config.cjs + postcss.config.js)
- Astro build:
- Reads src/pages & Markdown → generates HTML via Layout & components
- Styles via Tailwind + PostCSS → bundled CSS
- Copies public/ → dist/
- Browser requests pages from Vercel CDN → static HTML/CSS/JS served
- Interactive bits (Three.js) loaded at runtime from components

##### Architectural patterns & principles
- Component-based SSG (Static Site Generation)
- Separation of concerns:
- Presentation (components & layouts)
- Content (Markdown frontmatter + data modules)
- Styling (Tailwind + PostCSS)
- Scripts/automation (newsletter generator)
- Utility-first CSS (Tailwind) & minimal JS

##### Technologies & integrations
- Astro (framework)
- Node.js scripts (newsletter, PostCSS plugin)
- TailwindCSS + @astrojs/tailwind
- PostCSS + custom attribute-selector replacer
- Three.js + three-noise for 3D backgrounds
- TypeScript / TSX for type safety
- Vercel hosting

##### Final advice
- Be exhaustive but clear: break the system into “Developer → CI/CD → Build → Output → Runtime.”
- Every folder that feeds into the build (src/pages, src/components, public/)
- Third-party integrations (Tailwind, Three.js, Vercel)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        GH["GitHub Repo"]:::code
        DevServer["Local Dev Server\n(astro dev)"]:::code
        Scripts["Developer Scripts"]:::code
        GN["generate_final_newsletter.cjs"]:::code
        PR["postcss-replace-attribute-selectors.cjs"]:::code
    end

    %% CI/CD
    subgraph "CI/CD"
        direction TB
        VCI["Vercel CI/CD"]:::build
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        AstroBuild["Astro Compiler"]:::build
        TailwindJIT["Tailwind JIT"]:::build
        PostCSS["PostCSS Plugin"]:::build
    end

    %% Source Code
    subgraph "Source Code" 
        direction TB
        Pages["src/pages/"]:::code
        Layouts["src/layouts"]:::code
        Components["src/components"]:::code
        Data["src/components/data/"]:::code
        NewsletterComp["src/components/newsletter/"]:::code
        Hackathon["src/components/hackathon/"]:::code
        Utils["src/utils"]:::code
        Env["src/env.d.ts"]:::code
        GlobalCSS["src/global.css"]:::code
        AstroConfig["astro.config.mjs"]:::code
        TailwindConfig["tailwind.config.cjs"]:::code
        PostCSSConfig["postcss.config.js"]:::code
        RemarkRT["remark-reading-time.mjs"]:::code
    end

    %% Public Assets
    subgraph "Public Assets"
        direction TB
        PublicRoot["public/"]:::output
        Headers["_headers"]:::output
        Manifest["site.webmanifest"]:::output
        Assets["assets/"]:::output
        Authors["authors/"]:::output
        Images["images/"]:::output
    end

    %% Output & Hosting
    subgraph "Output & Hosting"
        direction TB
        Dist["/dist"]:::output
        CDN["Vercel CDN"]:::output
    end

    %% Runtime
    subgraph "Runtime"
        direction TB
        Browser["Browser"]:::runtime
    end

    %% Project Config & Repo
    subgraph "Project Config"
        direction TB
        PKG["package.json"]:::code
        TSConfig["tsconfig.json"]:::code
        VercelJSON["vercel.json"]:::code
        GitIgnore[".gitignore"]:::code
        VSCode[".vscode/"]:::code
        README["README.md"]:::code
    end

    %% Connections
    GH -->|push code| VCI
    DevServer -->|runs| AstroBuild
    Scripts --> GN
    Scripts --> PR
    VCI -->|runs build| AstroBuild
    AstroBuild --> Pages
    AstroBuild --> Layouts
    AstroBuild --> Components
    AstroBuild --> Utils
    AstroBuild --> AstroConfig
    AstroBuild --> TailwindConfig
    AstroBuild --> PostCSSConfig
    AstroBuild --> RemarkRT
    AstroBuild --> GlobalCSS
    AstroBuild --> PublicRoot
    TailwindJIT --> GlobalCSS
    PostCSS --> PostCSSConfig
    AstroBuild -->|generates| Dist
    PublicRoot -->|copied| Dist
    Dist --> CDN
    CDN --> Browser
    Browser -->|loads interactive components| Components

    %% Click Events
    click GN "https://github.com/bliss-e-v/webpage/blob/main/generate_final_newsletter.cjs"
    click PR "https://github.com/bliss-e-v/webpage/blob/main/postcss-replace-attribute-selectors.cjs"
    click AstroConfig "https://github.com/bliss-e-v/webpage/blob/main/astro.config.mjs"
    click TailwindConfig "https://github.com/bliss-e-v/webpage/blob/main/tailwind.config.cjs"
    click PostCSSConfig "https://github.com/bliss-e-v/webpage/blob/main/postcss.config.js"
    click RemarkRT "https://github.com/bliss-e-v/webpage/blob/main/remark-reading-time.mjs"
    click VercelJSON "https://github.com/bliss-e-v/webpage/blob/main/vercel.json"
    click PKG "https://github.com/bliss-e-v/webpage/blob/main/package.json"
    click Pages "https://github.com/bliss-e-v/webpage/tree/main/src/pages/"
    click Layouts "https://github.com/bliss-e-v/webpage/blob/main/src/layouts/Layout.astro"
    click Layouts "https://github.com/bliss-e-v/webpage/blob/main/src/layouts/Newsletter.astro"
    click Components "https://github.com/bliss-e-v/webpage/tree/main/src/components/"
    click Data "https://github.com/bliss-e-v/webpage/tree/main/src/components/data/"
    click NewsletterComp "https://github.com/bliss-e-v/webpage/tree/main/src/components/newsletter/"
    click Hackathon "https://github.com/bliss-e-v/webpage/tree/main/src/components/hackathon/"
    click Utils "https://github.com/bliss-e-v/webpage/blob/main/src/utils/getSortedPosts.ts"
    click Utils "https://github.com/bliss-e-v/webpage/blob/main/src/utils/types.ts"
    click Env "https://github.com/bliss-e-v/webpage/blob/main/src/env.d.ts"
    click GlobalCSS "https://github.com/bliss-e-v/webpage/blob/main/src/global.css"
    click TSConfig "https://github.com/bliss-e-v/webpage/blob/main/tsconfig.json"
    click VSCode "https://github.com/bliss-e-v/webpage/tree/main/.vscode/"
    click GitIgnore "https://github.com/bliss-e-v/webpage/blob/main/.gitignore"
    click README "https://github.com/bliss-e-v/webpage/blob/main/README.md"
    click Headers "https://github.com/bliss-e-v/webpage/tree/main/public/_headers"
    click Manifest "https://github.com/bliss-e-v/webpage/blob/main/public/site.webmanifest"
    click Assets "https://github.com/bliss-e-v/webpage/tree/main/public/assets/"
    click Authors "https://github.com/bliss-e-v/webpage/tree/main/public/authors/"
    click Images "https://github.com/bliss-e-v/webpage/tree/main/public/images/"

    %% Styles
    classDef code fill:#cce5ff,stroke:#005799,color:#000
    classDef build fill:#ffe5cc,stroke:#994d00,color:#000
    classDef output fill:#d6f5d6,stroke:#267326,color:#000
    classDef runtime fill:#e6e6e6,stroke:#666666,color:#000
```
