9.9 KiB
9.9 KiB
Exhaustive Module Data Flow & Schema Analysis
This document provides a 100% comprehensive breakdown of the Dealer Onboarding & Lifecycle Management system. It includes every enum, every database key, and every workflow transition to support a thorough gap analysis.
1. Global Constants & Enums (constants.ts)
These constants are the primary drivers of application logic and stage-gate controls.
👥 User Roles (ROLES)
| Key | Value | Role Description |
|---|---|---|
DD |
DD |
Dealer Development Executive (Field) |
DD_ZM |
DD-ZM |
DD Zone Manager (Zone) |
RBM |
RBM |
Regional Business Manager |
ZBH |
ZBH |
Zone Business Head |
DD_LEAD |
DD Lead |
Lead for Dealer Development |
DD_HEAD |
DD Head |
Head of Dealer Development |
NBH |
NBH |
National Business Head |
LEGAL_ADMIN |
Legal Admin |
Legal Dept (Verification/Letters) |
SUPER_ADMIN |
Super Admin |
System Administrator (Bypass) |
FINANCE |
Finance |
Finance Dept (Payments/Clearance) |
DEALER |
Dealer |
The Business Partner / Applicant |
ARCHITECTURE |
ARCHITECTURE |
Site Layout & Design Team |
FDD |
FDD |
Field Due Diligence Agency |
CCO |
CCO |
Chief Commercial Officer |
CEO |
CEO |
Chief Executive Officer |
🛠️ Application Lifecycle (APPLICATION_STATUS)
| Status | Functional Meaning |
|---|---|
Pending |
Initial lead entry |
Submitted |
Form submitted by Prospect |
Questionnaire Pending |
Sent to prospect for survey |
Shortlisted |
DD Lead approval for evaluation |
FDD Verification |
Agency conducting site/back background check |
LOI Issued |
Intent letter issued (Commercial check complete) |
EOR In Progress |
Site construction/readiness audit |
LOA Issued |
Final Appointment Letter issued |
Onboarded |
System provisioning complete (Active Dealer) |
📦 Request Types (REQUEST_TYPES)
application: New Onboardingresignation: Voluntary Exitconstitutional: Legal entity changerelocation: Site movement
2. Onboarding Module: Schema & Transitions
🔑 Primary Model: Application (applications table)
| Field | Type | Description |
|---|---|---|
id |
UUID | Internal Database PK |
applicationId |
String | Public ID (e.g., APP-2024-001) |
businessType |
Enum | Dealership or Studio |
applicantName |
String | Legal name of primary applicant |
experienceYears |
Integer | Industry experience |
investmentCapacity |
String | Range of funds available |
currentStage |
Enum | Current workflow stage (e.g., ZBH) |
overallStatus |
Enum | High-level status (e.g., LOI Issued) |
score |
Decimal | Aggregate Questionnaire/Interview score |
isShortlisted |
Boolean | Gate for proceeding to interviews |
documents |
JSONB | Active document snapshot {type, url, status} |
timeline |
JSONB | Sequential history of actions |
🔄 Sub-Entities captured during Onboarding
| Model | Key Fields Captured |
|---|---|
| Interview | level (1, 2, 3), scheduleDate, type (Virtual/Physical) |
| FDD Report | findings (Text), recommendation (Recommended/Not), verifiedAt |
| Security Deposit | amount, paymentDate, transactionRef, status |
| EOR Checklist | auditorId, auditDate, items (Compliant/Non-Compliant) |
3. Post-Onboarding Modules: Detailed Schema
🏗️ Relocation Module (relocation_requests table)
| Field | Type | Description |
|---|---|---|
requestId |
String | Unique Relocation ID |
outletId |
UUID | FK to the specific outlet being moved |
relocationType |
Enum | Within City, Intercity, Interstate |
newAddress |
Text | Destination street address |
newCity/State |
String | Destination geo-attributes |
reason |
Text | Business justification for relocation |
currentStage |
Enum | ASM Review -> NBH -> Legal |
⚖️ Constitutional Change (constitutional_changes table)
| Field | Type | Description |
|---|---|---|
changeType |
Enum | Ownership Transfer, Partnership Change, etc. |
description |
Text | Summary of legal restructuring |
oldValue |
String | Current constitution (Snapshot) |
newValue |
String | Proposed constitution |
🚪 Offboarding (Termination & Resignation)
Both flows merge into the Full & Final (F&F) settlement.
| Module | Primary Keys | Clearance Tracks |
|---|---|---|
| Resignation | resignationType, lastOperationalDate, reason |
Spares, Service, Accounts, Logistics |
| Termination | category (Non-performance/Compliance), proposedLwd |
Show Cause Notice, Personal Hearing Record |
| FnF Settlement | totalReceivables, totalPayables, netAmount |
Line items for specific credit/debit memos |
4. Document Matrix (Gap Analysis Reference)
Every request type captures a specific subset of DOCUMENT_TYPES. Missing a document in a stage is a common "Gap".
| Document Type | Captured In | Mandatory For |
|---|---|---|
GST Certificate |
Application / Const. Change | All entities |
Partnership Deed |
Application / Const. Change | Partnership firms |
New Lease Agreement |
Relocation | Site movement |
NOC Landlord |
Relocation | Existing site exit |
SCN Response |
Termination | Show Cause phase |
Hearing Record |
Termination | Personal Hearing phase |
Exit Feedback |
Resignation | Dealer exit |
5. Audit & Traceability Logic
Every action across all modules is tracked via these shared models:
AuditLog
userId: Who did it.action:CREATED,UPDATED,APPROVED, etc.oldData/newData: JSON snapshots of the record BEFORE and AFTER the change.
Worknote
requestId: Link to Application/Relocation/etc.noteText: Threaded comments between field and HO teams.noteType:general,system, orprivate.
Document Types (Exhaustive List)
| Enum Key | Display Name |
|---|---|
GST_CERTIFICATE |
GST Certificate |
PAN_CARD |
PAN Card |
AADHAAR |
Aadhaar |
PARTNERSHIP_DEED |
Partnership Deed |
LLP_AGREEMENT |
LLP Agreement |
INCORPORATION_CERTIFICATE |
Certificate of Incorporation |
MOA |
MOA |
AOA |
AOA |
BOARD_RESOLUTION |
Board Resolution |
PROPERTY_DOCUMENTS |
Property Documents |
BANK_STATEMENT |
Bank Statement |
NODAL_AGREEMENT |
Nodal Agreement |
CANCELLED_CHECK |
Cancelled Check |
FIRM_REGISTRATION |
Firm Registration |
RENTAL_AGREEMENT |
Rental Agreement |
VIRTUAL_CODE |
Virtual Code Confirmation |
DOMAIN_ID |
Domain ID Setup |
MSD_CONFIG |
MSD Configuration |
LOI_ACK |
LOI Acknowledgement |
FDD_REPORT |
FDD Final Audit Report |
KT_MATRIX |
Kepner Tregoe Matrix |
INTERVIEW_EVALUATION |
Interview Evaluation Sheet |
SITE_READINESS |
Site Readiness Report |
CIBIL_REPORT |
CIBIL Report |
LOA_ACCEPTANCE |
LOA Acceptance Copy |
ARCHITECTURE_BLUEPRINT |
Architecture Blueprint |
SITE_PLAN |
Site Plan |
STATUTORY_AUDIT |
Statutory Approval Certificate |
BANK_GUARANTEE |
Bank Guarantee Document |
RELOCATION_* |
10+ Relocation specific docs (Photos, NOC, Fire Safety, etc.) |
Audit Actions (System Traceability)
CREATED, UPDATED, APPROVED, REJECTED, DELETED, LOGIN, LOGOUT, STAGE_CHANGED, SHORTLISTED, DISQUALIFIED, QUESTIONNAIRE_SUBMITTED, DOCUMENT_UPLOADED, DOCUMENT_VERIFIED, INTERVIEW_SCHEDULED, LOI_REQUESTED, LOA_GENERATED, EOR_AUDIT_SUBMITTED, PAYMENT_UPDATED, RESIGNATION_SUBMITTED.
9. Advanced Approval Policies (StageApprovalPolicy)
To enforce strict governance, certain stages (Interviews, LOI, LOA) require multiple independent approvals.
| Mode | Rule | Evaluation Logic |
|---|---|---|
MIN_N |
Minimum Count | Requires at least N unique users to approve, regardless of role. |
ROLE_MANDATORY |
Specific Roles | Requires unique approvals from EACH role listed in requiredRoles. |
ALL |
Full Concensus | Every assigned RequestParticipant for that stage must approve. |
Evaluation Engine: WorkflowService.evaluateStagePolicy()
- Super Admin Bypass: A Super Admin approval automatically satisfies any policy.
- Unique Actor Check: Prevents a single user with multiple roles from satisfying multiple requirements alone.
10. Auto-Assignment & Territory Mapping
The system automatically assigns evaluators based on the District -> Region -> Zone hierarchy linked to each application.
🗺️ Evaluator Mapping Matrix
| Stage / Level | Role Sources | Logic / Hierarchy |
|---|---|---|
| Level 1 Interview | DD-ZM, RBM |
Primary District Manager (zmId) + Regional Manager (rbmId). |
| Level 2 Interview | ZBH, DD Lead |
Zone Business Head (zbhId) + DD Lead assigned to that Zone. |
| Level 3 Interview | NBH, DD Head |
National Level Roles (Active status check). |
| LOI Approval | Finance, Head, NBH |
National Level (Requires 3 unique approvals). |
| LOA Approval | DD Head, NBH |
National Level (Requires 2 unique approvals). |
Metadata capture: Assignments are stored in RequestParticipant with joinedMethod: 'auto' and metadata.autoMapped: true.
11. System Fail-Safe (Retriggering)
If any territory mapping is missing (e.g., a District has no assigned ASM) or if a manager changes mid-flow, the system provides a Retrigger capability.
🔄 The Retrigger Process
- API Endpoint:
POST /onboarding/:id/retrigger-evaluators - Step A (Cleanup): Deletes all participants where
metadata.autoMapped = true. This preserves manual notes and manually added participants. - Step B (Hierarchy Sync): Invokes
syncLocationManagers()to refresh theDistricttable with current managers fromUserRole. - Step C (Re-assignment): Re-runs the
assignStageEvaluatorslogic to map the correct current users to all 3 interview levels and approval stages.
Generated: April 2026 | Comprehensive System Data Flow Analysis v2.1 (Advanced Features)