# jashikaraja05-pixel/buygen architecture

> Architecture diagram of the GitHub repository jashikaraja05-pixel/buygen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jashikaraja05-pixel/buygen
- Repository: https://github.com/jashikaraja05-pixel/buygen

## Overview

BUYGEN is a full-stack consumer-electronics marketplace. Customers discover products, manage a cart, check out through simulated payment, and track orders; administrators manage catalog, categories, offers, orders, payments, users, and metrics. The React app routes these experiences through a shared API client to an Express API, backed by a database layer and Firestore. The README documents AI advising, comparison, smart search, and guarded administration. Some subsystem links are documented rather than verified in sampled implementation excerpts.

Main entry points: [`src/services/api.ts`](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/services/api.ts) (API Client), [`src/App.tsx`](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/App.tsx) (App Router), [`src/server/api.ts`](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/server/api.ts) (Express API), [`src/context/AuthContext.tsx`](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/context/AuthContext.tsx) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Customer Storefront"]
  node_app["App Router<br/>[App.tsx]"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_authgate["Sign-in &amp; Registration"]
  node_home["Home &amp; Catalog<br/>[HomePage.tsx]"]
  node_products["Product Discovery<br/>[ProductsPage.tsx]"]
  node_productdetail["Product Details"]
end

subgraph group_shopping["Shopping &amp; Orders"]
  node_cartstate["Cart State<br/>[CartContext.tsx]"]
  node_wishlist["Wishlist"]
  node_compare["Product Comparison<br/>[ComparePage.tsx]"]
  node_checkout["Checkout &amp; Payment<br/>[CheckoutPage.tsx]"]
  node_orders["Order History<br/>[OrdersPage.tsx]"]
  node_tracking["Order Tracking"]
end

subgraph group_admin["Admin Console"]
  node_adminlayout["Admin Guard &amp; Layout<br/>[AdminLayout.tsx]"]
  node_admindashboard["Admin Metrics<br/>[AdminDashboard.tsx]"]
  node_admincatalog["Catalog Management"]
  node_admincategories["Category Management"]
  node_adminorders["Order Management"]
  node_adminusers["User Management<br/>[AdminUsersPage.tsx]"]
  node_offers["Offers &amp; Payments"]
end

subgraph group_backend["API &amp; Persistence"]
  node_clientapi["API Client<br/>[api.ts]"]
  node_express["Express API<br/>[api.ts]"]
  node_db[("Database Store<br/>[db.ts]")]
  node_firestore[("Firestore")]
end

subgraph group_discovery["AI &amp; Discovery"]
  node_advisor["Tech Advisor<br/>[AdvisorPage.tsx]"]
  node_search["Smart Search"]
  node_compareai["AI Comparison<br/>[ComparePage.tsx]"]
  node_normalizer["Spelling Normalizer"]
  node_advisorservice["Gemini Advisor"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_app
node_app -->|"provides auth"| node_auth
node_app -->|"routes unauthenticated"| node_authgate
node_app -->|"routes storefront"| node_home
node_app -->|"routes catalog"| node_products
node_app -->|"routes details"| node_productdetail
node_app -->|"routes checkout"| node_checkout
node_app -->|"routes orders"| node_orders
node_app -->|"routes admin"| node_adminlayout
node_auth -->|"calls auth API"| node_clientapi
node_home -->|"loads storefront data"| node_clientapi
node_products -.->|"searches catalog"| node_clientapi
node_productdetail -->|"adds products"| node_cartstate
node_cartstate -->|"calls cart API"| node_clientapi
node_wishlist -->|"calls wishlist API"| node_clientapi
node_wishlist -->|"moves to cart"| node_cartstate
node_checkout -->|"creates order"| node_clientapi
node_orders -->|"loads orders"| node_clientapi
node_tracking -.->|"reads live updates"| node_firestore
node_adminlayout -->|"checks role"| node_auth
node_admindashboard -->|"loads metrics"| node_clientapi
node_admincatalog -->|"manages products"| node_clientapi
node_admincategories -->|"manages categories"| node_clientapi
node_adminorders -->|"manages orders"| node_clientapi
node_adminusers -->|"manages users"| node_clientapi
node_offers -->|"manages offers"| node_clientapi
node_advisor -->|"requests advice"| node_clientapi
node_search -->|"requests smart search"| node_clientapi
node_compareai -->|"requests evaluation"| node_clientapi
node_clientapi -->|"sends API requests"| node_express
node_express -->|"uses data store"| node_db
node_db -->|"persists records"| node_firestore
node_express -->|"normalizes search"| node_normalizer
node_express -.->|"requests recommendations"| node_advisorservice
node_advisorservice -.->|"queries product data"| node_db

click node_app "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/App.tsx"
click node_auth "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/context/AuthContext.tsx"
click node_authgate "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/AuthGatewayPage.tsx"
click node_home "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/HomePage.tsx"
click node_products "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ProductsPage.tsx"
click node_productdetail "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ProductDetailsPage.tsx"
click node_cartstate "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/context/CartContext.tsx"
click node_wishlist "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/context/WishlistContext.tsx"
click node_compare "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ComparePage.tsx"
click node_checkout "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/CheckoutPage.tsx"
click node_orders "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/OrdersPage.tsx"
click node_tracking "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/components/RealTimeOrderTracker.tsx"
click node_adminlayout "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminLayout.tsx"
click node_admindashboard "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminDashboard.tsx"
click node_admincatalog "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminProductsPage.tsx"
click node_admincategories "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminCategoriesPage.tsx"
click node_adminorders "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminOrdersPage.tsx"
click node_adminusers "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminUsersPage.tsx"
click node_offers "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminOffersPage.tsx"
click node_advisor "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/AdvisorPage.tsx"
click node_search "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/SearchResultsPage.tsx"
click node_compareai "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ComparePage.tsx"
click node_clientapi "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/services/api.ts"
click node_express "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/server/api.ts"
click node_db "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/server/db.ts"
click node_normalizer "https://github.com/jashikaraja05-pixel/buygen/blob/main/src/lib/spellingNormalizer.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_auth,node_authgate,node_home,node_products,node_productdetail toneBlue
class node_cartstate,node_wishlist,node_compare,node_checkout,node_orders,node_tracking toneAmber
class node_adminlayout,node_admindashboard,node_admincatalog,node_admincategories,node_adminorders,node_adminusers,node_offers toneMint
class node_clientapi,node_express,node_db,node_firestore toneRose
class node_advisor,node_search,node_compareai,node_normalizer,node_advisorservice,node_shopper toneIndigo
```

## Components

### Customer Storefront

- [App Router](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Sign-in & Registration](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/AuthGatewayPage.tsx): `src/pages/AuthGatewayPage.tsx`
- [Home & Catalog](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/HomePage.tsx): `src/pages/HomePage.tsx`
- [Product Discovery](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ProductsPage.tsx): `src/pages/ProductsPage.tsx`
- [Product Details](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ProductDetailsPage.tsx): `src/pages/ProductDetailsPage.tsx`

### Shopping & Orders

- [Cart State](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/context/CartContext.tsx): `src/context/CartContext.tsx`
- [Wishlist](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/context/WishlistContext.tsx): `src/context/WishlistContext.tsx`
- [Product Comparison](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ComparePage.tsx): `src/pages/ComparePage.tsx`
- [Checkout & Payment](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/CheckoutPage.tsx): `src/pages/CheckoutPage.tsx`
- [Order History](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/OrdersPage.tsx): `src/pages/OrdersPage.tsx`
- [Order Tracking](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/components/RealTimeOrderTracker.tsx): `src/components/RealTimeOrderTracker.tsx`

### Admin Console

- [Admin Guard & Layout](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminLayout.tsx): `src/pages/admin/AdminLayout.tsx`
- [Admin Metrics](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminDashboard.tsx): `src/pages/admin/AdminDashboard.tsx`
- [Catalog Management](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminProductsPage.tsx): `src/pages/admin/AdminProductsPage.tsx`
- [Category Management](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminCategoriesPage.tsx): `src/pages/admin/AdminCategoriesPage.tsx`
- [Order Management](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminOrdersPage.tsx): `src/pages/admin/AdminOrdersPage.tsx`
- [User Management](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminUsersPage.tsx): `src/pages/admin/AdminUsersPage.tsx`
- [Offers & Payments](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/admin/AdminOffersPage.tsx): `src/pages/admin/AdminOffersPage.tsx`

### API & Persistence

- [API Client](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/services/api.ts): `src/services/api.ts`
- [Express API](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/server/api.ts): `src/server/api.ts`
- [Database Store](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/server/db.ts): `src/server/db.ts`
- **Firestore**

### AI & Discovery

- [Tech Advisor](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/AdvisorPage.tsx): `src/pages/AdvisorPage.tsx`
- [Smart Search](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/SearchResultsPage.tsx): `src/pages/SearchResultsPage.tsx`
- [AI Comparison](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/pages/ComparePage.tsx): `src/pages/ComparePage.tsx`
- [Spelling Normalizer](https://github.com/jashikaraja05-pixel/buygen/blob/main/src/lib/spellingNormalizer.ts): `src/lib/spellingNormalizer.ts`
- **Gemini Advisor**

### Other components

- **Shopper**

## Connections

- Shopper → App Router: uses
- App Router → Authentication: provides auth (evidence: `src/App.tsx`)
- App Router → Sign-in & Registration: routes unauthenticated (evidence: `src/App.tsx`)
- App Router → Home & Catalog: routes storefront (evidence: `src/App.tsx`)
- App Router → Product Discovery: routes catalog (evidence: `src/App.tsx`)
- App Router → Product Details: routes details (evidence: `src/App.tsx`)
- App Router → Checkout & Payment: routes checkout (evidence: `src/App.tsx`)
- App Router → Order History: routes orders (evidence: `src/App.tsx`)
- App Router → Admin Guard & Layout: routes admin (evidence: `src/App.tsx`)
- Authentication → API Client: calls auth API (evidence: `src/context/AuthContext.tsx`)
- Home & Catalog → API Client: loads storefront data (evidence: `src/pages/HomePage.tsx`)
- Product Discovery → API Client: searches catalog (evidence: `src/pages/ProductsPage.tsx`)
- Product Details → Cart State: adds products (evidence: `src/pages/ProductDetailsPage.tsx`)
- Cart State → API Client: calls cart API (evidence: `src/context/CartContext.tsx`)
- Wishlist → API Client: calls wishlist API (evidence: `src/context/WishlistContext.tsx`)
- Wishlist → Cart State: moves to cart (evidence: `src/context/WishlistContext.tsx`)
- Checkout & Payment → API Client: creates order (evidence: `src/pages/CheckoutPage.tsx`)
- Order History → API Client: loads orders (evidence: `src/pages/OrdersPage.tsx`)
- Order Tracking → Firestore: reads live updates (evidence: `src/components/RealTimeOrderTracker.tsx`)
- Admin Guard & Layout → Authentication: checks role (evidence: `src/pages/admin/AdminLayout.tsx`)
- Admin Metrics → API Client: loads metrics (evidence: `src/pages/admin/AdminDashboard.tsx`)
- Catalog Management → API Client: manages products (evidence: `src/pages/admin/AdminProductsPage.tsx`)
- Category Management → API Client: manages categories (evidence: `src/pages/admin/AdminCategoriesPage.tsx`)
- Order Management → API Client: manages orders (evidence: `src/pages/admin/AdminOrdersPage.tsx`)
- User Management → API Client: manages users (evidence: `src/pages/admin/AdminUsersPage.tsx`)
- Offers & Payments → API Client: manages offers (evidence: `src/services/api.ts`)
- Tech Advisor → API Client: requests advice (evidence: `src/pages/AdvisorPage.tsx`)
- Smart Search → API Client: requests smart search (evidence: `src/pages/SearchResultsPage.tsx`)
- AI Comparison → API Client: requests evaluation (evidence: `src/services/api.ts`)
- API Client → Express API: sends API requests
- Express API → Database Store: uses data store (evidence: `src/server/api.ts`)
- Database Store → Firestore: persists records (evidence: `src/server/db.ts`)
- Express API → Spelling Normalizer: normalizes search (evidence: `src/server/api.ts`)
- Express API → Gemini Advisor: requests recommendations
- Gemini Advisor → Database Store: queries product data
