# eramajarvi/project-overflow architecture

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

- Interactive diagram: https://gitdiagram.com/eramajarvi/project-overflow
- Repository: https://github.com/eramajarvi/project-overflow

## Overview

##### Project Type and Purpose
- This is a small full‑stack web application built with Astro (a static‑site generator) and React for client interactivity.
- It delivers an interactive “retro‑futuristic” UI with p5.js sketches and integrates with Google AI Studio via serverless API routes.

##### File Structure
- Top‑level config and build files: astro.config.mjs, tailwind.config.mjs, tsconfig.json, eslint.config.js, package.json
- public/: static assets (fonts, images, audio) served directly by Astro
- src/pages/:
- index.astro and other static pages (desktop.tsx, tooSmall.tsx) for routing & initial HTML
- src/pages/api/: serverless functions (chat.ts, completion.ts) that sit on Vercel or any Node host
- src/layouts/: Astro layouts (e.g., LoginLayout.astro) wrap pages
- src/components/: React components for UI “windows” (ChatPromptWindow.tsx, SettingsWindow.tsx, etc.) and Shader/Sketch wrappers
- src/components/sketches/: raw p5.js sketches + TypeScript wrappers that the UI mounts
- src/store.js: client‑side state management (small global store for dialogs, user session, current sketch)
- src/helpers/: utility modules (badPhrases, shader code, shaderImporter, etc.)
- src/styles/: global CSS

##### Readme Insights
- React only for window components and client‑side behavior (hydration happens after Astro SSR)
- AI calls are made in the browser via the Vercel AI SDK, proxied through two serverless endpoints to keep the API Key safe
- Jamstack taxonomical best practices: static HTML + hydration + API routes + minimal bundle (<2 MB)

##### Relationships and Data Flow
1. User opens the site → HTTP GET to Astro server → returns static HTML + CSS + JS
2. Browser hydrates React windows + loads p5.js
3. User interacts (e.g., submits chat prompt) → React dispatches action → calls `/api/chat` endpoint
4. Serverless function invokes Vercel AI SDK → forwards request to Google AI Studio API → receives AI response
5. Function responds with JSON to the browser → React updates UI, state, and may trigger a new p5.js sketch
6. Sketch assets are pure JS modules in src/components/sketches (no extra network fetches beyond the initial bundle)

##### Architectural Patterns & Principles
- Jamstack (static + dynamic via API routes)
- Separation of concerns:
- Presentation (Astro + React)
- Graphics engine (p5.js sketches)
- Business logic & AI calls (serverless functions)
- Static assets (public/)
- Micro‑frontend style: each window/sketch is its own component wrapper

##### Capturing Essential Details
- Explicitly show where the API Key is injected (serverless env)—helps security auditing
- Mention asset hosting for fonts/audio/images as its own service (Astro’s public folder)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser (Client)" 
        classDef client fill:#D0E8FF,stroke:#0066CC,color:#003366
        SSR["Astro SSG & SSR"]:::client
        Hydro["React Hydration"]:::client

        subgraph "Astro Pages"
            Index["src/pages/index.astro"]:::client
            Desktop["src/pages/desktop.tsx"]:::client
            TooSmall["src/pages/tooSmall.tsx"]:::client
        end

        subgraph "Layouts"
            LoginLayout["src/layouts/LoginLayout.astro"]:::client
        end

        subgraph "React UI Windows"
            ChatPromptWindow["src/components/ChatPromptWindow.tsx"]:::client
            SettingsWindow["src/components/SettingsWindow.tsx"]:::client
            HelpInstructionsWindow["src/components/HelpInstructionsWindow.tsx"]:::client
            HelpmeWindow["src/components/HelpmeWindow.tsx"]:::client
            LoginWindow["src/components/LoginWindow.tsx"]:::client
            WarningWindow["src/components/WarningWindow.tsx"]:::client
            WelcomePromptWindow["src/components/WelcomePromptWindow.tsx"]:::client
            CreditsWindow["src/components/CreditsWindow.tsx"]:::client
            DefaultWindow["src/components/DefaultWindow.tsx"]:::client
        end

        Store["src/store.js"]:::client

        subgraph "p5.js Sketch Engine"
            Sketches["src/components/sketches/*.jsx & *Wrapper.tsx"]:::client
        end
    end

    %% Serverless Layer
    subgraph "Serverless API" 
        classDef serverless fill:#DBF5D8,stroke:#0A8A0A,color:#065C06
        ChatAPI["/api/chat.ts"]:::serverless
        CompletionAPI["/api/completion.ts"]:::serverless
        SDK["Vercel AI SDK\n(env: GOOGLE_GENERATIVE_AI_API_KEY)"]:::serverless
    end

    %% External Service
    External["Google AI Studio API"]:::external
    classDef external fill:#FFE5B4,stroke:#FF8C00,color:#A65E00

    %% Assets Host
    static["public/assets/, public/fonts/, src/assets/"]:::assets
    classDef assets fill:#F3E5FF,stroke:#8A2BE2,color:#4B0082

    %% Data Flows
    SSR --> Index
    SSR --> Desktop
    SSR --> TooSmall
    Index --> Hydro
    Desktop --> Hydro
    TooSmall --> Hydro

    Hydro --> ChatPromptWindow
    Hydro --> SettingsWindow
    Hydro --> HelpInstructionsWindow
    Hydro --> HelpmeWindow
    Hydro --> LoginWindow
    Hydro --> WarningWindow
    Hydro --> WelcomePromptWindow
    Hydro --> CreditsWindow
    Hydro --> DefaultWindow
    Hydro --> Sketches
    Hydro --> Store

    ChatPromptWindow -->|POST /api/chat with prompt| ChatAPI
    SettingsWindow -->|may call| CompletionAPI
    Store --> ChatAPI
    Store --> CompletionAPI

    ChatAPI -->|calls SDK| SDK
    CompletionAPI -->|calls SDK| SDK
    SDK -->|HTTPS request| External
    External -->|AI JSON response| SDK
    SDK --> ChatAPI
    SDK --> CompletionAPI

    %% Static Assets
    SSR -->|"serves static assets"| static
    Hydro -->|"loads fonts/images/audio"| static

    %% Click Events
    click Index "https://github.com/eramajarvi/project-overflow/blob/master/src/pages/index.astro"
    click Desktop "https://github.com/eramajarvi/project-overflow/blob/master/src/pages/desktop.tsx"
    click TooSmall "https://github.com/eramajarvi/project-overflow/blob/master/src/pages/tooSmall.tsx"
    click LoginLayout "https://github.com/eramajarvi/project-overflow/blob/master/src/layouts/LoginLayout.astro"
    click ChatPromptWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/ChatPromptWindow.tsx"
    click SettingsWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/SettingsWindow.tsx"
    click HelpInstructionsWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/HelpInstructionsWindow.tsx"
    click HelpmeWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/HelpmeWindow.tsx"
    click LoginWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/LoginWindow.tsx"
    click WarningWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/WarningWindow.tsx"
    click WelcomePromptWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/WelcomePromptWindow.tsx"
    click CreditsWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/CreditsWindow.tsx"
    click DefaultWindow "https://github.com/eramajarvi/project-overflow/blob/master/src/components/DefaultWindow.tsx"
    click Store "https://github.com/eramajarvi/project-overflow/blob/master/src/store.js"
    click Sketches "https://github.com/eramajarvi/project-overflow/tree/master/src/components/sketches/"
    click ChatAPI "https://github.com/eramajarvi/project-overflow/blob/master/src/pages/api/chat.ts"
    click CompletionAPI "https://github.com/eramajarvi/project-overflow/blob/master/src/pages/api/completion.ts"
    click static "https://github.com/eramajarvi/project-overflow/tree/master/public/assets/"
    click static "https://github.com/eramajarvi/project-overflow/tree/master/public/fonts/"
    click static "https://github.com/eramajarvi/project-overflow/tree/master/src/assets/"
```
