# Business Flows

## Direct answer

These flows describe current implementation only. Each line follows `USER ACTION → FRONTEND → API → BACKEND → DATABASE → STATUS CHANGE → NEXT FLOW`. Where the old map and current code differ, current code wins and the conflict is named.

## Customer and access

### 1. Customer self-registration

Customer submits registration → `customer/index.html` → `POST /auth/customer/register` → validates uniqueness, hashes credential, creates customer/referral/profile data → `customers` (+ address/referral helpers) → portal/customer status initialized → customer login.

### 2. Staff creates a customer

Staff submits customer form → `customers.html` → `POST /customers` → validates and assigns customer code → `customers`, `customer_addresses` → customer record created → KYC completion or savings/contract/cash flow.

### 3. Customer/staff login

User submits credentials → staff `login.html` or customer `index.html` → staff/customer login API → role/scope checks and abuse protection → `employees`/`roles` or `customers`, auth-failure metadata → authenticated token/session state → dashboard/portal.

### 4. Additional KYC and profile completion

Staff/customer saves profile → customer pages → `PUT /customers/:id` → validates access and updates basic/address/employment/reference/guardian sections → customer profile tables → KYC fields updated → credit review/contract prerequisite checks.

### 5. Staff resets customer credential

Staff requests reset → `customers.html` → `POST /customers/:id/reset-password` → issues temporary credential metadata → `customers` → `must_change_password` set → customer must change password in portal.

## Savings down payment

### 6. Create savings account

Staff selects customer/product/plan/promotion → `contracts.html` → `POST /savings/accounts` → checks no conflicting active contract/account, calculates canonical target, creates account and first period → savings and promotion tables → account `SAVING`, period `OPEN` → accept deposit.

### 7. Submit savings deposit

Staff submits initial/next amount (or future caller submits deposit) → `contracts.html` currently calls the route for initial deposit → `POST /savings/accounts/:id/transactions` → validates account/status/idempotency/reference → `savings_transactions` → transaction `PENDING` → verification queue (backend exists; current UI caller not found).

### 8. Verify or reject savings deposit

Verifier decides → no direct current frontend caller found → `POST /savings/transactions/:id/verify` → locks transaction, changes verification status, allocates verified amount across periods → `savings_transactions`, `savings_allocations`, `savings_periods`, `savings_accounts` → `VERIFIED`/`REJECTED`; periods `PARTIAL`/`PAID`; account may become `READY_FOR_CONTRACT` → conversion.

### 9. READY_FOR_CONTRACT

Verified total reaches target → savings verification allocator → internal helper → recomputes verified sum → `savings_accounts` → `SAVING` to `READY_FOR_CONTRACT` → create/match pending contract then convert.

### 10. Convert savings to contract

Staff supplies matching pending contract → no direct current frontend caller found → `POST /savings/accounts/:id/convert` → locks account/contract, verifies target/customer/product match, applies down payment and remaining loan → `savings_accounts`, `contracts` → account `CONVERTED`; contract `PENDING_APPROVAL` → credit/approval and activation. The old `BROKEN` label conflicts with the active atomic handler: **MAP/CODE CONFLICT**.

## Contract and installments

### 11. Create contract draft/pending record

Staff enters customer/product/terms → `contracts.html` → `POST /contracts` → validates KYC, financial inputs, promotion/savings context → `contracts`, promotion/benefit tables and applicable schedule data → pending contract status → approval/activation.

### 12. Credit review / contract update

Staff changes contract lifecycle or terms → `contracts.html` → `PUT /contracts/:id` → validates and persists allowed fields/schedule changes → `contracts`, `payment_schedules` → pending/approved state changes → activation.

### 13. Contract activation

Authorized staff activates → `contracts.html` → `POST /contracts/:id/activate` → validates customer/KYC/savings and generates/validates schedules → `contracts`, `payment_schedules` → contract `ACTIVE` → installment payment.

### 14. Submit installment payment

Customer uploads slip and chooses next due/payoff → customer dashboard → `POST /payment-slips`, then `POST /contracts/:id/payment-intents` → stores managed upload, calculates server-owned amount, prevents duplicate pending intent → file storage + `contract_payment_intents` → intent `PENDING` → finance verification.

### 15. Verify/reject installment payment

Finance decides → `contracts.html` → `POST /payment-intents/:id/verify` → locks intent/schedule, validates current amount, writes payment or rejection → `contract_payment_intents`, `payment_schedules`, `payments`, audit → intent `VERIFIED`/`REJECTED`; schedule `PAID` when approved → next installment or contract completion.

### 16. Early payoff

User requests quote, submits PAYOFF intent, verifier approves → customer dashboard/contracts page → payoff quote + payment-intent create/verify → server recomputes all outstanding schedules and discount → intents, payments, schedules, contracts → schedules `PAID`, contract `CLOSED` → completed lifecycle. Direct payoff endpoint is `DISABLED (410)`: **MAP/CODE CONFLICT**.

### 17. Contract cancellation

Admin supplies reason → `contracts.html` → `POST /contracts/:id/cancel` → rejects if verified payments exist, records audit → `contracts`, `audit_logs` → contract `CANCELED` → follow-up/recovery outside this route.

## Cash sales and refunds

### 18. Create cash sale

Cashier selects customer/product/promotion and submits payment → `cash-sales.html` → `POST /cash-sales` → validates canonical amounts and idempotency → `cash_sales`, promotion/redemption/application tables → sale posted/current transaction status → receipt, optional void/refund.

### 19. Void cash sale

Manager provides reason → `cash-sales.html` → `POST /cash-sales/:id/void` → validates eligibility/idempotency and audits → `cash_sales` (+ audit/idempotency helpers) → `VOIDED` → terminal history.

### 20. Refund cash sale

Manager provides refund reason → `cash-sales.html` → `POST /cash-sales/:id/refund` → validates eligible amount/state, records refund and audit → `cash_sale_refunds`, `cash_sales` → refunded amount/status updated → terminal/refund reporting.

## Promotions, product, staff, and service

### 21. Claim a promotion event

User chooses eligible event → contracts/cash-sales/customer dashboard → eligibility GET then claim POST → validates qualification and prevents duplicate application → promotion event/application tables → application `CLAIMED` then later `APPLIED` by sale/savings/contract → business creation flow.

### 22. Create promotion campaign/package/benefit

Admin completes wizard → `promotions.html` → promotions/package/benefit routes → writes campaign hierarchy and validation rules → promotion tables → active/inactive campaign/package state → sales eligibility.

### 23. Create product variant

Staff submits product → `products.html` → `POST /products` → validates/code-generates → `products` → product active/available → savings/contract/cash-sale selection.

### 24. Create/toggle staff account

Admin submits staff or toggles access → `employees.html` → POST employees / PATCH toggle → role validation and credential hashing/status change → `employees`, `roles` → active/suspended access → login eligibility.

### 25. Collection follow-up

Collector opens queue and records call → `follow-ups.html` → GET today then POST follow-up → derives overdue queue and stores result → contracts/schedules/customers read, `follow_up_logs` write → follow-up status recorded → next collection date/action.

### 26. Satisfaction follow-up

Staff opens satisfaction queue and records outcome → `follow-ups.html` → GET satisfaction then POST follow-up → derives completed-service queue → contracts/customers read, `follow_up_logs` write → satisfaction result stored → service follow-up.

### 27. Executive dashboard

Executive opens dashboard → `dashboard.html` → `GET /dashboard/summary` → aggregates sales/contract/payment/schedule data → read-only financial tables → no status change → investigation into operational pages.