# Onboarding — Application Status Reference

This document lists every **`overallStatus`** value used in dealer onboarding: what the UI shows, how statuses map to pipeline progress, and the typical lifecycle order from application submission through inauguration and onboarding.

**Source of truth (code):**

| Area | Path |
|------|------|
| Status constants | `backend/src/common/config/constants.ts` → `APPLICATION_STATUS` |
| Status → pipeline stage | `backend/src/common/utils/progress.ts` → `PIPELINE_STAGE_LABEL_BY_OVERALL_STATUS` |
| Progress milestones | `backend/src/common/utils/progress.ts` → `ONBOARDING_STAGES` |
| Status → DB `currentStage` | `backend/src/common/config/constants.ts` → `OVERALL_STATUS_TO_DB_CURRENT_STAGE` |
| UI type / badges | `frontend/src/lib/mock-data.ts` → `ApplicationStatus` |

---

## Three layers (do not confuse)

| Layer | Field / table | Shown in UI as | Purpose |
|-------|----------------|----------------|---------|
| **Overall status** | `Application.overallStatus` | Status badge on lists, cards, Application Details sidebar | Fine-grained lifecycle label (this document) |
| **Current stage** | `Application.currentStage` | Sometimes in filters / audit; coarser enum | Role-based workflow stage (`DD`, `FDD`, `LOI`, `LOA`, `EOR`, etc.) |
| **Progress milestones** | `ApplicationProgress.stageName` | Application Details → **Progress** tab (“Application Journey”) | Ordered pipeline steps (`Submitted`, `Questionnaire`, `Shortlist`, …) |

`overallStatus` is what users most often see as **Status**. Progress tab labels can differ (e.g. badge **Level 1 Interview Pending** maps to milestone **1st Level Interview**).

---

## Happy path — sequential `overallStatus` (submission → inauguration)

Typical forward flow. Not every application visits every row (policy gates, parallel work, and admin shortcuts can skip or reorder steps).

| # | `overallStatus` (UI label) | Phase | Notes |
|---|---------------------------|-------|-------|
| 1 | **Submitted** | Intake | Default when no active opportunity; non-opportunity applications stay here until questionnaire is sent |
| 2 | **Questionnaire Pending** | Questionnaire | Default when application is tied to an active opportunity |
| 3 | **Questionnaire Completed** | Questionnaire | Set when prospect submits public questionnaire |
| 4 | **Shortlisted** | Evaluation | DD shortlists; interviews can be scheduled |
| 5 | **Level 1 Interview Pending** | Interview L1 | Set when Level 1 interview is scheduled |
| 6 | **Level 1 Approved** | Interview L1 | Level 1 panel decision (policy-managed) |
| 7 | **Level 2 Interview Pending** | Interview L2 | Level 2 scheduled |
| 8 | **Level 2 Approved** | Interview L2 | Level 2 passed |
| 9 | **Level 3 Interview Pending** | Interview L3 | Level 3 scheduled |
| 10 | **Level 3 Approved** | Interview L3 | Optional; admin quick-approve path before FDD |
| 11 | **FDD Verification** | FDD | Financial due diligence; interview L3 approval may jump here directly |
| 12 | **LOI In Progress** | LOI | LOI approval workflow (DD Head / NBH policy) |
| 13 | **Payment Pending** | Security deposit | Finance verification of security deposit |
| 14 | **Security Deposit** | Security deposit | LOI approved; deposit verified; gate before LOI issue (`SECURITY_DETAILS` constant) |
| 15 | **LOI Issued** | LOI | Letter of Intent issued to applicant |
| 16 | **Dealer Code Generation** | SAP / codes | Dealer codes generated (DD Admin trigger) |
| 17 | **Architecture Team Assigned** | Architecture (parallel) | Architecture team assigned |
| 18 | **Architecture Document Upload** | Architecture (parallel) | Site / blueprint uploads |
| 19 | **Architecture Team Completion** | Architecture (parallel) | Architecture track complete |
| 20 | **LOA Pending** | LOA | LOA approval; may require First Fill verified by Finance |
| 21 | **LOA Issued** | LOA | LOA document generated (policy path) |
| 22 | **EOR In Progress** | EOR | EOR checklist started |
| 23 | **EOR Complete** | EOR | All EOR items compliant |
| 24 | **Inauguration** | Go-live | EOR audit submitted as Completed; dealership ready for inauguration |
| 25 | **Approved** | Go-live | Treated like inauguration in progress / progress sync |
| 26 | **Onboarded** | Active dealer | Final onboarding after inauguration action; dealer profile active |

**Short path (badge only):**  
`Submitted` → `Questionnaire Pending` → `Questionnaire Completed` → `Shortlisted` → … → `Inauguration` → `Onboarded`

---

## Statutory sub-statuses (parallel with architecture)

After **Dealer Code Generation**, statutory compliance can surface granular statuses (all map to pipeline **Statutory Work**):

| `overallStatus` | Meaning |
|-----------------|---------|
| **Statutory GST** | GST certificate step |
| **Statutory PAN** | PAN step |
| **Statutory Nodal** | Nodal agreement |
| **Statutory Check** | Cancelled check / bank proof |
| **Statutory Partnership** | Partnership / LLP / MOA documents |
| **Statutory Firm Reg** | Firm registration |
| **Statutory Rental** | Property / rental agreement |
| **Statutory Virtual Code** | Virtual code |
| **Statutory Domain** | Domain setup |
| **Statutory MSD** | MSD configuration |
| **Statutory LOI Ack** | LOI acknowledgement copy |
| **Statutory Work** | Generic statutory milestone |

Generic architecture labels: **Architecture Work**, plus team assignment statuses in the happy-path table above.

---

## Alternate / branch statuses

| `overallStatus` | When used |
|-----------------|-----------|
| **Pending** | Legacy / initial; progress sync maps to **Submitted** |
| **In Review** | Legacy; maps to pipeline **Shortlist** |
| **Level 2 Recommended** | Alternate Level 2 outcome (still 2nd Level Interview pipeline) |
| **Returned to FDD** | Application sent back to FDD from a later stage |
| **Security Details** | **Deprecated** DB label; same stage as **Security Deposit** — migrate to **Security Deposit** |

Frontend also styles optional labels that may appear from older APIs or composite UI (see `frontend/src/lib/mock-data.ts`): e.g. **LOI Approved**, **Security Deposit In Progress**, **Architecture Work In Progress**, **Dealer Code Generated**, etc.

---

## Terminal (end-state) statuses

| `overallStatus` | Outcome |
|-----------------|---------|
| **Rejected** | Application rejected (any stage) |
| **Disqualified** | Disqualified |
| **LOI Rejected** | LOI approval rejected |
| **LOA Rejected** | LOA approval rejected |

---

## Progress tab milestones (`ONBOARDING_STAGES`)

Shown on Application Details → **Progress** (not always identical to the status badge text):

| Order | Milestone name | Parallel |
|------:|----------------|----------|
| 1 | Submitted | |
| 2 | Questionnaire | |
| 3 | Shortlist | |
| 4 | 1st Level Interview | |
| 5 | 2nd Level Interview | |
| 6 | 3rd Level Interview | |
| 7 | FDD | |
| 8 | LOI Approval | |
| 9 | Security Deposit | |
| 10 | LOI Issue | |
| 11 | Dealer Code Generation | |
| 12 | Architecture Work | Yes (order 12) |
| 12 | Statutory Work | Yes (order 12) |
| 13 | LOA | |
| 14 | EOR Complete | |
| 15 | Inauguration | |
| 16 | Onboarded | |

UI journey definition: `frontend/src/features/onboarding/hooks/useApplicationDetailsStageData.ts` (`processStages`).

---

## Mapping: `overallStatus` → progress milestone

Used by `syncApplicationProgress()` and SLA stage naming:

| `overallStatus` | Pipeline milestone (`ApplicationProgress.stageName`) |
|-----------------|-----------------------------------------------------|
| Submitted | Submitted |
| Questionnaire Pending / Completed | Questionnaire |
| Shortlisted, In Review | Shortlist |
| Level 1 Interview Pending / Approved | 1st Level Interview |
| Level 2 Interview Pending / Approved / Recommended | 2nd Level Interview |
| Level 3 Interview Pending / Approved | 3rd Level Interview |
| FDD Verification, Returned to FDD | FDD |
| LOI In Progress | LOI Approval |
| Payment Pending, Security Deposit, Security Details | Security Deposit |
| LOI Issued, Statutory LOI Ack, LOI Rejected | LOI Issue |
| Dealer Code Generation | Dealer Code Generation |
| Architecture Team * / Architecture Work | Architecture Work |
| Statutory * / Statutory Work | Statutory Work |
| LOA Pending / LOA Issued / LOA Rejected | LOA |
| EOR In Progress / EOR Complete | EOR Complete |
| Inauguration / Approved | Inauguration |
| Onboarded | Onboarded |
| Rejected / Disqualified | Rejected |

Full map: `PIPELINE_STAGE_LABEL_BY_OVERALL_STATUS` in `progress.ts`.

---

## Mapping: `overallStatus` → `currentStage` (DB enum)

Coarser internal stage on `Application.currentStage` (see `OVERALL_STATUS_TO_DB_CURRENT_STAGE`):

| `currentStage` | Example `overallStatus` values |
|----------------|--------------------------------|
| `DD` | Submitted, Questionnaire *, Shortlisted, Level * Pending |
| `Level 1 Approved` | Level 1 Approved |
| `Level 2 Approved` | Level 2 Approved |
| `Level 2 Recommended` | Level 2 Recommended |
| `Level 3 Approved` | Level 3 Approved |
| `FDD` | FDD Verification, Returned to FDD |
| `LOI` | LOI In Progress, Security Deposit, Payment Pending, LOI Issued, Dealer Code Generation, Statutory LOI Ack |
| `Architecture Work` | Architecture Team *, Architecture Work |
| `Statutory Work` | Statutory * |
| `LOA` | LOA Pending, LOA Issued, LOA Rejected |
| `EOR` | EOR In Progress, EOR Complete |
| `Approved` | Inauguration, Onboarded, Approved |
| `Rejected` | Rejected, Disqualified, LOI Rejected |

---

## Key transitions (implementation notes)

| Trigger | Typical transition |
|---------|-------------------|
| Application create (opportunity) | → **Questionnaire Pending** |
| Application create (no opportunity) | → **Submitted** |
| Public questionnaire submit | → **Questionnaire Completed** |
| Bulk / single shortlist | → **Shortlisted** |
| Schedule interview level N | → **Level N Interview Pending** |
| Interview L1/L2 approve (policy) | → **Level 1 Approved** / **Level 2 Approved** |
| Interview L3 approve (policy) | → **FDD Verification** (may skip **Level 3 Approved**) |
| FDD complete / admin approve | → **LOI In Progress** |
| LOI policy + deposit verified | → **Security Deposit** |
| LOI issued | → **LOI Issued** → **Dealer Code Generation** |
| Dealer codes created (integrity service) | → **LOA Pending** (architecture/statutory may continue in parallel) |
| LOA policy met | → **EOR In Progress** (or **LOA Issued** on policy path) |
| EOR checklist Completed | → **Inauguration** |
| Dealer onboard action | → **Onboarded** (requires **Inauguration** / **Approved** and EOR complete) |

Admin sequential override (frontend): `useApplicationDetailsAdminActions.ts` — manual **Approve** button steps through statuses when policy does not apply.

---

## UI surfaces by page

| Page / component | Statuses typically shown |
|------------------|-------------------------|
| **Opportunity Requests** | Questionnaire Pending, Questionnaire Completed, Shortlisted |
| **All Applications (DD)** | Early statuses (Submitted, Questionnaire *, Shortlisted, interview pending) |
| **Applications / cards** | All `overallStatus` values from API |
| **Application Details** | Current `overallStatus` badge + Progress tab milestones |
| **Non-Opportunities** | **Submitted** (not yet in opportunity flow) |

---

## Related documentation

- Module overview: `modular_wise/01_Dealer_Onboarding.md`
- SLA vs applicant reminders: `sla/ONBOARDING_SLA_RULES.md`
- Data flows summary: `Detailed_Module_Data_Flows.md`

---

*Last aligned with codebase: `APPLICATION_STATUS` and `progress.ts` as of document creation.*
