dncmaduro/candy-cal-be

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.