CompensAI

workflow schema

Inspiration

People routinely miss out on legitimate compensation because the process is operationally painful. The bottleneck is not eligibility. It is the workflow: identifying the right email, extracting evidence, applying the correct legal framework, drafting a precise claim, and then following up until someone actually resolves it. We wanted the “magic moment” to be proactive discovery, so as new emails arrive, the system flags claimable situations and prepares an actionable draft with an estimated recovery value.

We also wanted a practical, privacy-aware approach. Instead of scanning years of historical inbox content by default, CompensAI monitors incoming emails going forward. For legacy cases, the user can forward specific emails into the system for processing.

What it does

Monitors incoming emails and detects potential compensation opportunities (flight delay, cancellation, damaged parcel).
Converts unstructured email content into a structured case with a clear status and an audit trail.
Enriches each case with additional context from broader legal frameworks relevant to the issue type.
Generates a deterministic claim draft (email-style) and pauses for one-click user approval.
Tracks vendor replies and updates the case status through resolution.
Maintains an append-only event timeline so every agent action is explainable and debuggable.
Hackathon demo setup:
- The monitored “client inbox” is client.compensai@gmail.com.
- The simulated “company/vendor inbox” is everydayaionx@gmail.com.
Billing behavior (hackathon MVP):
- We generate a Stripe invoice link and surface it in the dashboard.
- We do not email invoices to the user in the MVP.
- Payment tracking and reminders are future functionality.

How we built it

Email intake and monitoring: We use n8n for Gmail watch/send so we can connect email quickly without heavy OAuth engineering under hackathon constraints. Incoming emails are forwarded to the backend as structured payloads, and legacy emails can be forwarded manually for processing.
Backend orchestration: A FastAPI service performs classification, extraction, drafting, and state transitions. We store state in Supabase using:
- cases as the current snapshot of each case, and
- case_events as an append-only timeline of transitions and actions.
LLM reasoning: Claude is used for robust extraction and drafting, constrained by templates and a strict approval checkpoint.
Dashboard: Built in Lovable, reading directly from Supabase so the UI updates as soon as new case events are written.

Challenges we ran into

Reply monitoring reliability: We initially tried to run the full “send and monitor replies” loop entirely in n8n, but reply correlation and branching logic were brittle. Threads and vendor reply patterns required a more deterministic state machine.
Migration under time pressure: We moved core case logic to Python to enforce schemas, validate transitions, and maintain an auditable event timeline, while keeping Gmail watch/send in n8n for fast connectivity.
Idempotency and deduplication: Monitoring workflows easily create duplicate cases unless message/thread identifiers are enforced as dedup keys.
Balancing autonomy with safety: A fully autonomous “submit claims” flow is risky. We made the Human-in-the-Loop checkpoint a first-class state transition rather than an afterthought.

Accomplishments that we're proud of

Built an end-to-end, event-driven pipeline where every step is auditable via case_events.
Achieved a realistic agentic workflow: discovery, classification, drafting, approval gating, and response tracking, not just text generation.
Implemented a privacy-aligned operational model: monitor new inbound emails by default, and support legacy processing via explicit forwarding.
Designed the architecture so the UI can update live without complex frontend state management by relying on Supabase as the system of record.
Defined a clean billing interface for the dashboard: on success we generate an invoice link and update the case state, without relying on email delivery for billing.

What we learned

Agent systems need contracts and validation. Without strict schemas and state transitions, multi-step workflows drift and break.
Append-only event timelines are the right model for agentic workflows with interrupts, retries, and asynchronous replies.
The core difficulty is orchestration, not prompting: deduplication, safe execution, and reply correlation dominate real-world reliability.
Human approval is not a weakness. It is a safety primitive that enables automation in legal and financial workflows without unsafe autonomy.

What's next for CompensAI

Real user email integration: Move from hackathon-grade connectivity to production-ready user integration with tenant isolation, hardened token handling, and strict minimization. Keep the default model as inbound monitoring, with explicit forwarding for legacy cases.
Full authentication and access control: Implement complete Supabase Auth + RLS policies so each user sees only their cases and event timelines, and introduce roles for support and audit workflows.
Real vendor submissions (Ryanair, Amazon, etc.): Add vendor-specific connectors for claim portals and dispute flows, and introduce robust browser automation (for example with Playwright) with resilient selectors, run logs, and deterministic retries. This is a future capability and is intentionally out of scope for the hackathon MVP.
Rejection mitigation and escalation: If a claim is rejected, generate the next mitigation step: request missing info, draft a rebuttal grounded in policy and legal framework, and prepare escalation packs (evidence bundles, regulator/ADR templates where applicable).
Automatic follow-ups: Add SLA timers and scheduled follow-ups if vendors do not respond within (N) days, escalating after (M) days when appropriate.
Draft revision loop: Let users comment on the approval draft (“too aggressive”, “add booking ref earlier”), regenerate the draft with constraints, and keep the case in the approval state until the user approves.
Billing expansion: Enable invoice emailing, payment reminders, and automated collection flows once Stripe is fully integrated into the user identity and permissions model.