# teja-pola/gocart architecture

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

- Interactive diagram: https://gitdiagram.com/teja-pola/gocart
- Repository: https://github.com/teja-pola/gocart

## Overview

##### Project Type and Purpose
- goCart is a full-stack, embeddable AI shopping assistant—essentially a universal widget that any e-commerce site can drop in.
- It combines a React/Tailwind frontend, serverless functions (Netlify & Supabase Edge Functions), a PostgreSQL backend (Supabase), and integrations with external AI and data services (SerpAPI, Groq, ElevenLabs).

##### File Structure
- Top-level:
- src/              → Frontend React (Vite) code
- netlify/functions/ & src/server/ → Netlify serverless (Node/TypeScript)
- supabase/functions/ → Supabase Edge Functions (Deno/TypeScript)
- supabase/migrations/ & supabase/config.toml → Database schema and config
- .kiro/            → Internal docs and quality-gate hooks
- Public assets, config files (tsconfig, tailwind.config, netlify.toml)
- Patterns:
- Frontend vs. backend separation
- Serverless microservices
- Database migrations/versioning
- Zustand for client state management
- Proxy layer for SerpAPI (security and key-hiding)

##### Extract Architecture Insights from the README
- Frontend: TypeScript + React + Tailwind, delivered via Vite, deployed on Netlify CDN.
- Backend:
- Netlify Function at /.netlify/functions/serpapi-proxy for real-time Walmart data
- Supabase Edge Functions for cart agent logic & speech-to-text
- Supabase Auth and PostgreSQL DB for persistence
- AI Services:
- Groq API (Llama) for conversational AI
- ElevenLabs for voice synthesis
- SerpAPI for fetching product catalogs

##### Main Components & Their Interactions
a. Frontend Widget
- React component library (src/components)
- Zustand store (src/store) for cart/session state
- Styles with Tailwind
b. API Layer
- Netlify Function (serpapi-proxy)
- Supabase Edge Functions (cartify-agent, speech-to-text)
- Supabase Auth (JWT flows)
c. AI & External Services
- Groq API (user prompts → LLM)
- ElevenLabs (text → voice response)
- SerpAPI (product search)
d. Database & Persistence
- PostgreSQL via Supabase
- Migrations define tables, RLS policies
- Storage (if any media)
e. Hosting & CI
- Netlify (frontend + functions)
- Supabase (DB + Edge functions)
- .kiro hooks enforce linting, tests, security audits

##### Architectural Patterns & Design Principles
- Micro-frontends: single React widget that can be embedded anywhere
- Serverless microservices: each function has a single responsibility
- Event-driven state transitions (cart updates, API responses)
- Zero-trust API design: proxy functions prevent client-side secret leaks
- RLS (Row-Level Security) in Supabase for multi-tenant safety

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlane: Client/Site
    subgraph "Client / Site" 
        direction TB
        Browser["Browser"]:::client
        ReactUI["React UI"]:::frontend
        Zustand["Zustand Store"]:::frontend
        TailwindCSS["Tailwind Styles"]:::frontend
        Vite["Vite Build"]:::frontend
        NetlifyCDN["Netlify CDN"]:::hosting
    end

    %% Swimlane: goCart Cloud Services
    subgraph "goCart Cloud Services"
        direction TB
        subgraph "Netlify Functions"
            SerpProxyNL["Netlify SerpAPI Proxy"]:::backend
        end
        subgraph "Alternate Proxy"
            SerpProxySRV["Server Folder SerpAPI Proxy"]:::backend
        end
        subgraph "Supabase Edge Functions"
            CartifyAgent["Cartify Agent"]:::backend
            SpeechToText["Speech-to-Text"]:::backend
        end
        subgraph "Supabase Core"
            SupabaseClient["Supabase Client Lib"]:::backend
            SupabaseAuthDB["Auth & PostgreSQL DB"]:::database
            SupabaseConfig["supabase/config.toml"]:::config
            Migrations["supabase/migrations"]:::config
        end
    end

    %% Swimlane: External AI & Data Providers
    subgraph "External AI & Data Providers"
        direction TB
        SerpAPI["SerpAPI"]:::external
        Groq["Groq API"]:::external
        ElevenLabs["ElevenLabs"]:::external
    end

    %% Connections
    Browser -->|"loads widget"| ReactUI
    ReactUI -->|"uses store"| Zustand
    ReactUI -->|"calls proxy"| SerpProxyNL
    ReactUI -->|"calls proxy"| SerpProxySRV
    SerpProxyNL -->|"fetchProducts()"| SerpAPI
    SerpProxySRV -->|"fetchProducts()"| SerpAPI
    ReactUI -->|"POST /cart"| CartifyAgent
    CartifyAgent -->|"chatCompletion()"| Groq
    CartifyAgent -->|"respondAudio()"| ElevenLabs
    ReactUI -->|"auth & data"| SupabaseClient
    SupabaseClient -->|"JWT auth & queries"| SupabaseAuthDB
    SupabaseAuthDB -->|"schema & policies"| Migrations

    ReactUI -->|"styles config"| TailwindCSS
    ReactUI -->|"build config"| Vite
    Vite --> NetlifyCDN
    CartifyAgent --> SupabaseAuthDB
    SpeechToText -->|"speechToText()"| SupabaseAuthDB

    %% Click Events
    click ReactUI "https://github.com/teja-pola/gocart/blob/main/src/main.tsx"
    click ReactUI "https://github.com/teja-pola/gocart/blob/main/src/App.tsx"
    click ReactUI "https://github.com/teja-pola/gocart/tree/main/src/components/"
    click ReactUI "https://github.com/teja-pola/gocart/blob/main/src/index.css"
    click Zustand "https://github.com/teja-pola/gocart/blob/main/src/store/useStore.ts"
    click SerpProxyNL "https://github.com/teja-pola/gocart/blob/main/netlify/functions/serpapi-proxy.ts"
    click SerpProxyNL "https://github.com/teja-pola/gocart/blob/main/netlify/functions/tsconfig.json"
    click SerpProxySRV "https://github.com/teja-pola/gocart/blob/main/src/server/serpapi-proxy.ts"
    click CartifyAgent "https://github.com/teja-pola/gocart/blob/main/supabase/functions/cartify-agent/index.ts"
    click SpeechToText "https://github.com/teja-pola/gocart/blob/main/supabase/functions/speech-to-text/index.ts"
    click SpeechToText "https://github.com/teja-pola/gocart/blob/main/supabase/functions/speech-to-text/deno.json"
    click SpeechToText "https://github.com/teja-pola/gocart/blob/main/supabase/functions/speech-to-text/.npmrc"
    click SupabaseConfig "https://github.com/teja-pola/gocart/blob/main/supabase/config.toml"
    click Migrations "https://github.com/teja-pola/gocart/blob/main/supabase/migrations/*.sql"
    click SupabaseClient "https://github.com/teja-pola/gocart/blob/main/src/lib/supabase.ts"
    click TailwindCSS "https://github.com/teja-pola/gocart/blob/main/tailwind.config.js"
    click Vite "https://github.com/teja-pola/gocart/blob/main/vite.config.ts"
    click NetlifyCDN "https://github.com/teja-pola/gocart/blob/main/netlify.toml"
    click .kiro "https://github.com/teja-pola/gocart/tree/main/.kiro/"
    click .kiro/hooks "https://github.com/teja-pola/gocart/tree/main/.kiro/hooks/"
    click .kiro/specs "https://github.com/teja-pola/gocart/tree/main/.kiro/specs/ai-shopping-assistant/"
    click .kiro/steering "https://github.com/teja-pola/gocart/tree/main/.kiro/steering/"

    %% Styles
    classDef client fill:#D0E6A5,stroke:#6B8E23
    classDef frontend fill:#A1C4FD,stroke:#1E90FF
    classDef backend fill:#FBC2EB,stroke:#FF1493
    classDef database fill:#FEE140,stroke:#FFD700
    classDef external fill:#FFDAC1,stroke:#FF8C00
    classDef hosting fill:#C3B1E1,stroke:#8A2BE2
    classDef config fill:#E2F0CB,stroke:#228B22
```
