Flutter/Native Overlay and NestJS Backend
Budget: $250 – $750 USD
Task Doc: Guarantee Overlay (Flutter/Native + NestJS)
https://docs.google.com/document/d/14gaCz0tn6Ku9r3zQNr7OOuAM0k6jFxBKyNra69laYRo/edit?usp=sharing
Resources available for this project (post-acceptance access only)
DeepLink FlutterBridge, DualCam, and parts of the overlay UI (these components follow our quality-standards - the project incumbent will also follow these standards).
Skilled dev estimate: ~4 days to adapt these components to your project work. Otherwise, quote Greenfield (no repo access pre-acceptance).
Acceptance (Non-Negotiable)
1) Mobile Overlay (Flutter/Native)
Overlay activates 60 min pre-event (or distance/ETA-adjusted), and drives required evidence steps.
Evidence capture:
Selfie (front camera)
Outfit photo (full body)
Video/context video (front camera) with text: “Please make sure that your face stays in the shot.”
Background location (after permission; minimal UI)
Audio dictation + AI classification (provider-pluggable)
UI behaviors:
FAB menu (top-right default; expandable; pending indicators)
Red dot for pending steps with pop/blip
Pulsing “next step” cue
Toasts: short, dismissible; optional sound
“Ah Shucks” modal blocks app at Final Call end and triggers queue-or-wipe outcome.
2) Timeline Config (Admin + Live Preview)
Admin timeline editor (web acceptable) must support:
Drag/drop timeline events; snap increments (ex: 5 min)
Edit timings, messages/templates, cadence, sounds, toggles
Versioned configs (apply to future users only; no retro mutation)
Live preview/simulator of overlay behavior without a real event
Timeline rules must support:
Distance/ETA adjustments + “leave now” nudges
Prospect-message Final Call extension (default +5 min; configurable; capped by admin config)
Outfit auto-send at 5 min if at location (configurable rule)
3) Offline + Kill/Resume + Delayed Upload (Reliability)
Evidence capture works offline.
App kill/reopen mid-flow resumes correctly (no corruption, no duplicates).
Upload retries complete when connectivity returns within submission window (default 24 hours, configurable).
Correct authoritative outcomes:
success (no refund)
forfeit
queued for review vs wipe evidence (per Ah Shucks decision + rules)
4) Phase 0 POC “Cheap Mode Gate” (Config-Only Provider Swap)
Before gold wiring, prove the full system end-to-end in cheap mode:
Cheap mode uses deterministic mocks (optional cheap smoke tests allowed).
Config-only swapping between cheap and gold providers (no code changes).
Must implement abstractions:
RecognitionProvider (face + scene)
DictationProvider (primary + fallback)
Recognition output must return: pass/fail + confidence + reason codes (enums).
5) Backend (NestJS) is Source of Truth
Required domain coverage: GuaranteeSession, TimelineConfig (versioned), Evidence, CaseFile, Agent, Team, Appeal, Decision, Metrics.
Required endpoints (minimum):
/start, /status, /step-complete, /forfeit, /finalize
/timeline-config CRUD + version bump
/refund-case create/read + evidence links
/appeal create + lifecycle transitions
Storage:
Media in S3 with least privilege
Retention default 2 days, configurable via policy; wipe path deletes immediately/guaranteed purge
6) Appeals + Agent Workflow (Redis)
Appeals dispatch via Redis queue to two independent agents using configurable agent score weights:
active status, agent rating, resolution time, team rating
If disagreement: third tiebreak agent
Lifecycle must be: Queued → Under Review → Escalated → Decisioned → Actioned → Archived
Agent scoring effects:
correct agents/teams: +1
incorrect: -1
Once Actioned, execution is automatic.
7) Notifications
POC: mocked/cheap sending proving scheduling + rate control.
Final: push + Twilio SMS + voice fallback, provider-configurable, with rate limits, cost caps, kill-switches.
8) Tests + Reproducibility
Automated tests for core rules and edge cases: offline resume, UTC/timezones, idempotency, delayed upload window logic.
Dockerized backend + README to run locally.
Performance expectation: overlay interactions responsive; no obvious jank.
Required Demo Videos (Acceptance Proof)
You must deliver screen recordings proving end-to-end behavior (not partial clips):
Standard compliance + Verified Effort badge unlock
Forfeit/failure
Offline capture → later upload → correct finalization
Kill mid-flow → reopen → resume → complete
Distance/ETA-adjusted timeline + “leave now”
Prospect-message extension behavior
Audio dictation + classification “successful meetup” path that nulls guarantee (config)
Admin timeline editor live preview/simulator
Appeal flow: Redis dispatch → two agents → tiebreak → Actioned result
Missing any video blocks acceptance.
Milestones (Results)
M0: Phase 0 Cheap Mode Gate
Full end-to-end state machine, offline+kill/resume, delayed upload window, admin editor + live preview, tests, Docker/README, all required demos.
M1: Gold Wiring + S3 + Notifications
Config-only swap to real providers, S3 retention/wipe enforced, push + Twilio SMS/voice fallback w/ caps/kill-switches, casefiles/evidence links.
M2: Appeals + Roles + Agent Scoring UI
Roles (Super Admin/Manager/Agent), teams, scoring weights, two-agent+tiebreak, lifecycle correctness, auto Actioned execution, manager views.
M3: Hardening + Final QA Pack
Expanded tests (idempotency, flaky network, partial uploads, corrupted local cache recovery), final docs/runbooks, final clean demos.
Deliverables
Flutter/Native overlay module + capture flows + offline queue + resumable uploads
NestJS backend modules, schemas, endpoints, providers, queues
Admin timeline editor + live preview + role gating
Tests, Docker, README, demo videos
Implementation Notes (Suggestions)
Provider interfaces: RecognitionProvider (face+scene), DictationProvider (primary+fallback), NotificationProvider (push/sms/voice) — config-only swapping
Uploads: chunked/resumable required for full-trip recording path; POC may use smaller limits but must prove chunking path
S3: least privilege; wipe is immediate/guaranteed purge
https://docs.google.com/document/d/14gaCz0tn6Ku9r3zQNr7OOuAM0k6jFxBKyNra69laYRo/edit?usp=sharing
Resources available for this project (post-acceptance access only)
DeepLink FlutterBridge, DualCam, and parts of the overlay UI (these components follow our quality-standards - the project incumbent will also follow these standards).
Skilled dev estimate: ~4 days to adapt these components to your project work. Otherwise, quote Greenfield (no repo access pre-acceptance).
Acceptance (Non-Negotiable)
1) Mobile Overlay (Flutter/Native)
Overlay activates 60 min pre-event (or distance/ETA-adjusted), and drives required evidence steps.
Evidence capture:
Selfie (front camera)
Outfit photo (full body)
Video/context video (front camera) with text: “Please make sure that your face stays in the shot.”
Background location (after permission; minimal UI)
Audio dictation + AI classification (provider-pluggable)
UI behaviors:
FAB menu (top-right default; expandable; pending indicators)
Red dot for pending steps with pop/blip
Pulsing “next step” cue
Toasts: short, dismissible; optional sound
“Ah Shucks” modal blocks app at Final Call end and triggers queue-or-wipe outcome.
2) Timeline Config (Admin + Live Preview)
Admin timeline editor (web acceptable) must support:
Drag/drop timeline events; snap increments (ex: 5 min)
Edit timings, messages/templates, cadence, sounds, toggles
Versioned configs (apply to future users only; no retro mutation)
Live preview/simulator of overlay behavior without a real event
Timeline rules must support:
Distance/ETA adjustments + “leave now” nudges
Prospect-message Final Call extension (default +5 min; configurable; capped by admin config)
Outfit auto-send at 5 min if at location (configurable rule)
3) Offline + Kill/Resume + Delayed Upload (Reliability)
Evidence capture works offline.
App kill/reopen mid-flow resumes correctly (no corruption, no duplicates).
Upload retries complete when connectivity returns within submission window (default 24 hours, configurable).
Correct authoritative outcomes:
success (no refund)
forfeit
queued for review vs wipe evidence (per Ah Shucks decision + rules)
4) Phase 0 POC “Cheap Mode Gate” (Config-Only Provider Swap)
Before gold wiring, prove the full system end-to-end in cheap mode:
Cheap mode uses deterministic mocks (optional cheap smoke tests allowed).
Config-only swapping between cheap and gold providers (no code changes).
Must implement abstractions:
RecognitionProvider (face + scene)
DictationProvider (primary + fallback)
Recognition output must return: pass/fail + confidence + reason codes (enums).
5) Backend (NestJS) is Source of Truth
Required domain coverage: GuaranteeSession, TimelineConfig (versioned), Evidence, CaseFile, Agent, Team, Appeal, Decision, Metrics.
Required endpoints (minimum):
/start, /status, /step-complete, /forfeit, /finalize
/timeline-config CRUD + version bump
/refund-case create/read + evidence links
/appeal create + lifecycle transitions
Storage:
Media in S3 with least privilege
Retention default 2 days, configurable via policy; wipe path deletes immediately/guaranteed purge
6) Appeals + Agent Workflow (Redis)
Appeals dispatch via Redis queue to two independent agents using configurable agent score weights:
active status, agent rating, resolution time, team rating
If disagreement: third tiebreak agent
Lifecycle must be: Queued → Under Review → Escalated → Decisioned → Actioned → Archived
Agent scoring effects:
correct agents/teams: +1
incorrect: -1
Once Actioned, execution is automatic.
7) Notifications
POC: mocked/cheap sending proving scheduling + rate control.
Final: push + Twilio SMS + voice fallback, provider-configurable, with rate limits, cost caps, kill-switches.
8) Tests + Reproducibility
Automated tests for core rules and edge cases: offline resume, UTC/timezones, idempotency, delayed upload window logic.
Dockerized backend + README to run locally.
Performance expectation: overlay interactions responsive; no obvious jank.
Required Demo Videos (Acceptance Proof)
You must deliver screen recordings proving end-to-end behavior (not partial clips):
Standard compliance + Verified Effort badge unlock
Forfeit/failure
Offline capture → later upload → correct finalization
Kill mid-flow → reopen → resume → complete
Distance/ETA-adjusted timeline + “leave now”
Prospect-message extension behavior
Audio dictation + classification “successful meetup” path that nulls guarantee (config)
Admin timeline editor live preview/simulator
Appeal flow: Redis dispatch → two agents → tiebreak → Actioned result
Missing any video blocks acceptance.
Milestones (Results)
M0: Phase 0 Cheap Mode Gate
Full end-to-end state machine, offline+kill/resume, delayed upload window, admin editor + live preview, tests, Docker/README, all required demos.
M1: Gold Wiring + S3 + Notifications
Config-only swap to real providers, S3 retention/wipe enforced, push + Twilio SMS/voice fallback w/ caps/kill-switches, casefiles/evidence links.
M2: Appeals + Roles + Agent Scoring UI
Roles (Super Admin/Manager/Agent), teams, scoring weights, two-agent+tiebreak, lifecycle correctness, auto Actioned execution, manager views.
M3: Hardening + Final QA Pack
Expanded tests (idempotency, flaky network, partial uploads, corrupted local cache recovery), final docs/runbooks, final clean demos.
Deliverables
Flutter/Native overlay module + capture flows + offline queue + resumable uploads
NestJS backend modules, schemas, endpoints, providers, queues
Admin timeline editor + live preview + role gating
Tests, Docker, README, demo videos
Implementation Notes (Suggestions)
Provider interfaces: RecognitionProvider (face+scene), DictationProvider (primary+fallback), NotificationProvider (push/sms/voice) — config-only swapping
Uploads: chunked/resumable required for full-trip recording path; POC may use smaller limits but must prove chunking path
S3: least privilege; wipe is immediate/guaranteed purge