Project Structure

"Where does X live?" This page maps every top-level folder to its responsibility so you can navigate both repos fast. Deeper architectural reasoning is in Folder Structure.

uengage-crm (monolith)

uengage-crm/
├── index.js                  # ⭐ app bootstrap: middleware → crons → routes → sockets → DB
├── config.js                 # env exporter (reads .env.dev / .env.prod)
├── crm_ecosystem.config.js   # PM2 process config (dev/prod)
├── socket.js                 # Socket.IO init (WhatsApp live chat)
├── agentSocketUtils.js       # socket ↔ MongoDB bridge
├── newrelic.js               # APM config (currently inactive)
│
├── config/                   # DB connection setup
│   ├── mysql.js              #   MySQL params
│   ├── mysqlConnection.js    #   single connection (transactions)
│   └── mysqlPool.js          #   ⭐ webPool + jobsPool
│
├── utilities/                # cross-cutting infra
│   ├── mongodb.js            #   ⭐ Mongo client/mongoose (DB 'uengage')
│   ├── redis.js              #   Redis (ioredis)
│   ├── poolMonitor.js        #   pool_stats logging
│   ├── constants.js          #   business constants
│   └── loggerUtils.js
│
├── logger/                   # Winston + trace-id logger-service
│
├── middlewares/              # ⭐ 6 auth layers + requestLogger (see Security)
│
├── routes/                   # HTTP route definitions
│   ├── crm.js                #   /crm_api (legacy, 200+ endpoints)
│   ├── crmv2.js              #   /crm_api/v2
│   ├── injestion.js          #   order ingestion + loyalty POS ops
│   ├── stats.js              #   /stats (metrics dashboard)
│   ├── prismIntegration.js   #   /integration/v1 (POS/3rd-party)
│   ├── posistLoyaltyIntegration.js  # /posist/v1
│   └── prism_routes/         #   campaign_tag, loyalty_rewards, digital_bill,
│                             #   whatsapp_login, fraud_rules, order_360, qr_code
│
├── controllers/              # ⭐ 57 files — request handlers / business logic
├── commonFunctions/          # ⭐ 60 shared helpers (queues, senders, parsers)
├── processLibrary/           # ⭐ 18 aggregation / MIS / campaign-processing engines
├── crons/                    # ⭐ 91 scheduled jobs (+ subfolders)
│   ├── autoCampaignRoiCrons/
│   ├── rewardsCrons/
│   └── updationCrons/
├── models/                   # ~29 Mongoose schemas
├── constants/                # rfmSegments.js (RFM grid)
├── customerDetails/          # customer-detail helpers
├── CampaignRefunds/          # campaign refund logic
├── scripts/                  # one-off maintenance scripts
├── templates/                # message/email templates
│
├── .env.dev                  # ⚠️ committed dev secrets
└── .env.prod.example         # prod env template

The 5 folders you'll live in

Folder	What it holds	Mental model
controllers/	One file per feature area; exports functions bound to routes	"the verbs the API can do"
commonFunctions/	Reusable helpers: message senders, queue producers, parsers, wallet/points flows	"the shared toolbox"
processLibrary/	Heavy background engines: aggregations, MIS reports, campaign processing	"the batch brains"
crons/	Scheduled entry points that call into the above	"the alarm clocks"
models/	Mongoose schemas (MongoDB). MySQL has no ORM — raw SQL in controllers/helpers	"the Mongo shapes"

⚠️ There is no services/ layer. Business logic is split across controllers + commonFunctions + processLibrary, often with logic inside controllers. This is the biggest structural characteristic (and debt) of the codebase — see Module Architecture.

prism-services (serverless)

prism-services/
├── serverless-orders.yml     # 'prism' service: orders-api + orders-consumer
├── serverless-whatsapp.yml   # 'prism-whatsapp': api-send/receipts + consumers
├── package.json              # kafkajs, mongodb, moment
├── src/
│   ├── services/
│   │   ├── kafka.js          # KafkaJS producer/consumer setup
│   │   └── mongodb.js        # Mongo connection (shared 'uengage' DB)
│   ├── utils/
│   │   └── extractMessagesFromEvent.js   # decode MSK event batch
│   ├── orders/handlers/
│   │   ├── api/orders.js             # HTTP → Kafka producer
│   │   └── consumers/orders.js       # Kafka → crm_queue
│   └── whatsapp/handlers/
│       ├── api/send.js               # HTTP → whatsapp-messages
│       ├── api/receipts.js           # HTTP → whatsapp-receipts
│       └── consumers/{send,receipts}.js  # (currently log-only)
└── .github/                  # CI: serverless deploy on main

Where common tasks live (quick index)

I want to…	Look in
Add/modify an API endpoint	routes/*.js + the matching controllers/*.js
Change how an order is parsed	commonFunctions/parseOrderData.js, processCommonIngestion.js, ingestion controllers
Touch loyalty points	loyaltyController.js, commonFunctions/handleWalletPointsFlow.js, rewardHelper.js, crons/*Points*.js
Change a dashboard number	dashboardControllerNew.js, processLibrary/aggregationProcess.js, metricsController.js
Change campaign sending	campaignController*.js, commonFunctions/*CampaignQueue*.js, crons/send*Cron.js
Add/adjust a cron	crons/ + register it in index.js
Add a MongoDB collection	models/ (Mongoose)
Change ingestion at the edge	prism-services/src/orders/handlers/

Related

• Folder Structure (architecture rationale)
• Module Architecture