Module Architecture¶

How the 57 controllers organize into business modules, where implementations duplicate, where code is dead, and — critically — where the PM's Excel and the actual code disagree. This is the bridge between Product modules and 03-Modules/.

1. Controller → Module map (condensed)¶

Module	Primary controllers	Central hub
Order Ingestion	`injestionController`, `commonOrderIngestion`, `petpoojaOrderIngestion`, `ristaOrderIngestion`, `uengageOrderIngestion`, `shoutloOrderIngestion`, `posistCron`, `customerInjestionController`, `fcmInjestionController`, `appCustomerController`, `PosDIYController`, `prismIntegration`	`injestionController` (HTTP) + per-POS crons
Customer / CRM	`customerController` ⭐, `customerInsightsController`, `rfmController`, `checkInController`	`customerController` (40+ fns)
Dashboard & Analytics	`dashboardControllerNew` ⭐, `dashboardController` (legacy), `aggregationController`, `metricsController`, `order360Controller`, `invoiceInsightsController`	dual dashboards
Campaigns & Journeys	`campaignController` ⭐ (50+ fns), `campaignControllerDynamic`, `automatedCampaignController`, `coldCampaignController`, `processCampaignController`, `campaignTagController`, `campaignControllerMailHelper`	`campaignController`
WhatsApp	`gupshupOnboardingController`, `metaTSP`, `whatsappCatalogueController`, `whatsappLoginControler`	Gupshup + Meta
Loyalty & Rewards	`loyaltyController` ⭐, `rewardsController`, `walletController`, `posistLoyaltyIntegration`	`loyaltyController`
Feedback & NPS	`feedbackController`, `npsControllers`, `ratingController`, `lowRatingTrigger`	—
Digital Bills	`digitalBillController`, `invoiceInsightsController`	—
Fraud	`fraudRulesController`	—
Admin / Business / Misc	`adminController`, `businessController`, `leadController`, `helpDeskController`, `qrCodeController`, `gamingController`, `salonController`, `aiController`	—

⭐ = "monolithic hub" — a very large controller that concentrates its domain's logic. These are the highest-risk files to edit and the most important to understand.

2. The three "monolithic hubs"¶

Hub	~size	Why it's dangerous	Read first
`campaignController.js`	50+ functions	SMS+FCM+Email+WhatsApp + segmentation + analytics all in one file	Campaigns
`customerController.js`	40+ functions	CRUD + segmentation + RFM + loyalty + chat routing	Customer-CRM
`dashboardController.js`	50+ functions	legacy dashboard, being replaced	Dashboard

3. Duplicate / overlapping implementations ♻️¶

Before editing any of these, confirm which one the route actually uses.

Concern	Implementations	Status / guidance
Dashboard	`dashboardController.js` (legacy) ↔ `dashboardControllerNew.js` (modern: Redis cache, Socket.io, checklist/KPIs)	New is the target; legacy still serves many endpoints
Campaigns	`campaignController` (traditional) ↔ `campaignControllerDynamic` (custom-code/animated) ↔ `automatedCampaignController` (journeys)	3 separate pipelines — pick by campaign type
Auto-campaign queue	`commonFunctions/automatedCampaignQueue.js` ↔ `automatedCampaignQueueNew.js`	`New` is current; verify before changing
Route versions	`routes/crm.js` (`/crm_api`) ↔ `routes/crmv2.js` (`/crm_api/v2`)	v2 is the migration path
Ingestion	Lambda `orders-api` ↔ monolith `injestionController`	both write `crm_queue` — duplication risk
Order ingestion crons	5 near-identical per-POS crons	shared error/email logic duplicated
Loyalty points store	MongoDB `wallet_*` ↔ MySQL `crm_points_allocation_queue`	non-atomic dual write ⚠️

Full remediation notes: Technical Debt.

4. Dead / legacy code ⚰️¶

File	Verdict
`testController.js`	debug endpoints only
`oldCustomerCron.js`	replaced by `customerInjestionController`
`oldFcmCron.js`	replaced by `fcmInjestionController`
`parseFcmTokenController.js`	legacy child-process token parser
`uengageloyaltyController.js`	empty placeholder — never implemented
commented crons in `index.js` (lines ~69, 77, 105, 118, 125+)	disabled
commented socket handlers (`socket.js` disconnect/sessionLogout)	disabled

Candidates for archival — but verify they're truly unreferenced before deleting. Do not remove without a grep for imports/route registration.

5. Excel ↔ Code validation (the critical part)¶

Per the user's validation rules — where the PM spec and the code diverge:

📄 Excel-only / weak-in-code¶

Product feature (Excel)	Code reality
Membership Module — rich 8-tab plan builder, Draft→Active→Paused→Expired lifecycle, App/Web/POS purchase	No dedicated membership controller. Membership appears embedded in loyalty (`wallet_rules`) and `salon_services`/`salonController.membershipReport`. The full builder is likely frontend (Next.js) + minimal backend, or not yet built server-side. Flag as partial. See Membership.
Tag Customers (Segment action)	Excel marks "Not Live"; confirm in code
Create Offer/Promo from segment ("KILLER FEATURE")	Excel "Not Live"; promo engine lives in MySQL `addo_promo_code_engine` (see Database)
Send Campaign from segmentation tab	Roadmap B1.2 "Planned" — not yet wired

💻 Code-only (in code, not emphasized in Excel)¶

Code feature	Notes
`gamingController` — gamification/contests	not in the feature Excel sheets
`salonController` — salon vertical (services, GST, membership reports)	Prism also serves salons, not just F&B
`aiController` — AI insights/prompts with wallet deduction	early AI feature
`helpDeskController` — WhatsApp live chat + agent flows + Socket.io	operational, lightly documented
`leadController` — sales CRM (lead→contact)	internal sales pipeline
`qrCodeController` — QR generation/scan attribution	supports QR/Attribution engine
`PosDIYController` — self-serve POS integration	onboarding

✅ Excel + Code aligned (strong)¶

Order ingestion, Customer 360/CRM, Campaigns (WhatsApp/SMS/Push), Automated Journeys, Loyalty (points/tiers/referral/fraud), Dashboard analytics, Digital Bills, Feedback/NPS.

6. Module dependency graph¶

flowchart LR
    ING[Order Ingestion] --> CRM[Customer/CRM]
    CRM --> RFM[Customer Intelligence/RFM]
    RFM --> CAMP[Campaigns]
    RFM --> JRNY[Automated Journeys]
    CAMP --> WA[WhatsApp]
    CAMP --> SP[SMS/Push]
    JRNY --> WA
    JRNY --> SP
    CRM --> LOY[Loyalty]
    LOY --> WAL[Wallet]
    LOY --> REF[Referral]
    LOY --> MEM[Membership]
    LOY --> FRAUD[Fraud]
    ING --> BILL[Digital Bills]
    BILL --> FB[Feedback/NPS]
    CAMP --> DASH[Dashboard]
    LOY --> DASH
    FB --> DASH
    ING --> DASH
    ADMIN[Admin/Business] -.scopes.-> ALL[(all modules)]

Each arrow is a real runtime dependency you'll see when tracing code. Use this to predict blast radius before a change.

7. How to read a module doc¶

Every folder in 03-Modules/ follows the same 15-section template and ends with assessments + assignments. Start with the module's README.md, then follow cross-links into Database, Queues, and API for depth.

Folder Structure · High-Level Architecture · Technical Debt