# vacaramin/bidbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/vacaramin/bidbuddy
- Repository: https://github.com/vacaramin/bidbuddy

## Overview

##### Project type and purpose
- This is a frontend-only SaaS single-page application (SPA) built with React (JSX), Vite/Webpack, and deployed to Firebase Hosting. Its purpose is to generate AI-powered Upwork proposals, let users configure templates, track history, and manage settings, all in the browser.

##### File structure
- Top-level config:
- .firebaserc, firebase.json → Firebase Hosting setup
- .github/workflows/*.yml → CI/CD pipelines for build & deploy
- package.json, vite.config.js, webpack.config.js → build tools & dependencies
- Public assets:
- public/, dist/, index.html → static site entry points
- Source code (src/):
- Layout/ (Sidebar, Topbar) → page chrome
- components/ (Card, Logo) → reusable UI blocks
- pages/ (Home, Bid, GenerateProposal, etc.) → route-level views
- hooks/ & utils/ → custom hooks (useLocalStorage) and services (apiService.js for AI calls)
- token.js, localStorage.js → auth token storage & local persistence

##### README for additional insights
- Core features: AI proposal generation, templates, history tracking, user settings.
- No backend code present—data persistence and business logic reside entirely in frontend and third-party APIs.

a. Main components:
- User’s browser running the React SPA
- SPA modules:
– Layout & routing (Topbar, Sidebar, pages)
– Components & hooks (UI, localStorage)
– Services (apiService calling AI provider)
- External AI service (e.g., OpenAI API)
- Local browser storage (localStorage)
- CI/CD pipeline (GitHub Actions)
- Hosting (Firebase Hosting)

b. Relationships & data flow:
1. User interacts with SPA UI → triggers page logic
2. SPA reads/writes to localStorage for settings & history
3. When generating proposals, SPA calls apiService → sends job description + user config to External AI API → receives generated text
4. SPA displays proposal and saves it to localStorage
5. On commit/merge, GitHub Actions runs build (Vite/Webpack), then deploys dist/ to Firebase Hosting

c. Architectural patterns & principles:
- Single-page application (client-side routing)
- Separation of concerns: Layout vs. Components vs. Pages
- Custom hooks & utility modules to isolate side-effects (e.g., localStorage, API calls)
- CI/CD for automated build and deploy

d. Key technologies:
- React (JSX, hooks)
- Vite & Webpack for dev/build
- Firebase Hosting for static site deployment
- GitHub Actions for CI/CD
- LocalStorage for persistence
- External AI service (via REST)

##### Essential details to capture
- Global token.js utility as part of apiService’s auth workflow
- Build step (Vite/Webpack) before deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User Browser"]:::user

    %% React SPA
    subgraph "React SPA"
        direction TB
        Entry["src/main.jsx"]:::frontend
        Styles["src/index.scss"]:::frontend
        subgraph "Layout"
            direction TB
            Sidebar["Sidebar.jsx"]:::frontend
            Topbar["Topbar.jsx"]:::frontend
        end
        subgraph "Components"
            direction TB
            Card["Card.jsx"]:::frontend
            Logo["Logo.jsx"]:::frontend
        end
        subgraph "Pages"
            direction TB
            Home["Home.jsx"]:::frontend
            Bid["Bid.jsx"]:::frontend
            Generate["GenerateProposal.jsx"]:::frontend
            History["History.jsx"]:::frontend
            ImportExport["ImportExport.jsx"]:::frontend
            Onboarding["OnboardingWizard.jsx"]:::frontend
            Settings["Settings.jsx"]:::frontend
        end
        subgraph "Hooks & Utils"
            direction TB
            UseLS["useLocalStorage.js"]:::backend
            APIService["apiService.js"]:::backend
            LocalStorageUtil["localStorage.js"]:::backend
            Token["token.js"]:::backend
        end
        Dist["dist/index.html"]:::frontend
    end

    %% Data Store
    LocalStorageCylinder["LocalStorage"]:::db

    %% External Services
    AI["External AI Service"]:::cloud

    %% CI/CD & Hosting
    subgraph "CI/CD Pipeline"
        direction TB
        GHActions["GitHub Actions"]:::ci
        Build["Vite/Webpack Build"]:::ci
        Firebase["Firebase Hosting"]:::cloud
    end

    %% Relationships
    User -->|interacts| Entry
    Entry --> Styles
    Entry --> Sidebar
    Entry --> Topbar
    Entry --> Card
    Entry --> Logo
    Entry --> Home
    Entry --> Bid
    Entry --> Generate
    Entry --> History
    Entry --> ImportExport
    Entry --> Onboarding
    Entry --> Settings
    Entry --> UseLS
    Entry --> APIService
    Entry --> Dist

    APIService -->|POST /generateProposal| AI
    AI -->|response| APIService

    UseLS --> LocalStorageCylinder
    LocalStorageUtil --> LocalStorageCylinder
    History --> LocalStorageCylinder
    Settings --> LocalStorageCylinder
    ImportExport --> LocalStorageCylinder
    Onboarding --> LocalStorageCylinder

    GHActions --> Build
    Build --> Firebase

    %% Click Events
    click Entry "https://github.com/vacaramin/bidbuddy/blob/main/src/main.jsx"
    click Styles "https://github.com/vacaramin/bidbuddy/blob/main/src/index.scss"
    click Sidebar "https://github.com/vacaramin/bidbuddy/blob/main/src/Layout/Sidebar.jsx"
    click Topbar "https://github.com/vacaramin/bidbuddy/blob/main/src/Layout/Topbar.jsx"
    click Card "https://github.com/vacaramin/bidbuddy/blob/main/src/components/Card.jsx"
    click Logo "https://github.com/vacaramin/bidbuddy/blob/main/src/components/Logo.jsx"
    click Home "https://github.com/vacaramin/bidbuddy/blob/main/src/pages/Home.jsx"
    click Bid "https://github.com/vacaramin/bidbuddy/blob/main/src/pages/Bid.jsx"
    click Generate "https://github.com/vacaramin/bidbuddy/blob/main/src/pages/GenerateProposal.jsx"
    click History "https://github.com/vacaramin/bidbuddy/blob/main/src/pages/History.jsx"
    click ImportExport "https://github.com/vacaramin/bidbuddy/blob/main/src/pages/ImportExport.jsx"
    click Onboarding "https://github.com/vacaramin/bidbuddy/blob/main/src/pages/OnboardingWizard.jsx"
    click Settings "https://github.com/vacaramin/bidbuddy/blob/main/src/pages/Settings.jsx"
    click UseLS "https://github.com/vacaramin/bidbuddy/blob/main/src/hooks/useLocalStorage.js"
    click APIService "https://github.com/vacaramin/bidbuddy/blob/main/src/utils/apiService.js"
    click LocalStorageUtil "https://github.com/vacaramin/bidbuddy/blob/main/src/utils/localStorage.js"
    click Token "https://github.com/vacaramin/bidbuddy/blob/main/src/token.js"
    click Dist "https://github.com/vacaramin/bidbuddy/blob/main/dist/index.html"
    click Public "https://github.com/vacaramin/bidbuddy/tree/main/public/"
    click Firebase "https://github.com/vacaramin/bidbuddy/blob/main/firebase.json"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#2980B9,color:#154360
    classDef backend fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef db fill:#F4F6F6,stroke:#7F8C8D,color:#2C3E50
    classDef cloud fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef ci fill:#FADBD8,stroke:#E74C3C,color:#641E16
    classDef user fill:#FDEDEC,stroke:#C0392B,color:#641E16
```
