Blame & Claim Flow Architecture

All active flows — V1 (legacy) · V2 · V3 · V4 · V5 · V6 — with roles, route prefixes, and step sequences.

Legend & Roles

Roles by Flow
Flow Blame actor Claim/Review actor
V1 / V2 (user) USER USER + DAMAGE_EXPERT
Expert blame panel EXPERT FIELD_EXPERT —
Expert claim panel — DAMAGE_EXPERT FIELD_EXPERT FILE_REVIEWER FILE_MAKER
V2 expert-init (mirror) FIELD_EXPERT FIELD_EXPERT
V3 FIELD_EXPERT FIELD_EXPERT
V4 FILE_MAKER FILE_REVIEWER
V5 FILE_MAKER FILE_REVIEWER + FILE_MAKER (approval)
V6 CALL_CENTER + USER (via link) USER + DAMAGE_EXPERT (standard V2 claim)
Route Prefixes
Flow Blame prefix Claim / Review prefix
V1 (legacy) blame-request-management/ claim-request-management/
V2 user v2/blame-request-management/ v2/claim-request-management/
V2 expert-init (mirror) v2/expert-initiated/blame-request-management/ same controller (no separate claim prefix)
V2 expert blame panel v2/expert-blame/ v2/expert-claim/
V3 v3/expert-initiated/blame-request-management/ same controller
V4 v4/file-maker/blame-request-management/ v4/file-reviewer/blame-request-management/
V5 v5/file-maker/blame-request-management/ v5/file-reviewer/blame-request-management/ + v5/file-maker/claim-approval/
V6 v6/call-center-blame/ (agent) + v2/blame-request-management/ (user link) v2/claim-request-management/ (standard)

Flow V1 / V2 — User-Initiated Blame & Claim

The canonical user flow. Each party opens the app on their own device. First party fills blame info and invites the second party via SMS link. An expert blame review is optional. After blame completes the damaged party opens a claim which a damage expert prices. V1 = legacy routes (deprecated, @ApiExcludeController) · V2 = same logic, v2/ prefix, GlobalGuard + RolesGuard (USER).

Blame Phase
Actor:USER Guard: GlobalGuard
1
Create request
POST /
↓
2
Blame confession
POST /blame-confession/:id
↓
2a
[CAR_BODY only] Car body form
POST /car-body-form/:id
↓
3
Initial form (plate or VIN)
POST /initial-form/:id or /initial-form-vin/:id
↓
4
Details: location · voice · description
POST /add-detail-location, /upload-voice, /add-detail-description
↓
5
Add second party (sends SMS invite)
POST /add-second-party/:phone/:id/:frontendRoute
↓
6
Second party fills same steps 2–4
Second party logs in on their own device
↓
7
Sign (both parties)
PUT /sign/:id
Uploads signature image + isAccept flag
↓
8
[Optional] Expert blame review
via v2/expert-blame — assign → reply/resend
Expert assigns case, may request resend, submits verdict
↓
9
Blame COMPLETED
Guilty party determined
Claim Phase
Actor:USER (damaged party) + DAMAGE_EXPERT
1
Create claim from blame
POST v2/claim-request-management/create-from-blame/:blameId
↓
2
Select outer parts
PATCH /select-outer-parts/:claimId
↓
3
Select other parts + bank info
PATCH /select-other-parts/:claimId
↓
4
Upload documents
POST /upload-document/:claimId
↓
5
Capture parts (photos + angles)
POST /capture-part/:claimId
↓
6
Car capture (walk-around video)
PATCH /car-capture/:claimId
→ WAITING_FOR_DAMAGE_EXPERT
↓
7
Damage expert reviews & prices
via v2/expert-claim — assign → reply / price-drop
↓
8
User signs pricing / objects / rates
PUT /owner-insurer-approval/sign or /objection or /user-rating

Flow V2 — Expert-Initiated Mirror (In-Person)

A FIELD_EXPERT at the accident scene fills every step on behalf of both parties. The route prefix mirrors the user API exactly — v2/expert-initiated/blame-request-management/ — so the frontend can reuse the same pages by swapping only the prefix. The FIRST party registered is always the guilty party. After both signatures the blame completes immediately (no expert review queue). The expert also handles the claim steps on the same controller as the user flow (under v2/expert-initiated/claim-request-management/ if needed, or via the standard V2 claim controller).

Blame Phase
Actor:FIELD_EXPERT Guard: LocalActorAuthGuard
1
Create (creationMethod=IN_PERSON)
POST /
↓
2
Send & verify party OTP (guilty)
POST /send-party-otp/:id → /verify-party-otp/:id
↓
3
Blame confession (guilty)
POST /blame-confession/:id
↓
3a
[CAR_BODY only] Car body form
POST /car-body-form/:id
↓
4
Initial form / run inquiries (guilty)
POST /run-inquiries/:id or /run-inquiries-vin/:id
↓
5
Upload video (guilty first party)
POST /upload-video/:id
↓
6
Details: location · voice · description (guilty)
POST /add-detail-location, /upload-voice, /add-detail-description
↓
7
Add second party (no SMS link)
POST /add-second-party/:phone/:id/
↓
8
OTP + inquiries + details (damaged) — same steps 2–6
THIRD_PARTY only
↓
9
Sign FIRST then Sign SECOND
PUT /sign/:id (called twice, partyRole=FIRST / SECOND)
↓
10
Accident fields → Blame COMPLETED
POST /accident-fields/:id
No expert review queue — blame closes immediately
Claim Phase (same expert)
Actor:FIELD_EXPERT
1
Create claim from blame
POST v2/expert-initiated/claim-request-management/create-from-blame/:blameId
↓
2
Select outer + other parts
PATCH /select-outer-parts, /select-other-parts
↓
3
Upload documents
POST /upload-document/:claimId
↓
4
Capture parts
POST /capture-part/:claimId
↓
5
Car capture (walk-around video)
PATCH /car-capture/:claimId
→ WAITING_FOR_DAMAGE_EXPERT
↓
6
Damage expert reviews (normal flow)
via v2/expert-claim

Flow V3 — Expert-Initiated (Reorganised Steps)

Same actor as V2 mirror (FIELD_EXPERT), same end result, but steps are reorganised: all party narrative steps (OTPs, inquiries, voice, location, description, sign) come first for both parties, then the damage-assessment steps (accident fields, documents, part selection, capture, walk-around video) follow in a single dedicated pass. Blame + Claim share a single controller: v3/expert-initiated/blame-request-management/.

Actor:FIELD_EXPERT Guard: LocalActorAuthGuard

Party Steps (blame narrative)

1
Create (IN_PERSON)
POST /
↓
2
OTP send + verify (guilty)
POST /send-party-otp → /verify-party-otp
↓
3
[CAR_BODY] Car body form
POST /car-body-form/:id
↓
4
Run inquiries (guilty + auto-claim)
POST /run-inquiries/:id or /run-inquiries-vin/:id
↓
5
Location · description · voice (guilty)
POST /add-detail-location, /add-detail-description, /upload-voice
↓
6
Sign (guilty)
PUT /sign/:id
↓
7
OTP + inquiries + details (damaged)
THIRD_PARTY only; CAR_BODY skips 7–8
↓
8
Sign (damaged)
PUT /sign/:id

Damage Assessment Steps

9
Accident fields
POST /accident-fields/:id
↓
10
Get linked claim ID
GET /claim-id/:requestId
↓
11
Upload documents (licences, car cards)
POST /upload-document/:claimId
↓
12
Select outer parts
PATCH /select-outer-parts/:claimId
↓
13
Select other parts
PATCH /select-other-parts/:claimId
↓
14
Capture part photos + angles
POST /capture-part/:claimId
↓
15
Car capture (walk-around)
PATCH /car-capture/:claimId
↓
16
Upload blame video (FINAL)
POST /upload-video/:requestId
→ WAITING_FOR_EXPERT (THIRD_PARTY) or COMPLETED (CAR_BODY)

Flow V4 — Split Roles: FileMaker + FileReviewer

Two actors handle the same V3 work split across two controllers. FileMaker (v4/file-maker/blame-request-management/) handles the party narrative (OTPs, inquiries, details, signatures) and uploads the initial claim documents. FileReviewer (v4/file-reviewer/blame-request-management/) handles the damage assessment pass. The final blame video (upload-video) is a no-op in V4 — blame is already COMPLETED by car-capture.

FileMaker Phase
Actor:FILE_MAKER v4/file-maker/blame-request-management/
1
Create (IN_PERSON)
POST /
↓
2
OTP send + verify (guilty)
POST /send-party-otp → /verify-party-otp
↓
3
[CAR_BODY] Car body form
POST /car-body-form/:id
↓
4
Run inquiries (guilty + auto-claim)
POST /run-inquiries/:id or /run-inquiries-vin/:id
↓
5
Location · description · voice (guilty)
POST /add-detail-location, /add-detail-description, /upload-voice
↓
6
Sign (guilty)
PUT /sign/:id (partyRole=FIRST)
↓
7
OTP + inquiries + details + sign (damaged)
THIRD_PARTY only
↓
8
Upload documents (licences, car cards)
POST /upload-document/:claimId
Uses claim-id/:requestId to resolve claimId
↓
✓
FileMaker DONE — file sealed
FileReviewer can now pick up
FileReviewer Phase
Actor:FILE_REVIEWER v4/file-reviewer/blame-request-management/
1
Get linked claim ID
GET /claim-id/:requestId
↓
2
Accident fields
POST /accident-fields/:requestId
↓
3
Capture requirements lookup
GET /capture-requirements/:claimId
↓
4
Upload document (chassis / engine)
POST /upload-document/:claimId
↓
5
Select outer parts
PATCH /select-outer-parts/:claimId
↓
6
Select other parts
PATCH /select-other-parts/:claimId
↓
7
Capture part photos + angles
POST /capture-part/:claimId
↓
8
Car capture (walk-around video)
PATCH /car-capture/:claimId
claim → WAITING_FOR_DAMAGE_EXPERT · blame → COMPLETED
↓
9
Damage expert reviews & prices
via v2/expert-claim
↓
10
Owner sign on expert pricing (FileReviewer acts on behalf of user)
PUT /claim-sign/:claimId
Submits agree + branchId + signature image
↓
—
upload-video — no-op
POST /upload-video/:requestId (blame already COMPLETED)

Flow V5 — Same as V4 + FileMaker Approval Gate

FileMaker steps are identical to V4 except requiresFileMakerApproval=true is set at creation. The FileReviewer steps are also identical to V4. The only difference is the tail: after the damage expert completes their review and the owner signs, the claim moves to WAITING_FOR_FILE_MAKER_APPROVAL instead of proceeding directly to fanavaran submission. The FileMaker then approves (→ fanavaran) or rejects (→ back to WAITING_FOR_DAMAGE_EXPERT, max 2 rejections).

Actors:FILE_MAKERFILE_REVIEWERDAMAGE_EXPERT FILE_MAKER (approval)

FileMaker steps (identical to V4)

Same sequence under v5/file-maker/blame-request-management/ — no changes.

1–8
Identical to V4 FileMaker
See V4 left column above
↓
✓
FileMaker DONE — file sealed

FileReviewer steps + Approval tail

1–10
Identical to V4 FileReviewer (steps 1–10)
v5/file-reviewer/blame-request-management/
↓
11
Claim → WAITING_FOR_FILE_MAKER_APPROVAL
(instead of direct fanavaran submit)
↓
12
FileMaker approves or rejects
POST v5/file-maker/claim-approval/approve/:claimId
POST v5/file-maker/claim-approval/reject/:claimId
Reject sends back to WAITING_FOR_DAMAGE_EXPERT · max 2 rejections
↓
✓
Fanavaran submission (on approve)

Flow V6 — Call-Center Initiated

A CALL_CENTER agent takes the guilty party's details over the phone (plate + national code, or chassis/VIN), runs the insurance inquiry, then sends the blame link via SMS. The guilty party opens the link and completes the form through the standard V2 user flow — but the initial-form / inquiry step is automatically skipped (skipInitialFormStep=true) because the agent already ran it. For THIRD_PARTY files only the guilty party's data is collected by the agent; the damaged party fills their portion normally after the link is opened. The downstream claim flow (after blame completes) is the standard V2 claim flow.

Agent Phase
Actor:CALL_CENTER Guard: LocalActorAuthGuard · v6/call-center-blame/
1
Create blame file
POST /create
Body: { type: "THIRD_PARTY" | "CAR_BODY" }
↓
2
Run inquiry for guilty party (plate or VIN)
POST /run-inquiry/:requestId
POST /run-inquiry-vin/:requestId
Agent supplies plate + national-code collected from caller; results stored on blame document
↓
3
Send blame link to guilty party via SMS
POST /send-link/:requestId
Body: { phoneNumber }. Registers user if needed, stores as first party, fires SMS invite.
↓
✓
Agent done
Monitor via GET /my-files and GET /blame/:requestId
User Phase (standard V2 flow, inquiry skipped)
Actor:USER via SMS link → v2/blame-request-management/
1
Blame confession
POST /blame-confession/:id
↓
2
Initial-form / inquiry step — SKIPPED
skipInitialFormStep=true because agent already ran it
↓
3
Details: location · voice · description (guilty)
↓
4
Add second party (THIRD_PARTY: sends SMS invite)
POST /add-second-party/:phone/:id/:frontendRoute
↓
5
Second party fills normal steps on own device
THIRD_PARTY only
↓
6
Sign (both parties)
PUT /sign/:id
↓
7
[Optional] Expert blame review
via v2/expert-blame
↓
8
Blame COMPLETED → standard V2 claim flow
Damaged party opens claim via v2/claim-request-management/

Expert Review Panels (shared across V1–V6)

Expert Blame Panel — v2/expert-blame/
Actor:EXPERTFIELD_EXPERT
Method Route Purpose
GET / List blame cases for review
GET /:id Case details
POST /:id/assign Assign & lock case
PUT /reply/submit/:id Submit verdict
PUT /reply/resend/:id Request document resend
PUT /reply/inPerson/:id Submit in-person visit verdict
GET /report/unified-file-statuses Status catalog & counts
Expert Claim Panel — v2/expert-claim/
Actor:DAMAGE_EXPERTFIELD_EXPERTFILE_REVIEWERFILE_MAKER
Method Route Purpose
GET /requests List claim queue
GET /request/:id Claim details
POST /assign/:id Assign & lock
PUT /reply/submit/:id Submit damage assessment
PUT /reply/resend/:id Request resend
GET/PUT /request/:id/price-drop Price drop calculation
PATCH /validate-factors/:id Validate repair factors
PATCH /:id/visit Request in-person visit

Flow Comparison at a Glance

Dimension V1 / V2 User V2 Expert-Init V3 V4 V5 V6
Who fills blame? Each party on own device FIELD_EXPERT for both FIELD_EXPERT for both FILE_MAKER FILE_MAKER CALL_CENTER (inquiry) + USER (rest, via link)
Who does assessment? User, then expert reviews FIELD_EXPERT FIELD_EXPERT (same session) FILE_REVIEWER FILE_REVIEWER USER + DAMAGE_EXPERT (standard V2 claim)
Expert blame review? Optional queue No — immediate COMPLETED after accident-fields WAITING_FOR_EXPERT after upload-video COMPLETED after car-capture COMPLETED after car-capture Optional queue (same as V2 user)
Claim review DAMAGE_EXPERT DAMAGE_EXPERT DAMAGE_EXPERT DAMAGE_EXPERT → owner sign (FileReviewer) DAMAGE_EXPERT → owner sign → FileMaker approval DAMAGE_EXPERT (standard V2)
Inquiry step User fills initial-form Expert fills run-inquiries per party Expert fills run-inquiries per party FileMaker fills run-inquiries per party FileMaker fills run-inquiries per party Agent pre-fills; user skips it
Upload-video step Not in V2 user flow Yes — upload-video per party (mirror) Yes — last step → WAITING_FOR_EXPERT No-op (blame done by car-capture) No-op (blame done by car-capture) Not applicable
Blame route prefix v2/blame-request-management/ v2/expert-initiated/blame.../ v3/expert-initiated/blame.../ v4/file-maker/blame.../ v5/file-maker/blame.../ v6/call-center-blame/
Assessment route prefix v2/claim-request-management/ same controller same controller v4/file-reviewer/blame.../ v5/file-reviewer/blame.../ v2/claim-request-management/