# mld10sar/golden-buddy architecture

> Architecture diagram of the GitHub repository mld10sar/golden-buddy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mld10sar/golden-buddy
- Repository: https://github.com/mld10sar/golden-buddy

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1 — System Context
%% =========================
subgraph "Diagram 1: System Context (Runtime)"
  direction TB

  User["User (Browser)"]:::external

  subgraph "AI Studio App (React + TypeScript SPA)"
    direction TB
    SPA["Browser SPA (Static Frontend)"]:::frontend
    EnvNote[/"GEMINI_API_KEY via env injection\n(dev/build-time config)"/]:::config
  end

  Gemini["Gemini API (External Service)"]:::externalService

  User -->|"Uses_UI"| SPA
  SPA -->|"HTTPS_requests(Prompt/Completion)"| Gemini
  Gemini -->|"AI_response(JSON)"| SPA
  EnvNote -.->|"Provides_API_key/config"| SPA
end

%% ==========================================
%% Diagram 2 — Container/Component (Inside SPA)
%% ==========================================
subgraph "Diagram 2: Browser SPA Components (C4-Component)"
  direction TB

  subgraph "Bootstrap & Shell"
    direction TB
    HTML["HTML Shell (index.html)"]:::doc
    Boot["React Bootstrap (index.tsx)"]:::frontend
    App["App Shell (App.tsx)"]:::frontend
    Meta[/"App Metadata (metadata.json)"/]:::config
  end

  subgraph "Views (Screens)"
    direction TB
    Welcome["Welcome View"]:::frontend
    NamePicker["Name Picker View"]:::frontend
    LocationPicker["Location Picker View"]:::frontend
    InterestPicker["Interest Picker View"]:::frontend
    Dashboard["Dashboard View"]:::frontend
    Profile["Profile View"]:::frontend
  end

  subgraph "State + Shared Domain"
    direction TB
    Store["Central Store (services/store.ts)"]:::store
    Types["Shared Types (types.ts)"]:::shared
    Const["Shared Constants (constants.ts)"]:::shared
  end

  subgraph "External Integration (Client-side)"
    direction TB
    Env[/"Environment Config (.env.local)"/]:::config
    GeminiClient["Gemini API Client (fetch wrapper)"]:::api
    Gemini2["Gemini API (External)"]:::externalService
  end

  %% Bootstrapping
  HTML -->|"Loads_bundle"| Boot
  Boot -->|"Mounts_root_component"| App
  Meta -.->|"Provides_app_metadata"| App

  %% Navigation / UI flow
  App -->|"Renders_screen"| Welcome
  Welcome -->|"Next(screen_flow)"| NamePicker
  NamePicker -->|"Next(screen_flow)"| LocationPicker
  LocationPicker -->|"Next(screen_flow)"| InterestPicker
  InterestPicker -->|"Next(screen_flow)"| Dashboard
  Dashboard <-->|"Navigate(view_switch)"| Profile

  %% User input -> state
  Welcome <-->|"Reads/Writes_state"| Store
  NamePicker <-->|"User_profile_data(name)"| Store
  LocationPicker <-->|"User_profile_data(location)"| Store
  InterestPicker <-->|"User_profile_data(interests)"| Store
  Dashboard <-->|"Reads_dashboard_state"| Store
  Profile <-->|"Reads/Edits_profile_state"| Store

  %% Shared contracts
  Store -->|"Uses_types"| Types
  Store -->|"Uses_constants"| Const
  Welcome -->|"Uses_types/constants"| Types
  Welcome -->|"Uses_types/constants"| Const
  NamePicker -->|"Uses_types/constants"| Types
  NamePicker -->|"Uses_types/constants"| Const
  LocationPicker -->|"Uses_types/constants"| Types
  LocationPicker -->|"Uses_types/constants"| Const
  InterestPicker -->|"Uses_types/constants"| Types
  InterestPicker -->|"Uses_types/constants"| Const
  Dashboard -->|"Uses_types/constants"| Types
  Dashboard -->|"Uses_types/constants"| Const
  Profile -->|"Uses_types/constants"| Types
  Profile -->|"Uses_types/constants"| Const

  %% AI request/response flow
  Store -->|"Builds_prompt_from_state"| GeminiClient
  Dashboard -->|"Triggers_AI_request"| GeminiClient
  GeminiClient -->|"Calls_Gemini_API(HTTPS)"| Gemini2
  Gemini2 -->|"Returns_AI_response(JSON)"| GeminiClient
  GeminiClient -->|"Updates_store_with_AI_results"| Store

  %% Config injection
  Env -.->|"Provides_API_key"| GeminiClient
end

%% ==================================
%% Diagram 3 — Build & Deploy Pipeline
%% ==================================
subgraph "Diagram 3: Build & Deploy (CI/CD + Static Hosting)"
  direction TB

  Dev["Developer Machine"]:::external
  Repo["GitHub Repository"]:::infra
  Actions["GitHub Actions (deploy workflow)"]:::infra
  Build["Build Step (Vite build output)"]:::infra
  Host["Static Host / CDN (Deploy Target)"]:::infra
  Browser["User Browser (Downloads SPA)"]:::external

  subgraph "Build Tooling & Config"
    direction TB
    Pkg["package.json (scripts/deps)"]:::infraDoc
    Lock["package-lock.json"]:::infraDoc
    ViteCfg["vite.config.ts"]:::infraDoc
    TS["tsconfig.json"]:::infraDoc
    TSNode["tsconfig.node.json"]:::infraDoc
  end

  Dev -->|"Commit/Push"| Repo
  Repo -->|"Triggers_workflow_on_push"| Actions

  Actions -->|"Install_deps(npm_ci)"| Pkg
  Actions -->|"Uses_lockfile"| Lock
  Actions -->|"Uses_build_config"| ViteCfg
  Actions -->|"Uses_TS_config"| TS
  Actions -->|"Uses_tooling_TS_config"| TSNode

  Actions -->|"Runs_vite_build"| Build
  Build -->|"Deploys_static_assets"| Host

  Browser -->|"HTTP_GET(index.html+bundle)"| Host
  Host -->|"Serves_static_assets"| Browser
end

%% ==================
%% Click events (paths)
%% ==================
click HTML "https://github.com/mld10sar/golden-buddy/blob/main/index.html"
click Boot "https://github.com/mld10sar/golden-buddy/blob/main/index.tsx"
click App "https://github.com/mld10sar/golden-buddy/blob/main/App.tsx"
click Welcome "https://github.com/mld10sar/golden-buddy/blob/main/views/Welcome.tsx"
click NamePicker "https://github.com/mld10sar/golden-buddy/blob/main/views/NamePicker.tsx"
click LocationPicker "https://github.com/mld10sar/golden-buddy/blob/main/views/LocationPicker.tsx"
click InterestPicker "https://github.com/mld10sar/golden-buddy/blob/main/views/InterestPicker.tsx"
click Dashboard "https://github.com/mld10sar/golden-buddy/blob/main/views/Dashboard.tsx"
click Profile "https://github.com/mld10sar/golden-buddy/blob/main/views/Profile.tsx"
click Store "https://github.com/mld10sar/golden-buddy/blob/main/services/store.ts"
click Types "https://github.com/mld10sar/golden-buddy/blob/main/types.ts"
click Const "https://github.com/mld10sar/golden-buddy/blob/main/constants.ts"
click Env "https://github.com/mld10sar/golden-buddy/blob/main/.env.local"
click Meta "https://github.com/mld10sar/golden-buddy/blob/main/metadata.json"
click Pkg "https://github.com/mld10sar/golden-buddy/blob/main/package.json"
click Lock "https://github.com/mld10sar/golden-buddy/blob/main/package-lock.json"
click ViteCfg "https://github.com/mld10sar/golden-buddy/blob/main/vite.config.ts"
click TS "https://github.com/mld10sar/golden-buddy/blob/main/tsconfig.json"
click TSNode "https://github.com/mld10sar/golden-buddy/blob/main/tsconfig.node.json"
click Actions "https://github.com/mld10sar/golden-buddy/blob/main/.github/workflows/deploy.yml"

%% =============
%% Styles/Legend
%% =============
classDef frontend fill:#1e88e5,stroke:#0d47a1,stroke-width:1.5px,color:#ffffff;
classDef store fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#ffffff;
classDef shared fill:#42a5f5,stroke:#0d47a1,stroke-width:1px,color:#ffffff;
classDef api fill:#1976d2,stroke:#0d47a1,stroke-width:1.5px,color:#ffffff;

classDef external fill:#e0e0e0,stroke:#616161,stroke-width:1px,color:#212121;
classDef externalService fill:#fb8c00,stroke:#e65100,stroke-width:2px,color:#1b1b1b;

classDef infra fill:#bdbdbd,stroke:#424242,stroke-width:1.5px,color:#1b1b1b;
classDef infraDoc fill:#cfcfcf,stroke:#424242,stroke-width:1px,color:#1b1b1b;

classDef doc fill:#ffffff,stroke:#1565c0,stroke-width:1.5px,color:#0d47a1;
classDef config fill:#fff3e0,stroke:#ef6c00,stroke-width:1.5px,color:#5d4037;
```
