How mld10sar/golden-buddy works
What this project is (type + purpose)
From the file tree + README, this is a single-page web application built with React + TypeScript and bundled by Vite. It’s meant to be run locally (npm run dev) and deployed as a static frontend (no server-side code in the repo). The app integrates with Gemini via a GEMINI_API_KEY in .env.local, implying the frontend (or a thin client-side service layer) calls the Gemini API.
Key indicators:
• vite.config.ts, index.html, index.tsx, App.tsx → Vite + React SPA entrypoints
• views/*.tsx → page/view-level components
• services/store.ts → centralized state management (store)
• .github/workflows/deploy.yml → CI/CD pipeline for deployment
• README focuses only on Node + env var + npm run dev → no backend runtime mentioned
• User Browser (React SPA)
• External Gemini API
• Build/Deploy pipeline (GitHub Actions → static hosting target)
Runtime container: “Browser SPA”
• Entrypoints
• index.html → HTML shell
• index.tsx → React bootstrap (mounting root component)
• App.tsx → top-level composition: routing / view switching / global providers
• Views (page-level UI)
• views/Welcome.tsx
• views/NamePicker.tsx
• views/LocationPicker.tsx
• views/InterestPicker.tsx
• views/Dashboard.tsx
• views/Profile.tsx
These typically represent distinct screens or steps in the UX flow. They should be diagrammed as top-level UI modules.
• State + domain glue
• services/store.ts → shared app state (likely user profile, onboarding choices, dashboard data, etc.)
• constants.ts → shared constants/config values
• Config/metadata
• metadata.json → AI Studio related metadata (treat as “app metadata/config artifact”)
External dependency: Gemini
• Not in the repo, but a critical part of the runtime architecture: the app depends on Gemini API calls.
• Even if the exact calling code isn’t shown in the file tree, the presence of GEMINI_API_KEY strongly implies outbound HTTPS calls from the client.
Build & deployment
• package.json, package-lock.json → build tooling + dependencies
• .github/workflows/deploy.yml → CI/CD pipeline (build and deploy)
• tsconfig*.json → TS compilation configuration
• vite.config.ts → bundling/build config
Goal: show the app in relation to users and Gemini.
Nodes to include
• User
• AI Studio App (this project) running in Browser
• Gemini API (External Service)
• User → Browser SPA: “Uses / interacts with UI”
• Browser SPA → Gemini API: “HTTPS requests (prompt / completion / responses)”
• Gemini API → Browser SPA: “AI response payload”
Notes to annotate
• “GEMINI_API_KEY configured via environment at dev/build time”
• If the key is truly shipped to the browser, call out the security implication in a note (even if that’s “as designed” for AI Studio templates)
Goal: break down the SPA into as many components/modules as possible (without inventing things not present).
Bootstrap & Shell
• index.html
• index.tsx (mount root)
• App.tsx (composition, routing, providers)
Views (Screens)
• Welcome
• NamePicker
• LocationPicker
• InterestPicker
• Dashboard
• Profile
• Welcome → NamePicker → LocationPicker → InterestPicker → Dashboard
• Dashboard ↔ Profile (typical pattern)
State Management
• services/store.ts as a central store
• Each View ↔ Store (reads state, dispatches updates)
Shared Types/Constants
• types.ts
• constants.ts
• Store and Views depend on these
External API Integration
• Views/Store → Gemini API Client → Gemini API
Configuration
• .env.local (dev) / env injection (build)
• Env → Gemini API Client (provides API key/config)
Goal: capture the operational architecture (often missed, but critical).
Nodes
• Developer machine: npm install / npm run dev
• GitHub repository
• GitHub Actions workflow: .github/workflows/deploy.yml
• Build step: Vite build output
• Static hosting target (unknown from tree—label generically as “Static Host/CDN” unless deploy.yml reveals it)
• Dev → GitHub: push
• GitHub → GitHub Actions: trigger workflow
• GitHub Actions → Build artifacts: vite build
• Artifacts → Static Host/CDN: deploy
• User Browser → Static Host/CDN: downloads index.html + JS bundle
Relationships and interactions to explicitly show (data flow)
Since this is primarily a UI + store + external API system, make the data flows very explicit:
• User input flows
• Views collect: name, location, interests (based on view file names)
• Those values go into store.ts
• AI request flows
• Store or Dashboard triggers an AI request (logical assumption consistent with needing Gemini API key)
• Request payload uses state (name/location/interests)
• Gemini response updates store
• Dashboard/Profile re-render based on updated store
• “User profile data”
• “Prompt/request”
• “AI response”
• “State update / re-render”
Architectural patterns/design principles evident here
• SPA architecture (single runtime container in the browser)
• View-driven UI modules (views/*)
• Centralized state (services/store.ts) acting as a single source of truth
• Typed domain contracts (types.ts)
• Config via environment (.env.local, Vite env injection)
• CI/CD automation (GitHub Actions)
• [ ] Notes for .env.local / API key handling included