# oumelab/demo-ai-review-analysis-app architecture

> Architecture diagram of the GitHub repository oumelab/demo-ai-review-analysis-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oumelab/demo-ai-review-analysis-app
- Repository: https://github.com/oumelab/demo-ai-review-analysis-app

## Overview

##### Project type and purpose
- This is a front-end only, single-page web application (built with Vite + React + Bun), deployed as a static site on Cloudflare Pages.
- Its purpose is to fetch user reviews from Google Sheets, display them, then call the Gemini AI API to generate summaries.

##### File structure
- Top-level files: index.html, vite.config.ts, package.json, bun.lock → static front-end build.
- /public → static assets (images, favicon, screenshot).
- /src
- main.tsx, App.tsx → React entry point + top-level component
- /components → presentational UI components (review list, AI summary card, star rating, footer) plus a /ui folder for shared design system primitives (badge, button, card, tabs) from shadcn/ui.
- /hooks → data-access and business logic hooks (useReview for Google Sheets + SWR, useAISummaryLogic for Gemini calls).
- /lib → utility functions and wrappers.
- /constants and /types → static data, TypeScript types.
- index.css → Tailwind CSS globals.
- No separate backend; all API calls are made directly from the client.

##### README for additional insights
- Features: fetch+display reviews, AI summarization.
- Built With: Vite, React, Bun, Tailwind CSS, shadcn/ui, SWR, Google Sheets API, Gemini API, Cloudflare Pages.

a. Main components
- Client (Browser)
– React SPA (App.tsx → components/ui + src/components)
– Data-layer hooks (useReview, useAISummaryLogic)
– Utilities (src/lib) + constants/types
- Hosting / CDN
– Cloudflare Pages serving built static assets
- External services
– Google Sheets API (reads spreadsheet rows of reviews)
– Gemini AI API (summarization endpoint)
b. Relationships & data flow
1. Browser loads SPA from Cloudflare Pages
2. React app renders ReviewList; useReview hook issues GET to Google Sheets REST API via SWR
3. Google Sheets returns review data → React renders reviews
4. User clicks “Summarize” → useAISummaryLogic invokes Gemini API with review text
5. Gemini returns summary → React displays SummaryCard
c. Architectural patterns & principles
- Component-based UI (shadcn/ui primitives + custom components)
- Separation of concerns:
– “UI” layer (components)
– “Data” layer (hooks + SWR caching)
– “Utility” layer (/lib)
- Static hosting + direct client-to-API integration (no custom backend)
d. Key technologies to annotate
- Vite build + dev server
- React + TypeScript
- Tailwind CSS / shadcn/ui
- SWR (data fetching & caching)
- Google Sheets REST API
- Gemini AI API
- Cloudflare Pages (CDN/distribution)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Hosting/CDN Layer
  subgraph "Cloudflare Pages (CDN)"
    CF["Cloudflare Pages"]:::hosting
  end

  %% Client Side Application
  subgraph "Browser / React SPA"
    Browser["User's Browser"]:::frontend

    subgraph "SPA Code"
      MP["main.tsx"]:::frontend
      App["App.tsx"]:::frontend

      subgraph "Components"
        RL["Review List Component"]:::frontend
        ASC["AI Summary Card Component"]:::frontend
        RS["Review Summary Component"]:::frontend
        SR["Star Rating Component"]:::frontend
        FTR["Footer Component"]:::frontend

        subgraph "UI Primitives (shadcn/ui)"
          Bdg["Badge"]:::frontend
          Btn["Button"]:::frontend
          Cd["Card"]:::frontend
          Tbs["Tabs"]:::frontend
        end
      end

      subgraph "Hooks"
        UR["useReview Hook"]:::frontend
        UA["useAISummaryLogic Hook"]:::frontend
      end

      subgraph "Utilities & Config"
        LibIdx["lib/index.ts"]:::frontend
        Utils["lib/utils.ts"]:::frontend
        DataC["constants/data.ts"]:::frontend
        Types["types/index.ts"]:::frontend
        CSS["index.css"]:::frontend
        HTML["index.html"]:::frontend
        Vite["vite.config.ts"]:::frontend
        Pkg["package.json"]:::frontend
        Lock["bun.lock"]:::frontend
        Public["public/"]:::frontend
      end
    end
  end

  %% External Services
  GS["Google Sheets API"]:::external
  AIAPI["Gemini AI API"]:::external

  %% Data Flow
  CF -->|"GET index.html & bundles"| Browser
  Browser -->|"executes"| MP
  MP -->|"renders"| App
  App -->|"renders"| RL
  App -->|"renders"| ASC
  RL -->|"uses hook"| UR
  UR -->|"SWR GET reviews"| GS
  ASC -->|"uses hook"| UA
  UA -->|"AI inference call"| AIAPI

  %% Click Events for file mapping
  click MP "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/main.tsx"
  click App "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/App.tsx"
  click RL "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/review-list.tsx"
  click ASC "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/ai-summary-card.tsx"
  click RS "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/review-summary.tsx"
  click SR "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/star-rating.tsx"
  click FTR "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/footer.tsx"
  click Bdg "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/ui/badge.tsx"
  click Btn "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/ui/button.tsx"
  click Cd "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/ui/card.tsx"
  click Tbs "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/components/ui/tabs.tsx"
  click UR "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/hooks/useReview.ts"
  click UA "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/hooks/useAISummaryLogic.ts"
  click LibIdx "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/lib/index.ts"
  click Utils "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/lib/utils.ts"
  click DataC "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/constants/data.ts"
  click Types "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/types/index.ts"
  click CSS "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/src/index.css"
  click HTML "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/index.html"
  click Vite "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/vite.config.ts"
  click Pkg "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/package.json"
  click Lock "https://github.com/oumelab/demo-ai-review-analysis-app/blob/main/bun.lock"
  click Public "https://github.com/oumelab/demo-ai-review-analysis-app/tree/main/public/"

  %% Styling
  classDef frontend fill:#E8F0FE,stroke:#3B82F6,color:#1E40AF;
  classDef hosting fill:#FEF3E8,stroke:#F59E0B,color:#92400E;
  classDef external fill:#E8FEEF,stroke:#10B981,color:#065F46;
```
