COS-APR-001

Client Approval Flow

Module Approval

Status Ready

Phase 2

Dependencies COS-DSN-002 + COS-PRC-001

Downstream COS-ORD-001

Last Updated June 2026

Purpose

After internal review and pricing, the design and quote are sent to the customer for approval. Customer gives a structured response — replacing "ok bhai" WhatsApp messages with a timestamped, auditable record. System tracks all pending approvals, sends automated reminders, and escalates when aging.

Actors

Actor	Type	Role
RM	Internal	Sends approval package, monitors
Aayushi	Internal	Monitors all pending approvals across all customers
AI Communication Engine	System	Drafts the outbound approval message
Customer	External	Reviews design + price, approves or requests changes

Trigger

Job state transitions to CLIENT_APPROVAL_PENDING after internal review passes and pricing is computed.

Full Flow

1. Job reaches CLIENT_APPROVAL_PENDING
2. AI Communication Engine drafts approval message per customer preferences
3. RM reviews draft → one-click send OR edits first
4. System sends via WhatsApp (primary) or email
   → Approval link included (token-based, no login required)
5. SLA timer starts: 72h standard, 48h Tier A customers
6. Customer receives message

   PATH A — Customer uses approval link:
   → Sees: full render, spec sheet, price breakdown
   → Taps: [Approve] / [Request Changes + feedback] / [Reject]
   → Response recorded with timestamp

   PATH B — Customer replies on WhatsApp / email:
   → RM records response manually in system
   → Same job_event created, RM noted as recorder

7. APPROVE  → state = CAD_APPROVED → moves to COS-ORD-001
   REVISION  → state = REVISION_REQUESTED → loops to COS-DSN-001
   REJECT    → state = CANCELLED

8. SLA breach:
   → 72h: RM auto-reminder (AI drafted)
   → 96h: Aayushi alerted
   → 120h: Founder alerted (Tier A only)

Approval Message (AI-drafted, RM reviews)

Hi [Name],

Your design CJ-2026-001234 is ready.

[render image]

Details:
  Metal:    14kt White Gold
  Diamonds: Natural VVS · ~4.1ct
  Weight:   ~16.4g
  Price:    $9,250 (incl. duties to USA)

Let us know if you'd like to proceed or have any changes.
[Tap here to approve or request changes]

— Chandra Jewels

Message format varies per customer preference.

Approval Link — Customer Screen

Mobile-optimised, token-authenticated (no login):

┌─────────────────────────────────────┐
│  Chandra Jewels                     │
│  Design Review — CJ-2026-001234     │
├─────────────────────────────────────┤
│                                     │
│   [Full render — pinch to zoom]     │
│                                     │
├─────────────────────────────────────┤
│  Metal:     14kt White Gold         │
│  Diamonds:  Natural VVS · ~4.1ct    │
│  Weight:    ~16.4g                  │
│  Price:     $9,250 (duties incl.)   │
│  Ref ID:    CJ-2026-001234          │
├─────────────────────────────────────┤
│                                     │
│  [✓ Approve]  [✎ Request Changes]  │
│                                     │
│  Changes feedback:                  │
│  ┌───────────────────────────────┐  │
│  │                               │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Link expires after 7 days. Single-use token.

Pending Approvals — Aayushi View

Pending Approvals — 14 jobs
──────────────────────────────────────────────────
CJ-2026-001201  Icechamp   Pendant   Sent 2d  ● AGING
CJ-2026-001198  JU         Ring      Sent 1d  ○ OK
CJ-2026-001185  Prime      Bracelet  Sent 3d  ● FOLLOW UP
──────────────────────────────────────────────────
[Bulk: Send follow-up to all aging]

Green < 50% SLA · Yellow 50–80% · Red > 80% · Flashing = breached

Business Rules

Rule	Detail
Render required before send	Cannot send without at least one render image
Price required before send	COS-PRC-001 must be complete
One active approval per job	Cannot send new approval while one is pending
Token	Signed JWT, job_id scoped, 7-day expiry, single-use
WhatsApp path supported	RM can record manual approval — both paths produce same audit record
Post-approval spec lock	Once approved, spec is frozen. Any change requires new revision + new approval.
Revision loop > 3	Auto-alert Anmol. Customer may need different design approach.

API Endpoints

POST /jobs/:job_id/send-approval
  Body: { channel, message_override? }
  Returns: { approval_link, message_sent_id }

GET  /approvals/pending?rm_id=:id
GET  /approvals/pending                          [Aayushi — all]

POST /approvals/:token/respond                   [customer-facing, no auth]
  Body: { decision, feedback? }

POST /jobs/:job_id/record-manual-approval
  Body: { decision, feedback?, recorded_by, evidence_note }

GET  /jobs/:job_id/approval-history

Out of Scope

Item	Handled in
Style master / order creation	COS-ORD-001
Pricing	COS-PRC-001
Production scheduling	COS-PRD-001