# dncmaduro/candy-cal-fe architecture

> Architecture diagram of the GitHub repository dncmaduro/candy-cal-fe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dncmaduro/candy-cal-fe
- Repository: https://github.com/dncmaduro/candy-cal-fe

## Overview

#### Purpose and runtime
Candy Cal FE is an internal MyCandy operations/administration SPA for sales, marketing/storage, livestream, marketplace income, and admin workflows. It runs as a React 18 + TypeScript application built by Vite; production is static `dist/` content served through Nginx/static hosting. Entry bootstrap: `src/main.tsx`, root application shell: `src/App.tsx`.

#### Routing and access boundaries
TanStack Router file routes define functional areas and page composition; its generated tree is `src/routeTree.gen.ts`. Root-level route behavior is centralized in `src/routes/__root.tsx`; major route partitions include sales (`src/routes/sales/index.tsx`), marketing storage (`src/routes/marketing-storage/index.tsx`), livestream (`src/routes/livestream/index.tsx`), and administration (`src/routes/admin/index.tsx`). Route-specific layouts separate operational contexts: `src/components/layouts/AppLayout.tsx`, `src/components/layouts/SalesLayout.tsx`, `src/components/layouts/AdminLayout.tsx`.

#### API, auth, and state layer
Domain hooks are the boundary between UI and backend APIs, with Axios transport configured in `src/hooks/axios.ts` and endpoint selection/failover likely managed by `src/hooks/useEndpoints.ts`. Authentication/session enforcement is represented by `src/hooks/useAuthGuard.ts` and `src/utils/authSession.ts`. Cross-page client state is held in Zustand stores such as `src/store/userStore.ts`, `src/store/uiStore.ts`, and `src/store/calResultStore.ts`. Backend URLs come from `VITE_BACKEND_URL`; API contract implementations are primarily distributed across `src/hooks/`.

#### Sales CRM and analytics
The sales area manages leads, funnels, orders, catalog/price items, activities, tasks, channels, and customer ranking. Route pages orchestrate views and entity navigation, notably `src/routes/sales/funnel/index.tsx`, `src/routes/sales/orders/$orderId.tsx`, and `src/routes/sales/dashboard/index.tsx`. Business UI and mutation flows live in `src/components/sales/`, while data access is separated into hooks including `src/hooks/useSalesFunnel.ts`, `src/hooks/useSalesOrders.ts`, and `src/hooks/useSalesDashboard.ts`.

#### Marketing, inventory, and income operations
Marketing-storage combines inventory/product maintenance, calculators, delivery requests, logs, accounting storage, and income reporting. Representative boundaries are routes `src/routes/marketing-storage/storage/index.tsx`, `src/routes/marketing-storage/incomes/index.tsx`, and `src/routes/marketing-storage/accounting-storage/index.tsx`; domain UIs reside in `src/components/storage/`, `src/components/incomes/`, and `src/components/accounting-storage/`. Income imports have an explicit asynchronous client-side pipeline: `src/services/incomeImportTask.ts`, `src/workers/incomeImport.worker.ts`, and `src/store/incomeImportTaskStore.ts`.

#### Marketplace and livestream domains
Shopee and TikTok Shop have dedicated route spaces for income and SKU workflows: `src/routes/shopee/index.tsx`, `src/routes/shopee/kpi/index.tsx`, and `src/routes/tiktokshop/index.tsx`. Shopee dashboards are assembled from specialized analytics components and hooks, including `src/components/incomes/shopee-dashboard/ShopeePerformanceDashboardPage.tsx`, `src/hooks/useShopeeDashboardOverview.ts`, and `src/hooks/useShopeePerformanceMetrics.ts`. Livestream manages channels, personnel, calendars, goals, reports, performance, and salary through `src/routes/livestream/calendar/index.tsx`, `src/components/livestream/LivestreamCalendarRegion.tsx`, and `src/hooks/useLivestreamCore.ts`.

#### Realtime, AI, media, and deployment integrations
Socket-based updates are isolated behind `src/hooks/useSocket.ts` and `src/hooks/useMetaSocket.ts`, configured by `VITE_WEB_SOCKET_URL`; delivered-request channels also have a domain adapter at `src/components/delivered-requests/deliveredRequestChannel.ts`. AI interaction is surfaced through `src/components/ai/AiChatSidebar.tsx` and `src/hooks/useAi.ts`. Cloudinary configuration supports image uploads, likely consumed by media hooks/components such as `src/hooks/useMedia.ts` and `src/components/common/CCrop.tsx`. Deployment targets include Docker/Nginx (`Dockerfile.staging`, `nginx.vite.conf`) and static-host configuration (`netlify.toml`, `vercel.json`).

Main entry points: [`src/routeTree.gen.ts`](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routeTree.gen.ts) (TanStack route tree), [`src/App.tsx`](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/App.tsx) (Root app shell), [`src/routes/__root.tsx`](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/__root.tsx) (Root route boundary), [`src/services/incomeImportTask.ts`](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/services/incomeImportTask.ts) (Income import pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Application Shell"]
  node_bootstrap(("Vite bootstrap<br/>entrypoint<br/>[main.tsx]"))
  node_app["Root app shell<br/>React shell<br/>[App.tsx]"]
  node_router["TanStack route tree<br/>routing<br/>[routeTree.gen.ts]"]
  node_root_route["Root route boundary<br/>route guard<br/>[__root.tsx]"]
  node_layouts["Operational layouts<br/>[AppLayout.tsx]"]
end

subgraph group_domains["Operational Domains"]
  node_sales_routes["Sales CRM routes<br/>route area<br/>[index.tsx]"]
  node_sales_ui["Sales workflows<br/>domain UI"]
  node_sales_api["Sales data hooks<br/>API hooks<br/>[useSalesFunnel.ts]"]
  node_storage_routes["Marketing-storage routes<br/>route area<br/>[index.tsx]"]
  node_storage_ui["Storage and income UI<br/>domain UI"]
  node_income_import["Income import pipeline<br/>async pipeline"]
  node_income_worker["Income import worker<br/>Web Worker"]
  node_marketplace_routes["Shopee and TikTok Shop<br/>route areas<br/>[index.tsx]"]
  node_shopee_analytics["Shopee analytics<br/>analytics UI"]
  node_livestream["Livestream operations<br/>route and domain UI<br/>[index.tsx]"]
  node_admin_routes["Administration routes<br/>route area<br/>[index.tsx]"]
end

subgraph group_platform["Client Platform"]
  node_api_transport["Backend API transport<br/>Axios client<br/>[axios.ts]"]
  node_auth["Session enforcement<br/>auth guard<br/>[useAuthGuard.ts]"]
  node_state[("Cross-page state<br/>Zustand stores<br/>[userStore.ts]")]
  node_realtime["Realtime adapters<br/>socket hooks<br/>[useSocket.ts]"]
  node_ai_media["AI and media tools<br/>client integrations<br/>[AiChatSidebar.tsx]"]
  node_static_hosting{{"Static deployment<br/>Nginx/static hosting<br/>[nginx.vite.conf]"}}
end

node_bootstrap -->|"mounts"| node_app
node_app -->|"renders routes"| node_router
node_router -->|"starts at"| node_root_route
node_root_route -->|"enforces session"| node_auth
node_root_route -->|"selects context"| node_layouts
node_router -->|"composes"| node_sales_routes
node_router -->|"composes"| node_storage_routes
node_router -->|"composes"| node_marketplace_routes
node_router -->|"composes"| node_livestream
node_router -->|"composes"| node_admin_routes
node_sales_routes -->|"hosts"| node_sales_ui
node_sales_ui -->|"loads and mutates"| node_sales_api
node_sales_api -->|"uses"| node_api_transport
node_storage_routes -->|"hosts"| node_storage_ui
node_storage_ui -->|"starts imports"| node_income_import
node_income_import -->|"delegates work"| node_income_worker
node_income_import -->|"tracks task state"| node_state
node_marketplace_routes -->|"renders"| node_shopee_analytics
node_shopee_analytics -->|"queries metrics"| node_api_transport
node_livestream -->|"uses domain APIs"| node_api_transport
node_app -->|"shares client state"| node_state
node_app -.->|"receives updates"| node_realtime
node_app -.->|"uses"| node_ai_media
node_app -->|"builds to static output"| node_static_hosting

click node_bootstrap "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/main.tsx"
click node_app "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/App.tsx"
click node_router "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routeTree.gen.ts"
click node_root_route "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/__root.tsx"
click node_layouts "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/components/layouts/AppLayout.tsx"
click node_sales_routes "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/sales/index.tsx"
click node_sales_api "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/useSalesFunnel.ts"
click node_storage_routes "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/marketing-storage/index.tsx"
click node_income_import "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/services/incomeImportTask.ts"
click node_income_worker "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/workers/incomeImport.worker.ts"
click node_marketplace_routes "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/shopee/index.tsx"
click node_shopee_analytics "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/components/incomes/shopee-dashboard/ShopeePerformanceDashboardPage.tsx"
click node_livestream "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/livestream/calendar/index.tsx"
click node_admin_routes "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/admin/index.tsx"
click node_api_transport "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/axios.ts"
click node_auth "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/useAuthGuard.ts"
click node_state "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/store/userStore.ts"
click node_realtime "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/useSocket.ts"
click node_ai_media "https://github.com/dncmaduro/candy-cal-fe/blob/main/src/components/ai/AiChatSidebar.tsx"
click node_static_hosting "https://github.com/dncmaduro/candy-cal-fe/blob/main/nginx.vite.conf"

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_bootstrap,node_app,node_router,node_root_route,node_layouts toneBlue
class node_sales_routes,node_sales_ui,node_sales_api,node_storage_routes,node_storage_ui,node_income_import,node_income_worker,node_marketplace_routes,node_shopee_analytics,node_livestream,node_admin_routes toneAmber
class node_api_transport,node_auth,node_state,node_realtime,node_ai_media,node_static_hosting toneMint
```

## Components

### Application Shell

- [Vite bootstrap](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/main.tsx): entrypoint · `src/main.tsx`
- [Root app shell](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/App.tsx): React shell · `src/App.tsx`
- [TanStack route tree](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routeTree.gen.ts): routing · Generated route composition tree. · `src/routeTree.gen.ts`
- [Root route boundary](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/__root.tsx): route guard · `src/routes/__root.tsx`
- [Operational layouts](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/components/layouts/AppLayout.tsx): layouts · App, sales, and admin contexts. · `src/components/layouts/AppLayout.tsx`

### Operational Domains

- [Sales CRM routes](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/sales/index.tsx): route area · Funnels, orders, and dashboard pages. · `src/routes/sales/index.tsx`
- **Sales workflows**: domain UI
- [Sales data hooks](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/useSalesFunnel.ts): API hooks · `src/hooks/useSalesFunnel.ts`
- [Marketing-storage routes](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/marketing-storage/index.tsx): route area · Inventory, accounting storage, and income operations. · `src/routes/marketing-storage/index.tsx`
- **Storage and income UI**: domain UI
- [Income import pipeline](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/services/incomeImportTask.ts): async pipeline · Client task delegates import work to a Web Worker. · `src/services/incomeImportTask.ts`
- [Income import worker](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/workers/incomeImport.worker.ts): Web Worker · `src/workers/incomeImport.worker.ts`
- [Shopee and TikTok Shop](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/shopee/index.tsx): route areas · Marketplace income, KPI, and SKU workflows. · `src/routes/shopee/index.tsx`
- [Shopee analytics](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/components/incomes/shopee-dashboard/ShopeePerformanceDashboardPage.tsx): analytics UI · `src/components/incomes/shopee-dashboard/ShopeePerformanceDashboardPage.tsx`
- [Livestream operations](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/livestream/calendar/index.tsx): route and domain UI · Calendars, channels, performance, and salary workflows. · `src/routes/livestream/calendar/index.tsx`
- [Administration routes](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/routes/admin/index.tsx): route area · `src/routes/admin/index.tsx`

### Client Platform

- [Backend API transport](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/axios.ts): Axios client · Backend URL is selected from VITE_BACKEND_URL. · `src/hooks/axios.ts`
- [Session enforcement](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/useAuthGuard.ts): auth guard · `src/hooks/useAuthGuard.ts`
- [Cross-page state](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/store/userStore.ts): Zustand stores · User, UI, calculator-result, and import-task state. · `src/store/userStore.ts`
- [Realtime adapters](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/hooks/useSocket.ts): socket hooks · Socket endpoints use VITE_WEB_SOCKET_URL. · `src/hooks/useSocket.ts`
- [AI and media tools](https://github.com/dncmaduro/candy-cal-fe/blob/main/src/components/ai/AiChatSidebar.tsx): client integrations · AI chat and Cloudinary-backed media interactions. · `src/components/ai/AiChatSidebar.tsx`
- [Static deployment](https://github.com/dncmaduro/candy-cal-fe/blob/main/nginx.vite.conf): Nginx/static hosting · Vite dist output is served by deployment targets. · `nginx.vite.conf`

## Connections

- Vite bootstrap → Root app shell: mounts
- Root app shell → TanStack route tree: renders routes
- TanStack route tree → Root route boundary: starts at
- Root route boundary → Session enforcement: enforces session
- Root route boundary → Operational layouts: selects context
- TanStack route tree → Sales CRM routes: composes
- TanStack route tree → Marketing-storage routes: composes
- TanStack route tree → Shopee and TikTok Shop: composes
- TanStack route tree → Livestream operations: composes
- TanStack route tree → Administration routes: composes
- Sales CRM routes → Sales workflows: hosts
- Sales workflows → Sales data hooks: loads and mutates
- Sales data hooks → Backend API transport: uses
- Marketing-storage routes → Storage and income UI: hosts
- Storage and income UI → Income import pipeline: starts imports
- Income import pipeline → Income import worker: delegates work
- Income import pipeline → Cross-page state: tracks task state
- Shopee and TikTok Shop → Shopee analytics: renders
- Shopee analytics → Backend API transport: queries metrics
- Livestream operations → Backend API transport: uses domain APIs
- Root app shell → Cross-page state: shares client state
- Root app shell → Realtime adapters: receives updates
- Root app shell → AI and media tools: uses
- Root app shell → Static deployment: builds to static output