# kenshincommits/fizzy architecture

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

- Interactive diagram: https://gitdiagram.com/kenshincommits/fizzy
- Repository: https://github.com/kenshincommits/fizzy

## Overview

Fizzi combines a 3D storefront, an admin CRM, and an Express/MongoDB API. The customer journey runs from browsing and behavioral events through lead scoring and pipeline updates; shoppers can also talk with Fulky, whose Retell webhook feeds CRM updates. Admin users inspect and manage customers, leads, orders, and analytics. The README documents the major capabilities and end-to-end flow; sampled source confirms selected UI, controller, and service relationships, while many subsystem details remain unsampled.

Main entry points: [`src/app/shop/page.tsx`](https://github.com/kenshincommits/fizzy/blob/main/src/app/shop/page.tsx) (Shop and pages), [`backend/src/app.ts`](https://github.com/kenshincommits/fizzy/blob/main/backend/src/app.ts) (REST API), [`backend/src/services/scoringService.ts`](https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/scoringService.ts) (Lead scoring), [`backend/src/models/Lead.ts`](https://github.com/kenshincommits/fizzy/blob/main/backend/src/models/Lead.ts) (MongoDB records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_storefront_pages["Shop and pages<br/>[page.tsx]"]
  node_landing["3D landing experience<br/>[page.tsx]"]
  node_slices["Page slices<br/>[index.tsx]"]
  node_product3d["3D product view<br/>[Product3D.tsx]"]
  node_voice["Fulky voice assistant"]
  node_login["Login and signup<br/>[page.tsx]"]
  node_auth["Session helpers<br/>[auth.ts]"]
  node_cms["Prismic content client<br/>[prismicio.ts]"]
end

subgraph group_crm["Admin CRM"]
  node_workspace["CRM workspace<br/>[App.tsx]"]
  node_crm_pages["CRM pages"]
  node_customer_profile["Customer profiles"]
  node_crm_state["CRM state<br/>[store.tsx]"]
  node_crm_api["API client<br/>[api.ts]"]
end

subgraph group_backend["Backend API"]
  node_api_app["REST API<br/>[app.ts]"]
  node_admin_routes["Admin routes<br/>[adminRoutes.ts]"]
  node_admin_controller["Admin handlers<br/>[adminController.ts]"]
  node_agent_controller["Agent handlers<br/>[agentController.ts]"]
  node_retell_service["Retell integration<br/>[retellService.ts]"]
  node_retell_webhook["Retell webhook<br/>[retellWebhook.ts]"]
  node_realtime["Live updates<br/>[socketManager.ts]"]
  node_mongo[("MongoDB records<br/>[Lead.ts]")]
end

subgraph group_intelligence["Lead Intelligence"]
  node_event_processing["Event processing"]
  node_scoring["Lead scoring<br/>[scoringService.ts]"]
  node_behavior["Behavior analysis<br/>[behaviorService.ts]"]
  node_pipeline["Pipeline stages<br/>[pipelineService.ts]"]
end

node_customer(("Shopper"))
node_admin_user(("CRM administrator"))
node_retell["Retell AI"]

node_customer -->|"browses"| node_storefront_pages
node_customer -->|"views"| node_landing
node_landing -->|"renders"| node_slices
node_storefront_pages -->|"renders"| node_product3d
node_storefront_pages -->|"offers"| node_voice
node_customer -->|"authenticates"| node_login
node_login -->|"stores session"| node_auth
node_landing -->|"loads content"| node_cms
node_storefront_pages -->|"sends events"| node_api_app
node_voice -->|"requests call"| node_api_app
node_api_app -->|"proxies call"| node_retell
node_retell -->|"posts transcript"| node_retell_webhook
node_retell_webhook -->|"updates records"| node_mongo
node_retell_webhook -->|"broadcasts update"| node_realtime
node_storefront_pages -->|"emits behavior events"| node_event_processing
node_event_processing -->|"scores events"| node_scoring
node_scoring -.->|"updates lead"| node_mongo
node_pipeline -->|"reads and saves lead"| node_mongo
node_scoring -.->|"advances stage"| node_pipeline
node_agent_controller -->|"calculates behavior"| node_behavior
node_agent_controller -->|"initiates calls"| node_retell_service
node_admin_user -->|"manages CRM"| node_workspace
node_workspace -->|"routes pages"| node_crm_pages
node_workspace -->|"opens profile"| node_customer_profile
node_crm_pages -->|"reads and updates"| node_crm_state
node_crm_state -->|"loads and mutates data"| node_crm_api
node_crm_api -->|"calls REST API"| node_api_app
node_api_app -.->|"mounts routes"| node_admin_routes
node_admin_routes -->|"dispatches handlers"| node_admin_controller
node_admin_controller -->|"reads and writes records"| node_mongo
node_admin_controller -->|"manages scoring rules"| node_scoring

click node_storefront_pages "https://github.com/kenshincommits/fizzy/blob/main/src/app/shop/page.tsx"
click node_landing "https://github.com/kenshincommits/fizzy/blob/main/src/app/page.tsx"
click node_slices "https://github.com/kenshincommits/fizzy/blob/main/src/slices/Carousel/index.tsx"
click node_product3d "https://github.com/kenshincommits/fizzy/blob/main/src/components/Product3D.tsx"
click node_voice "https://github.com/kenshincommits/fizzy/blob/main/src/components/FulkyVoiceAssistant.tsx"
click node_login "https://github.com/kenshincommits/fizzy/blob/main/src/app/login/page.tsx"
click node_auth "https://github.com/kenshincommits/fizzy/blob/main/src/lib/auth.ts"
click node_cms "https://github.com/kenshincommits/fizzy/blob/main/src/prismicio.ts"
click node_workspace "https://github.com/kenshincommits/fizzy/blob/main/admin/src/App.tsx"
click node_crm_pages "https://github.com/kenshincommits/fizzy/tree/main/admin/src/pages"
click node_customer_profile "https://github.com/kenshincommits/fizzy/blob/main/admin/src/components/CustomerProfile.tsx"
click node_crm_state "https://github.com/kenshincommits/fizzy/blob/main/admin/src/lib/store.tsx"
click node_crm_api "https://github.com/kenshincommits/fizzy/blob/main/admin/src/lib/api.ts"
click node_api_app "https://github.com/kenshincommits/fizzy/blob/main/backend/src/app.ts"
click node_admin_routes "https://github.com/kenshincommits/fizzy/blob/main/backend/src/routes/adminRoutes.ts"
click node_admin_controller "https://github.com/kenshincommits/fizzy/blob/main/backend/src/controllers/adminController.ts"
click node_agent_controller "https://github.com/kenshincommits/fizzy/blob/main/backend/src/controllers/agentController.ts"
click node_retell_service "https://github.com/kenshincommits/fizzy/blob/main/backend/src/integrations/retell/retellService.ts"
click node_retell_webhook "https://github.com/kenshincommits/fizzy/blob/main/backend/src/webhooks/retellWebhook.ts"
click node_realtime "https://github.com/kenshincommits/fizzy/blob/main/backend/src/realtime/socketManager.ts"
click node_mongo "https://github.com/kenshincommits/fizzy/blob/main/backend/src/models/Lead.ts"
click node_event_processing "https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/eventProcessingService.ts"
click node_scoring "https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/scoringService.ts"
click node_behavior "https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/behaviorService.ts"
click node_pipeline "https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/pipelineService.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_storefront_pages,node_landing,node_slices,node_product3d,node_voice,node_login,node_auth,node_cms toneBlue
class node_workspace,node_crm_pages,node_customer_profile,node_crm_state,node_crm_api toneAmber
class node_api_app,node_admin_routes,node_admin_controller,node_agent_controller,node_retell_service,node_retell_webhook,node_realtime,node_mongo toneMint
class node_event_processing,node_scoring,node_behavior,node_pipeline toneRose
class node_customer,node_admin_user,node_retell toneIndigo
```

## Components

### Storefront

- [Shop and pages](https://github.com/kenshincommits/fizzy/blob/main/src/app/shop/page.tsx): `src/app/shop/page.tsx`
- [3D landing experience](https://github.com/kenshincommits/fizzy/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Page slices](https://github.com/kenshincommits/fizzy/blob/main/src/slices/Carousel/index.tsx): `src/slices/Carousel/index.tsx`
- [3D product view](https://github.com/kenshincommits/fizzy/blob/main/src/components/Product3D.tsx): `src/components/Product3D.tsx`
- [Fulky voice assistant](https://github.com/kenshincommits/fizzy/blob/main/src/components/FulkyVoiceAssistant.tsx): `src/components/FulkyVoiceAssistant.tsx`
- [Login and signup](https://github.com/kenshincommits/fizzy/blob/main/src/app/login/page.tsx): `src/app/login/page.tsx`
- [Session helpers](https://github.com/kenshincommits/fizzy/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Prismic content client](https://github.com/kenshincommits/fizzy/blob/main/src/prismicio.ts): `src/prismicio.ts`

### Admin CRM

- [CRM workspace](https://github.com/kenshincommits/fizzy/blob/main/admin/src/App.tsx): `admin/src/App.tsx`
- [CRM pages](https://github.com/kenshincommits/fizzy/tree/main/admin/src/pages): `admin/src/pages`
- [Customer profiles](https://github.com/kenshincommits/fizzy/blob/main/admin/src/components/CustomerProfile.tsx): `admin/src/components/CustomerProfile.tsx`
- [CRM state](https://github.com/kenshincommits/fizzy/blob/main/admin/src/lib/store.tsx): `admin/src/lib/store.tsx`
- [API client](https://github.com/kenshincommits/fizzy/blob/main/admin/src/lib/api.ts): `admin/src/lib/api.ts`

### Backend API

- [REST API](https://github.com/kenshincommits/fizzy/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Admin routes](https://github.com/kenshincommits/fizzy/blob/main/backend/src/routes/adminRoutes.ts): `backend/src/routes/adminRoutes.ts`
- [Admin handlers](https://github.com/kenshincommits/fizzy/blob/main/backend/src/controllers/adminController.ts): `backend/src/controllers/adminController.ts`
- [Agent handlers](https://github.com/kenshincommits/fizzy/blob/main/backend/src/controllers/agentController.ts): `backend/src/controllers/agentController.ts`
- [Retell integration](https://github.com/kenshincommits/fizzy/blob/main/backend/src/integrations/retell/retellService.ts): `backend/src/integrations/retell/retellService.ts`
- [Retell webhook](https://github.com/kenshincommits/fizzy/blob/main/backend/src/webhooks/retellWebhook.ts): `backend/src/webhooks/retellWebhook.ts`
- [Live updates](https://github.com/kenshincommits/fizzy/blob/main/backend/src/realtime/socketManager.ts): `backend/src/realtime/socketManager.ts`
- [MongoDB records](https://github.com/kenshincommits/fizzy/blob/main/backend/src/models/Lead.ts): `backend/src/models/Lead.ts`

### Lead Intelligence

- [Event processing](https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/eventProcessingService.ts): `backend/src/services/eventProcessingService.ts`
- [Lead scoring](https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/scoringService.ts): `backend/src/services/scoringService.ts`
- [Behavior analysis](https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/behaviorService.ts): `backend/src/services/behaviorService.ts`
- [Pipeline stages](https://github.com/kenshincommits/fizzy/blob/main/backend/src/services/pipelineService.ts): `backend/src/services/pipelineService.ts`

### Other components

- **Shopper**
- **CRM administrator**
- **Retell AI**

## Connections

- Shopper → Shop and pages: browses (evidence: `README.md`)
- Shopper → 3D landing experience: views (evidence: `README.md`)
- 3D landing experience → Page slices: renders (evidence: `src/app/page.tsx`)
- Shop and pages → 3D product view: renders (evidence: `src/app/shop/page.tsx`)
- Shop and pages → Fulky voice assistant: offers (evidence: `README.md`)
- Shopper → Login and signup: authenticates (evidence: `README.md`)
- Login and signup → Session helpers: stores session (evidence: `src/app/login/page.tsx`)
- 3D landing experience → Prismic content client: loads content (evidence: `src/app/page.tsx`)
- Shop and pages → REST API: sends events (evidence: `README.md`)
- Fulky voice assistant → REST API: requests call (evidence: `README.md`)
- REST API → Retell AI: proxies call (evidence: `README.md`)
- Retell AI → Retell webhook: posts transcript (evidence: `README.md`)
- Retell webhook → MongoDB records: updates records (evidence: `README.md`)
- Retell webhook → Live updates: broadcasts update (evidence: `README.md`)
- Shop and pages → Event processing: emits behavior events (evidence: `README.md`)
- Event processing → Lead scoring: scores events (evidence: `README.md`)
- Lead scoring → MongoDB records: updates lead
- Pipeline stages → MongoDB records: reads and saves lead (evidence: `backend/src/services/pipelineService.ts`)
- Lead scoring → Pipeline stages: advances stage
- Agent handlers → Behavior analysis: calculates behavior (evidence: `backend/src/controllers/agentController.ts`)
- Agent handlers → Retell integration: initiates calls (evidence: `backend/src/controllers/agentController.ts`)
- CRM administrator → CRM workspace: manages CRM (evidence: `README.md`)
- CRM workspace → CRM pages: routes pages (evidence: `admin/src/App.tsx`)
- CRM workspace → Customer profiles: opens profile (evidence: `admin/src/App.tsx`)
- CRM pages → CRM state: reads and updates (evidence: `admin/src/pages/Pipeline.tsx`)
- CRM state → API client: loads and mutates data (evidence: `admin/src/lib/store.tsx`)
- API client → REST API: calls REST API (evidence: `README.md`)
- REST API → Admin routes: mounts routes
- Admin routes → Admin handlers: dispatches handlers (evidence: `backend/src/routes/adminRoutes.ts`)
- Admin handlers → MongoDB records: reads and writes records (evidence: `backend/src/controllers/adminController.ts`)
- Admin handlers → Lead scoring: manages scoring rules (evidence: `backend/src/controllers/adminController.ts`)