# dncmaduro/candy-cal-be architecture

> Architecture diagram of the GitHub repository dncmaduro/candy-cal-be, 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-be
- Repository: https://github.com/dncmaduro/candy-cal-be

## Overview

#### Purpose and entry points
Candy Cal is a NestJS backend for internal commerce operations: orders, inventory, revenue/KPIs, sales leads, livestream operations, Shopee analytics, logging, and notifications. It exposes REST APIs, Swagger/OpenAPI, and WebSocket gateways. Runtime bootstrapping and module composition are centered at `src/main.ts`, `src/app.module.ts`, and `src/app.controller.ts`.

#### API boundary, identity, and authorization
Controllers provide domain REST boundaries; DTOs validate/request-shape inputs. JWT authentication and role-based authorization protect operations, with roles such as admin, accounting, TikTok Shop, and read-only system employee. Swagger is generated from registered REST controllers at `/api/v1/docs`; WebSocket APIs are outside OpenAPI. Core paths: `src/auth/jwt.strategy.ts`, `src/auth/jwt-auth.guard.ts`, `src/roles/roles.guard.ts`.

#### Persistence and cross-cutting operations
MongoDB is the system of record through Mongoose schemas registered by the database module. The schema layer models operational records across users, orders, inventories, sales, Shopee, AI, and audit data. Shared error handling, lazy loading, cache abstraction, and currency conversion sit outside individual domains. Core paths: `src/database/database.module.ts`, `src/database/mongoose/schemas/User.ts`, `src/common/filters/all-exceptions.filter.ts`.

#### Fulfillment, inventory, and revenue pipeline
Product/item catalogs, packing rules, storage movements, production/order logs, delivery requests, and income imports form the core operational flow. Income import ingests Shopee exports, excludes canceled records, replaces duplicate source/day product data, then derives box assignments using packing rules; monthly goals consume revenue/quantity splits for KPI calculations. Core paths: `src/income/income.service.ts`, `src/packingrules/packingrules.service.ts`, `src/storagelogs/storagelogs.service.ts`.

#### Sales lead and order management
The sales subsystem manages channels, funnels, leads/cases, assignments and calls, customer ranks, activities/tasks, price items, inventory periods, and sales orders. Dashboard APIs aggregate these operational collections for reporting. A documented migration suite supports transition of legacy sales-lead ownership/funnel data directly in MongoDB. Core paths: `src/salesleads/salesleads.service.ts`, `src/salesorders/salesorders.service.ts`, `scripts/sales-lead-migration/execute.mongosh.js`.

#### Marketplace and livestream analytics
Shopee-specific data is modeled separately from generic income: daily ads, live revenue, products, income, monthly KPIs, and analytical dashboard queries. Livestream operations similarly separate channels, periods, performance, employees, goals, salaries, and alternate requests. These modules aggregate persisted operational data rather than representing an external Shopee API client. Core paths: `src/shopeedashboard/shopee-dashboard.repository.ts`, `src/livestreamanalytics/livestreamanalytics.service.ts`, `src/database/mongoose/schemas/ShopeeMonthKpi.ts`.

#### Realtime, integrations, AI, and observability
Notifications are persisted and delivered through a WebSocket gateway; Meta has REST/webhook and gateway surfaces. The AI module maintains conversation, feedback, usage, and routing/database context, indicating an assistant feature layered over internal data. System logs normalize important actions, while request auditing covers discovered daily-task endpoints. Core paths: `src/notifications/notifications.gateway.ts`, `src/meta/meta-webhook.controller.ts`, `src/ai/ai.service.ts`.

#### Runtime and delivery
This is a Node.js/NestJS service deployed in Docker, with development and production/staging Dockerfiles plus Compose definitions. CI and deployment are automated through GitHub Actions. MongoDB is required infrastructure; JWT configuration and likely integration credentials are environment-provided. Core paths: `Dockerfile`, `docker-compose.yml`, `.github/workflows/deploy.yml`.

Main entry points: [`src/database/database.module.ts`](https://github.com/dncmaduro/candy-cal-be/blob/main/src/database/database.module.ts) (MongoDB), [`src/app.controller.ts`](https://github.com/dncmaduro/candy-cal-be/blob/main/src/app.controller.ts) (REST controllers), [`src/income/income.service.ts`](https://github.com/dncmaduro/candy-cal-be/blob/main/src/income/income.service.ts) (Income & fulfillment), [`src/app.module.ts`](https://github.com/dncmaduro/candy-cal-be/blob/main/src/app.module.ts) (Application module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & delivery"]
  node_bootstrap{{"Nest bootstrap<br/>NestJS runtime<br/>[main.ts]"}}
  node_app["Application module<br/>module composition<br/>[app.module.ts]"]
  node_delivery["Docker &amp; CI delivery<br/>deployment automation"]
end

subgraph group_boundary["API &amp; access"]
  node_rest["REST controllers<br/>HTTP API boundary<br/>[app.controller.ts]"]
  node_swagger["Swagger / OpenAPI<br/>API documentation<br/>[main.ts]"]
  node_jwt["JWT authentication<br/>auth strategy and guard<br/>[jwt-auth.guard.ts]"]
  node_roles["Role authorization<br/>RBAC guard<br/>[roles.guard.ts]"]
end

subgraph group_operations["Commerce operations"]
  node_fulfillment["Income &amp; fulfillment<br/>operational pipeline<br/>[income.service.ts]"]
  node_packing["Packing rules<br/>fulfillment rules"]
  node_storage["Storage movements<br/>inventory operations"]
  node_salesleads["Sales leads<br/>lead operations"]
  node_salesorders["Sales orders<br/>order operations"]
  node_migration["Sales-lead migration<br/>MongoDB migration script<br/>[execute.mongosh.js]"]
end

subgraph group_analytics["Analytics &amp; realtime"]
  node_shopee["Shopee analytics<br/>analytics repository"]
  node_livestream["Livestream analytics<br/>operations analytics"]
  node_notifications["Notifications gateway<br/>WebSocket gateway"]
  node_meta["Meta webhook API<br/>webhook controller"]
  node_ai["AI assistant<br/>AI service<br/>[ai.service.ts]"]
end

node_mongo[("MongoDB<br/>system of record<br/>[database.module.ts]")]
node_errors["Global error handling<br/>exception filter"]

node_bootstrap -->|"boots"| node_app
node_bootstrap -->|"publishes"| node_swagger
node_app -->|"registers"| node_rest
node_app -->|"applies"| node_errors
node_rest -->|"authenticates with"| node_jwt
node_jwt -->|"enables"| node_roles
node_rest -->|"operates"| node_fulfillment
node_rest -->|"operates"| node_salesleads
node_rest -->|"operates"| node_salesorders
node_rest -->|"queries"| node_shopee
node_fulfillment -->|"derives assignments from"| node_packing
node_fulfillment -->|"records movements"| node_storage
node_fulfillment -->|"imports and persists"| node_mongo
node_salesleads -->|"persists"| node_mongo
node_salesorders -->|"persists"| node_mongo
node_migration -.->|"updates legacy data"| node_mongo
node_shopee -->|"aggregates"| node_mongo
node_livestream -->|"aggregates"| node_mongo
node_notifications -->|"persists"| node_mongo
node_meta -->|"triggers"| node_notifications
node_ai -->|"stores context and usage"| node_mongo
node_delivery -.->|"deploys"| node_bootstrap

click node_bootstrap "https://github.com/dncmaduro/candy-cal-be/blob/main/src/main.ts"
click node_app "https://github.com/dncmaduro/candy-cal-be/blob/main/src/app.module.ts"
click node_delivery "https://github.com/dncmaduro/candy-cal-be/blob/main/Dockerfile"
click node_rest "https://github.com/dncmaduro/candy-cal-be/blob/main/src/app.controller.ts"
click node_swagger "https://github.com/dncmaduro/candy-cal-be/blob/main/src/main.ts"
click node_jwt "https://github.com/dncmaduro/candy-cal-be/blob/main/src/auth/jwt-auth.guard.ts"
click node_roles "https://github.com/dncmaduro/candy-cal-be/blob/main/src/roles/roles.guard.ts"
click node_mongo "https://github.com/dncmaduro/candy-cal-be/blob/main/src/database/database.module.ts"
click node_errors "https://github.com/dncmaduro/candy-cal-be/blob/main/src/common/filters/all-exceptions.filter.ts"
click node_fulfillment "https://github.com/dncmaduro/candy-cal-be/blob/main/src/income/income.service.ts"
click node_packing "https://github.com/dncmaduro/candy-cal-be/blob/main/src/packingrules/packingrules.service.ts"
click node_storage "https://github.com/dncmaduro/candy-cal-be/blob/main/src/storagelogs/storagelogs.service.ts"
click node_salesleads "https://github.com/dncmaduro/candy-cal-be/blob/main/src/salesleads/salesleads.service.ts"
click node_salesorders "https://github.com/dncmaduro/candy-cal-be/blob/main/src/salesorders/salesorders.service.ts"
click node_migration "https://github.com/dncmaduro/candy-cal-be/blob/main/scripts/sales-lead-migration/execute.mongosh.js"
click node_shopee "https://github.com/dncmaduro/candy-cal-be/blob/main/src/shopeedashboard/shopee-dashboard.repository.ts"
click node_livestream "https://github.com/dncmaduro/candy-cal-be/blob/main/src/livestreamanalytics/livestreamanalytics.service.ts"
click node_notifications "https://github.com/dncmaduro/candy-cal-be/blob/main/src/notifications/notifications.gateway.ts"
click node_meta "https://github.com/dncmaduro/candy-cal-be/blob/main/src/meta/meta-webhook.controller.ts"
click node_ai "https://github.com/dncmaduro/candy-cal-be/blob/main/src/ai/ai.service.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_bootstrap,node_app,node_delivery toneBlue
class node_rest,node_swagger,node_jwt,node_roles toneAmber
class node_fulfillment,node_packing,node_storage,node_salesleads,node_salesorders,node_migration toneMint
class node_shopee,node_livestream,node_notifications,node_meta,node_ai toneRose
class node_mongo,node_errors toneNeutral
```

## Components

### Runtime & delivery

- [Nest bootstrap](https://github.com/dncmaduro/candy-cal-be/blob/main/src/main.ts): NestJS runtime · Starts the application and composes modules. · `src/main.ts`
- [Application module](https://github.com/dncmaduro/candy-cal-be/blob/main/src/app.module.ts): module composition · `src/app.module.ts`
- [Docker & CI delivery](https://github.com/dncmaduro/candy-cal-be/blob/main/Dockerfile): deployment automation · Builds and deploys the Node service. · `Dockerfile`

### API & access

- [REST controllers](https://github.com/dncmaduro/candy-cal-be/blob/main/src/app.controller.ts): HTTP API boundary · Domain controllers expose internal operations APIs. · `src/app.controller.ts`
- [Swagger / OpenAPI](https://github.com/dncmaduro/candy-cal-be/blob/main/src/main.ts): API documentation · Documents registered REST controllers at /api/v1/docs. · `src/main.ts`
- [JWT authentication](https://github.com/dncmaduro/candy-cal-be/blob/main/src/auth/jwt-auth.guard.ts): auth strategy and guard · `src/auth/jwt-auth.guard.ts`
- [Role authorization](https://github.com/dncmaduro/candy-cal-be/blob/main/src/roles/roles.guard.ts): RBAC guard · `src/roles/roles.guard.ts`

### Commerce operations

- [Income & fulfillment](https://github.com/dncmaduro/candy-cal-be/blob/main/src/income/income.service.ts): operational pipeline · Imports income, removes canceled or duplicate data, and derives box assignments. · `src/income/income.service.ts`
- [Packing rules](https://github.com/dncmaduro/candy-cal-be/blob/main/src/packingrules/packingrules.service.ts): fulfillment rules · `src/packingrules/packingrules.service.ts`
- [Storage movements](https://github.com/dncmaduro/candy-cal-be/blob/main/src/storagelogs/storagelogs.service.ts): inventory operations · `src/storagelogs/storagelogs.service.ts`
- [Sales leads](https://github.com/dncmaduro/candy-cal-be/blob/main/src/salesleads/salesleads.service.ts): lead operations · Manages funnels, cases, assignments, calls, activities, and tasks. · `src/salesleads/salesleads.service.ts`
- [Sales orders](https://github.com/dncmaduro/candy-cal-be/blob/main/src/salesorders/salesorders.service.ts): order operations · `src/salesorders/salesorders.service.ts`
- [Sales-lead migration](https://github.com/dncmaduro/candy-cal-be/blob/main/scripts/sales-lead-migration/execute.mongosh.js): MongoDB migration script · Migrates legacy ownership and funnel data. · `scripts/sales-lead-migration/execute.mongosh.js`

### Analytics & realtime

- [Shopee analytics](https://github.com/dncmaduro/candy-cal-be/blob/main/src/shopeedashboard/shopee-dashboard.repository.ts): analytics repository · Queries persisted ads, live revenue, products, income, and monthly KPIs. · `src/shopeedashboard/shopee-dashboard.repository.ts`
- [Livestream analytics](https://github.com/dncmaduro/candy-cal-be/blob/main/src/livestreamanalytics/livestreamanalytics.service.ts): operations analytics · Aggregates channels, periods, performance, staff, goals, and salaries. · `src/livestreamanalytics/livestreamanalytics.service.ts`
- [Notifications gateway](https://github.com/dncmaduro/candy-cal-be/blob/main/src/notifications/notifications.gateway.ts): WebSocket gateway · Persists notifications and delivers them in realtime. · `src/notifications/notifications.gateway.ts`
- [Meta webhook API](https://github.com/dncmaduro/candy-cal-be/blob/main/src/meta/meta-webhook.controller.ts): webhook controller · Provides Meta REST and webhook entry points. · `src/meta/meta-webhook.controller.ts`
- [AI assistant](https://github.com/dncmaduro/candy-cal-be/blob/main/src/ai/ai.service.ts): AI service · Maintains conversations, feedback, usage, and internal-data context. · `src/ai/ai.service.ts`

### Other components

- [MongoDB](https://github.com/dncmaduro/candy-cal-be/blob/main/src/database/database.module.ts): system of record · Mongoose stores operational, analytics, AI, and audit records. · `src/database/database.module.ts`
- [Global error handling](https://github.com/dncmaduro/candy-cal-be/blob/main/src/common/filters/all-exceptions.filter.ts): exception filter · `src/common/filters/all-exceptions.filter.ts`

## Connections

- Nest bootstrap → Application module: boots
- Nest bootstrap → Swagger / OpenAPI: publishes
- Application module → REST controllers: registers
- Application module → Global error handling: applies
- REST controllers → JWT authentication: authenticates with
- JWT authentication → Role authorization: enables
- REST controllers → Income & fulfillment: operates
- REST controllers → Sales leads: operates
- REST controllers → Sales orders: operates
- REST controllers → Shopee analytics: queries
- Income & fulfillment → Packing rules: derives assignments from
- Income & fulfillment → Storage movements: records movements
- Income & fulfillment → MongoDB: imports and persists
- Sales leads → MongoDB: persists
- Sales orders → MongoDB: persists
- Sales-lead migration → MongoDB: updates legacy data
- Shopee analytics → MongoDB: aggregates
- Livestream analytics → MongoDB: aggregates
- Notifications gateway → MongoDB: persists
- Meta webhook API → Notifications gateway: triggers
- AI assistant → MongoDB: stores context and usage
- Docker & CI delivery → Nest bootstrap: deploys