Status Lifecycles

This page is the authoritative reference for every status value in the system and the transitions the backend permits between them. Status values are transcribed verbatim from vruksha-backend/src/shared/enums/status.enum.ts. Transition arrows are taken from the module transition maps (where one exists in code) or presented conceptually (where the module does not enforce a strict map).

In each diagram, an arrow means the backend allows that transition. A status with no outgoing arrows is terminal — once reached, no further status change is accepted.

---

Stock (StockStatus — 11 statuses)

Source: STOCK_STATUS_TRANSITIONS in the stock-management module — strictly enforced.

Value	Meaning
WISHLIST	Land/asset identified as a target; no commercial commitment yet.
IN_NEGOTIATION	Active negotiation with the seller is underway.
UNDER_PO	A purchase order / agreement to purchase is in place.
ADVANCED	An advance payment has been made against the purchase.
REGISTERED	The purchase is legally registered; the asset is owned.
ALLOCATED	The registered stock has been allocated to a project.
ON_HOLD	Temporarily paused (legal, due-diligence, or internal hold).
CANCELLED	The acquisition was abandoned; the record is parked, not deleted.
PARTIALLY_SOLD	Part of the allocated stock area has been sold.
COMPLETELY_SOLD	The entire allocated stock area has been sold.
SPLIT	The stock was split into child stocks; the parent is locked. Terminal.

Key rules from the transition map:

• SPLIT is never a manual next-state. The split operation (POST /stocks/:id/split) writes SPLIT directly after creating the child stocks. Once split, the parent is terminal.
• ON_HOLD and CANCELLED are wide "escape hatches": from either, the stock can be returned to most active states. CANCELLED is recoverable (it is not terminal).
• COMPLETELY_SOLD can only move to CANCELLED.

See also: Stock Allocations and the allocation workflow, which has its own status set (DRAFT → SUBMITTED → APPROVED → POSTED, with REJECTED/CANCELLED).

---

Unit (UnitStatus — 8 statuses)

Source: status.enum.ts. Unit status is driven by sales activity (quotation holds, sales orders) rather than a single freestanding transition map, so the diagram below is conceptual — it reflects the lifecycle the sales and unit modules produce in practice.

Value	Meaning	Customer-facing
DRAFT	Being configured; not released for sale.	Hidden
AVAILABLE	Open for booking.	Available
BLOCKED	Temporarily reserved / held (e.g. by a quotation hold).	Unavailable
BOOKED	Booking confirmed via an active Sales Order.	Unavailable
ADVANCED	Advance received against the booking.	Unavailable
REGISTERED	Sold and registered.	Unavailable
CANCELLED	Unit cancelled / withdrawn.	Hidden
FROZEN	Frozen for legal, internal, or dispute reasons.	Unavailable

Sales-driven behaviour: When a quotation places a hold, the unit moves to a held/BLOCKED state; releasing the hold returns it to AVAILABLE. A Sales Order going ACTIVE books the unit; the SO module syncs unit status on ACTIVE/COMPLETED/CANCELLED transitions.

---

Project (ProjectStatus — 6 statuses)

Source: status.enum.ts. The projects module does not enforce a strict transition map for project status, so the diagram is conceptual.

Value	Meaning
DRAFT	Project record created; configuration in progress.
PLANNING	Planning and structuring (holdings, allocations) underway.
ACTIVE	Project is live and operational.
ON_HOLD	Temporarily paused.
COMPLETED	Project finished.
CANCELLED	Project cancelled. Recommended terminal alternative to deletion when a project has dependencies.

---

Partnership (PartnershipStatus — 4 statuses)

Source: partnerships.service.ts — strictly enforced (DRAFT → ACTIVE → SUSPENDED/CLOSED).

Value	Meaning
DRAFT	Partnership created; holdings being configured. Not yet operational.
ACTIVE	Operational. Holdings must sum to 100% with exactly one managing partner before activation.
SUSPENDED	Temporarily not operational; cannot be modified while suspended.
CLOSED	Permanently closed. Terminal. Cannot be modified or deleted; recommended alternative to deletion.

Enforced transitions: DRAFT → ACTIVE; ACTIVE → SUSPENDED or CLOSED; SUSPENDED → ACTIVE or CLOSED; CLOSED → (none). Activating validates that active holdings total exactly 100.00% and that exactly one active managing partner exists.

---

Quotation (QuotationStatus — 4 enum values)

Source: quotations.service.ts — strictly enforced. Note: the quotation transition map in code also references an intermediate UNIT_HOLD state used when units from a quotation are placed on hold; it is shown below for completeness alongside the four canonical enum values (DRAFT, QUOTED, CANCELLED, CONVERTED).

Value	Meaning
DRAFT	Quotation being prepared; not yet finalised.
QUOTED	Finalised and shared with the buyer (requires at least one unit).
UNIT_HOLD	One or more units from this quotation are currently held. Reverts to QUOTED when all holds are released.
CANCELLED	Quotation cancelled. Terminal. Held units are auto-released.
CONVERTED	Converted into a Sales Order. Terminal.

Enforced transitions: DRAFT → QUOTED or CANCELLED; QUOTED → CANCELLED (and, via the hold operation, QUOTED ↔ UNIT_HOLD); UNIT_HOLD → CANCELLED; CANCELLED and CONVERTED are terminal. Conversion to a Sales Order is allowed only from QUOTED or UNIT_HOLD.

See Sales Calculations for how quotation amounts are computed, and Quotations for the workflow.

---

Sales Order (SalesOrderStatus — 10 statuses)

Source: sales-orders.service.ts — strictly enforced.

Value	Meaning
DRAFT	Sales Order being prepared.
PENDING_APPROVAL	Submitted and awaiting approval.
ACTIVE	Approved and live; the unit is booked.
COMPLETED	Fully executed (e.g. fully paid).
INVOICED	A Sales Invoice has been raised against this SO. Terminal for SO status.
CANCELLED	Cancelled (a reason is mandatory). Terminal.
FORFEITED	Booking forfeited. Terminal.
SHIFTED	Booking shifted to another unit/SO. Terminal.
SPLIT	Sales Order split. Terminal.
AGREEMENT_SIGNED	Agreement executed with the buyer (an interim milestone after ACTIVE).

Enforced transitions:

• DRAFT → PENDING_APPROVAL
• PENDING_APPROVAL → ACTIVE (approve), DRAFT (send back), or CANCELLED
• ACTIVE → AGREEMENT_SIGNED, COMPLETED, CANCELLED, FORFEITED, SHIFTED, or SPLIT
• AGREEMENT_SIGNED → COMPLETED, CANCELLED, FORFEITED, SHIFTED, or SPLIT
• COMPLETED → CANCELLED
• INVOICED, CANCELLED, FORFEITED, SHIFTED, SPLIT → terminal (no outgoing transitions)

INVOICED is set automatically when a Sales Invoice is created from the SO; it is not a manual target in the status transition map.

See Sales Orders for the workflow and Sales Calculations for amount computation.

---

Sales Invoice (SalesInvoiceStatus — 5 statuses)

Source: sales-invoices.service.ts — strictly enforced.

Value	Meaning
DRAFT	Invoice being prepared. Only DRAFT invoices can be deleted.
ISSUED	Issued to the buyer (requires at least one buyer and one unit).
PARTIALLY_PAID	Partial payment received.
PAID	Fully paid.
CANCELLED	Cancelled (a reason is mandatory). Terminal.

Enforced transitions: DRAFT → ISSUED; ISSUED → PARTIALLY_PAID, PAID, or CANCELLED; PARTIALLY_PAID → PAID or CANCELLED; PAID → CANCELLED; CANCELLED is terminal.

See Sales Invoices for the workflow.

---

User (UserStatus — 6 statuses)

Source: status.enum.ts. User status is the product of authentication and admin actions (verification, invitation, lockout, suspension) rather than a single transition map, so the diagram is conceptual. See Auth Flows for the precise rules behind each transition.

Value	Meaning
DISABLED	Default for a new user; no login access until enabled/invited.
INVITED	A login invitation has been sent and is pending acceptance (invitations expire after 7 days).
ACTIVE	Verified and active; can log in.
SUSPENDED	Temporarily blocked by an administrator.
LOCKED	Locked after exceeding the failed-login limit (5 failures → 15-minute lockout).
UNVERIFIED	Account exists but the email has not yet been verified.

---

Quick reference: terminal states

Entity	Terminal states (no further transitions)
Stock	SPLIT
Partnership	CLOSED
Quotation	CANCELLED, CONVERTED
Sales Order	INVOICED, CANCELLED, FORFEITED, SHIFTED, SPLIT
Sales Invoice	CANCELLED

Unit, Project, and User do not have a strictly enforced transition map; their "terminal" states (e.g. unit REGISTERED, project COMPLETED/CANCELLED) are conceptual.