How eramajarvi/project-overflow works
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)