15 — Business Requirements Document (BRD)

Easy Branch Desk — the company's single working surface. This document tells a builder with zero EHFL context what every screen is for, what data it shows and where each field comes from, what every call-to-action does, and how data flows end to end. The clickable truth is reference/branch-desk-prototype.html (v11); the rules are doc 02; the tables are doc 04; the API is doc 05. Where this BRD and doc 02 differ, doc 02 wins.

1. Purpose and success measures

Problem. Case work at EHFL runs on offline artefacts — a DRM stuck-cases Excel, a reply-tracker sheet, morning/evening commitment mails, per-case WhatsApp threads. They cost hours daily, die with attrition, and hide cases.

Product. One role-based desk where every stuck loan is a card with a named owner, a clock and one best next action; where every function plans its morning on the system, the plans consolidate to HO at 10:30, and the evening result is compiled from LOS/LMS — never reported; and where every chase, reply and escalation is an event on the case, visible to everyone on it.

Success measures (tracked from the read models, targets in Settings): ≥90% of field users open the desk each working day; ≥80% of past-TAT cases touched same-day by week 2; ≥95% of in-flight cases carry a real (non-placeholder) disbursal date; ≥70% of chases answered within 1 working day; new-joiner time-to-first-productive-day ≤ 1 day; the four offline artefacts retired after two clean parallel days.

2. Personas and access (RBAC)

Login (SSO / LOS token) resolves a person → role + scope from org_person (+ org_los_user mapping, C3a rules; HRMS designation wins conflicts). A person sees only their scope. The prototype's header tabs simulate exactly these logins.

Server-side scope checks on every endpoint (CLAUDE.md rule 4). Customer phone/email/address/PAN/Aadhaar never reach any client (rule 3); collections show masked account ids only.

3. The standard screen contract

Every role's screen = (a) identity header with live scope numbers, (b) the standard strip — Plan my day · Close my day · Messages — always in the same position, (c) the role's queue as cards (phone) or table (desktop), (d) the shared case sheet/drawer for actions. Simple mode rules (rule 6): ≥16px text, ≥56px labelled buttons, one red main action per card, no codes, date chips not date inputs, lasting Done ✓, EN/HI via i18n_string.

The day cycle (all times are Settings rows): plans filed by 09:30 → manager acceptance by 10:30 → freeze_morning_grid job at 10:30 writes the branch×function grid → workday of case actions → compile_day_plans 19:00 (provisional; final 23:55) writes said-vs-done from LOS/LMS → compile_scores → planning window flips to tomorrow at 19:00. Plans are immutable after submit except through the approver; the plan button renders filed-locked (green) until 19:00.

4. Screen-by-screen specification

Format per screen: Purpose · Data (field → source) · CTAs (control → effect → event) .

4.1 RM home (simple)

• Purpose: the RM's whole job, ranked; zero navigation.
• Data: greeting name (org_person); "N cases need you" = count of red + in-flight from desk_case scoped to rm_code; progress bar = touched-today / needed (desk_event); ranked list per doc 02 R9 priority score.
• CTAs: standard strip (§3); each card per §4.2; language toggle (persists in user prefs); Show more (+15).

4.2 Case card + action sheet (shared by RM/DBM/DRM; owner roles get Reply/Call variant)

• Data on the face: customer name, ₹ (desk_case ← LOS loan); plain stage (stage → label map desk_stage_label); late/on-time (days_in_stage vs TAT from desk_config); highest-priority trigger line (R10 triggers: rmx/conflict/proposed/expiring/noaccept/nocall); waiting-on (owner resolution R3) or customer's WhatsApp reply (S8 feed); last status line ▸ + thread summary ("n updates · last by X (role) · time") — recomputed from desk_event on every write, so a save anywhere updates every viewer's card face; Done ✓ line if touched today; committed-date pill with moves count and conflict note (R5).
• CTAs (each writes ONE desk_event, client_event_id idempotent, 10-s author undo):
• Update → up to 3 picklist statuses (desk_picklist per lane) + note → status event.
• Date → chip day; if an official date exists, reason mandatory (picklist) → date event with official = (actor is DRM/DBM); RM dates are proposals; DRM one-tap confirm; history + conflict per R5.
• Remind → resolved recipient at escalation level = min(working-days past TAT, named rungs), skip unnamed, cc lower rungs → chase event → notification_outbox (WhatsApp Business API/email/in-app).
• Call → masked click-to-call (Exotel); outcome picklist + optional call-back date → call event; duration via webhook.
• Comment → free text + tags (people/teams from the case's people graph) → comment event; tagged parties notified + case flagged "Tagged" in their queue.
• More → Move to another RM (reassign), Escalate now (esc), Cancel with reason (cancel).
• Case drawer (full view): facts strip, six tabs (same writes), escalation ladder rendering the chain with skipped rungs and "due now" level, case diary = system events (stage entries, ADR raised-by, tech/legal results, customer replies, sheet commitments) interleaved with desk events, newest first.

4.3 Plan my day — Business RM (one screen, five sections)

• Pools (GET /plan/today?function=business): new leads (unactioned, S1); loggable files; ready pool (lane ≥3), dated-today first; own ADRs oldest-first; own overdue accounts (LMS od_live>0).
• CTAs: Take it / Not mine per lead (blocking rule: submit disabled until every lead decided; Take writes status:Application started, Not-mine reassign to DRM pool); login stepper (norm ⚙) + file ticks; money-out ticks; ADR ticks; collection ticks. Submit → day_plan row (plan_function business) with items JSON; toast confirms; button locks green.
• Approval: DBM where the spoke has one, else DRM (D8b): Accept / override with own number (both numbers stored + shown) / set-plan-for-non-filer. DRM Confirm branch plan → freeze contribution to grid; then the same button opens the consolidated branch plan (all RMs + credit + ops + collections per branch, "not filed" red, read-only; evening shows said-vs-done on it).

4.4 Plan my day — Credit BCM (one screen, four sections)

• Pools: U1 queue = branch cases at U1 pending + BUW done · awaiting U1, ordered oldest-first; other branches' U1 queues in the state (oldest 6); PD pool = U1 queue + awaiting-U2; ADRs raised by credit.
• CTAs: decisions counter — FIFO by construction: top-k auto-selected, un-tickable; later files addable, head never skippable; floor 1/day ⚙. PD per case with mode = Video | Physical, floor 1 PD ⚙ (submit disabled otherwise). Property-visit ticks. ADR ticks. Submit → day_plan (credit) routed to U2 (accepts) + DRM (administrative, sees it in his branch plan). Multi-branch: reopening moves to the next unfiled branch; branch switcher inside the sheet.

4.5 Plan my day — Operations / Legal / Technical / CM

• Ops pools: docket/send-file (who='Branch ops: docket printing'), OTC/OPS closures, post-disbursal ledger (handover, CERSAI, PDD — feed S15), ops ADRs. Submit → state ops.
• Legal/Technical: state queue of cases waiting on the function (oldest first) + own ADRs. Submit → state legal manager / zonal technical, DRMs informed.
• CM: overdue accounts oldest-bucket-first, top pre-ticked; number + ₹ auto-summed. Submit → CM's HRMS manager.
• All plans lock on submit; evening view per item from system records (LOS decisions, LMS receipts); demo buttons in prototype stand in for those records and say so.

4.6 Close my day (every role, forced)

• Pending list: planned-but-not-done items + untouched red cases (top by priority score); CM: uncollected planned accounts.
• Rule: every row requires next-action date + written comment; the close button stays disabled until complete. Writes a next event per case ("Day close — next action : "), marks the person's day closed (badge ✓), and next morning those items surface on top of the plan pools (R17 carry-over).

4.7 Messages (every role)

• Data: chases awaiting MY reply (chase without later reply, scoped) + cases where I/my team is tagged.
• CTAs: Open & reply → owner roles get Reply form (Cleared / Need something from branch / Will clear by date / Not ours) → reply event lands on the branch's card instantly; others land in Comment. Delivery pipes (WhatsApp/email) are transport only; the thread is the record.

4.8 Regional & above (read-only, own span)

• Standards tab: zone→state→DRM-cluster→branch; columns: files, past-TAT (n + %), red actioned today, offer accepted ≤3d, called ≤1d of sanction, sanctioned within 10d, RMs no activity, say–do, owner missing. Cell colour = RAG vs MD standard (80% within N days; amber = past halfway glide ⚙). Row taps: state expands; branch opens that branch's desk.
• Morning plans 10:30: frozen grid branch × (Business · Credit · Ops · Collections) + state strip (Legal/Technical); unfiled = red dash; built by the 10:30 job, never typed.
• Evening result 7 pm: per branch committed / done / score % from the compile; nothing self-reported.
• Leaderboard: per-role boards; score = Σ(weighted hits) ÷ max(floor, open_items), capped 100; open items = leads + files + ADR + post-disbursal + collections + tickets (snapshot 06:00); min 5 open items to rank; streak badges; "warming up" until 2–3 live compiles; weights/thresholds all desk_config (doc 14). Scores appear only here — never on field screens.

5. Data flows (end to end)

LOS (read replica)  ─┐
LMS (read replica)  ─┼─ case builder job (15 min, staging-swap, LAN-dedupe) → desk_case (read model)
HRMS↔LOS users      ─┘                                    org_person / org_branch_scope / routing chains

user action (form) → POST /events (idempotent) → desk_event (append-only) ─┬→ recompute card face / thread / counters
                                                                           ├→ notification_outbox → WhatsApp API / email / in-app
                                                                           └→ Metabase (reads branch_desk directly)

Exotel: click-to-call POST → masked bridge; call-log webhook → call event with duration
Customer WhatsApp replies (S8) → desk_case.customer_says → cards + triggers

06:00 snapshot_open_items → desk_open_snapshot
09:30 plans (day_plan) → 10:30 freeze_morning_grid → HO grid (read-only L4–L7)
19:00 compile_day_plans (LOS/LMS only) → results on plans/grid → compile_scores → desk_score → leaderboard
19:00 planning window flips to next working day; 23:55 final compile catches late LOS entries (F3a)
escalation job (daily, working days): unanswered chase → +1 level, skip unnamed, cc manager → outbox

No AI and no workflow orchestrator anywhere above — plain scheduled SQL/TypeScript jobs (rule 0). All schedules and thresholds are desk_config rows.

6. Non-functional requirements

Privacy: rule 3 + masked telephony + masked account ids; access logs on owner/HO views. Performance: Today list < 2s on 3G-class connections at 09:25 load (C11 drill); read model refresh ≤15 min; chase delivery ≤1 min. Reliability: idempotent writes (client_event_id), append-only events, 10-s undo only; kill switch per module; parallel run week 1. Auditability: every number on a management screen reproducible from desk_event + desk_case as of its timestamp; config changes maker–checker with config_audit. Localisation: every string through i18n; Hindi at launch. Offline: retry queue for event posts; plans require connectivity (accepted).

7. Out of scope (go-live) and future

Out: credit decisioning screens, collections legal workflows, document upload (stays in LOS), bureau-alert screens, voice-note transcription. Future (additive, config-first): tranche/partial-disbursement module, customer-ticket feed into open items, more languages, TSM/ASM layers, contest views reading desk_score (e.g. Diwali se Pahle Diwali), Lovable/EASY-OS convergence.

8. Traceability

Rules → doc 02 (R1–R17) · tables → doc 04 · API → doc 05 · frontend patterns → doc 06 + reference/source · jobs & integrations → doc 07 · privacy → doc 08 · build order & prompts → doc 09 · acceptance → doc 10 + golive-checks.xlsx (C1–C12) · config → doc 11 · day plan → doc 12 (F1–F11) · risks → doc 13 · scoring → doc 14. Golden cases: docs/golden-cases.json must pass before any screen ships.