Inspiration

In digital commerce, a single transaction issue quickly turns into a fragmented, adversarial mess. Most dispute systems treat the first person who files a report as the default plaintiff and the other party as the accused. Meanwhile, when AI is introduced into fintech workflows, teams often fall into one of two traps: either building a chaotic multi-agent courtroom where LLMs debate each other and hallucinate authority, or giving AI reckless direct access to execute refunds and alter financial records.

We built VelaPal V6 around a simple, grounded philosophy: Two perspectives. One shared case. AI-first, human-governed, evidence-based resolution.

An allegation does not establish fault. Both Customer and Seller deserve symmetrical rights to initiate a report, prepare evidence privately, share verified versions, and reach a fair resolution—where AI handles structured preparation and neutral mediation, deterministic backend rules control permissions, administrators supervise by exception, and PayPal remains the authoritative system of record for official payment lifecycles.

What it does

VelaPal connects smart shopping, subscription control, digital entitlements, and symmetrical two-sided dispute resolution across three role-scoped workspaces (Customer, Seller, and Admin):

  • Symmetrical Two-Sided Dispute Intake (One case_id, Two Perspectives): Either the Customer (for example, ordering a 256 GB Pocket Drive for USD 59.00, but receiving an item labeled 128 GB) or the Seller (for example, reporting an unconfirmed payment or fulfillment discrepancy) can open an internal case. Duplicate reports on the same transaction and issue automatically bind to the same active case_id rather than spawning conflicting threads.
  • Private-First Evidence & Versioned Sharing: Both parties upload supporting files (photos, invoices, serial numbers) into a private quarantine (QUARANTINED → SCANNING → CLEAN). Evidence remains strictly private until the owner grants explicit SHARE_SOURCE consent, which increments the caseVersion and invalidates any stale unexecuted proposals.
  • Neutral AI Synthesis & Mediation (Not an AI Courtroom): A single deterministic Python and LangGraph orchestrator powered by Google Gemini analyzes authorized case records and separates outputs into Verified Server Facts, Attributed Party Claims, Missing Evidence, Material Contradictions, and Explicit Uncertainty—backed by strict source citations (sourceId, version, locator).
  • Four Distinct Consent & Approval Gates: VelaPal never merges permissions. We strictly separate SHARE_SOURCE (owner consent to share a specific file version), CONTINUE_MEDIATION (consent to mediate when uncertainty remains), ACCEPT_PROPOSAL_TERMS (bilateral agreement to exact settlement terms, such as a voluntary USD 20.00 partial refund), and AUTHORIZE_FINANCIAL_EXECUTION (Merchant fund-owner authorization with MFA step-up).
  • Risk-Based Admin Supervision: Administrators monitor metadata by default (disputes.read). Accessing shared case evidence requires disputes.investigate and explicit case assignment with a conflict-of-interest declaration. Even then, private party drafts remain strictly inaccessible to Admins.
  • Resilient Financial Execution & UNKNOWN Reconciliation: Financial operations execute once via compare-and-swap (CAS) locking and idempotency keys. If a provider call times out, VelaPal records an explicit UNKNOWN state rather than assuming failure or blindly retrying—reconciling against the exact same operationId via PayPal read APIs and verified webhooks.
  • AI Shopping Assistant & Subscription Control: Includes budget-aware catalog quotes, immutable PurchaseSnapshot agreements prior to checkout, and transparent subscription renewal reminders and cancellations.

How we built it

We architected VelaPal V6.1 with strict trust boundaries across three services and a shared contract package:

  • Frontend (apps/web — Next.js, TypeScript, Tailwind CSS): Built around the calm, accessible VelaPal design system (#0B326D Navy, #0871E8 Action Blue, Geist typography, responsive 360px to 1440px layouts). Implements role-isolated workspaces, explicit state indicators (Loading, Pending, Unknown, Succeeded), and optimistic concurrency headers.
  • Business & Authorization API (apps/api — Express.js, TypeScript, PostgreSQL): Owns identity (Argon2id, HttpOnly __Host-velapal cookies, CSRF and Origin verification, purpose-bound MFA step-up challenges), RBAC, the Consent Ledger, transactional outbox and webhook inbox workers, and the PayPal Executor. All monetary values are handled in integer minor units (5900 = USD 59.00).
  • AI Orchestrator (apps/ai — Python, FastAPI, LangGraph, Google Gemini, Pydantic, Qdrant): Replaces noisy multi-agent debates with one auditable LangGraph state machine (intake → gather → synthesize → mediate → propose) persisted via langgraph-checkpoint-postgres. Retrieval in Qdrant enforces strict pre-query payload filtering (tenant_id, case_id, audience, accessRevision) and re-verifies ACLs before context assembly.
  • Three-Axis State Machine & Multi-Counter Concurrency: Every dispute case tracks three independent axes—Stage (AWAITING_EVIDENCE through RESOLVED), Control (RUNNING, WAITING_ADMIN, PAUSED, MANUAL), and Provider Operation Status (IDLE, PENDING, SUCCEEDED, FAILED, UNKNOWN, UNAVAILABLE)—paired with granular If-Match version counters (caseVersion, controlVersion, sourceVersion, proposalVersion, privateContextVersion, and accessRevision).

Challenges we ran into

  1. Preventing Version Collisions Across Concurrent Actions: Early on, if an Admin paused a case or a user saved a private note while the other party was reviewing a settlement proposal, a single global version counter would unfairly invalidate party consents. We solved this in V6.1 by splitting concurrency into six dedicated counters (caseVersion only increments on shared material changes, while controlVersion handles Admin interventions and privateContextVersion handles private drafts).
  2. Eliminating Stale AI Checkpoints & Revoked Evidence Leaks: What happens if a party shares evidence, an AI assessment starts running, and the party revokes that evidence mid-flight? We designed a cryptographically signed manifest and monotonic accessRevision check on POST /internal/v1/case-runs/:id/checkpoints. If caseVersion or accessRevision changes while the model is running, Express rejects the checkpoint with 409 STALE_CONTEXT and schedules a durable Qdrant purge.
  3. Handling Payment Ambiguity Honestly: Network timeouts during a refund or capture cannot be treated as simple errors—retrying blindly risks double-refunding. Building the EXECUTION_UNKNOWN state and a dedicated POST /api/v1/operations/:id/reconcile flow required careful idempotency and ledger locking so one agreement produces at most one financial effect.

Accomplishments that we're proud of

  • A Frozen, Production-Grade V6.1 Contract: Our Frontend, Backend, and AI layers communicate through a unified specification with zero header/body version duplication and unbroken lifecycle trace fixtures (case_vp_0421, VP-0422, VP-0423).
  • True Privacy & Least Privilege: Even supervisors cannot snoop on unshared PRIVATE party preparation drafts, and AI tools never receive raw database credentials, shell access, or PayPal secrets.
  • Verifiable Fairness Design: Our architecture enforces neutral attribution ("Customer states" vs. "Seller explains"), highlights missing evidence instead of guessing fault, and prevents prompt injection inside uploaded documents from ever gaining tool authority.

What we learned

  • One deterministic orchestrator beats a multi-agent debate: In high-stakes financial and dispute workflows, users and auditors need traceable source citations, schema-validated findings, and clear uncertainty—not four AI personas arguing with each other.
  • Consent is a specific contract, not a boolean: Approving AI mediation to continue is fundamentally different from agreeing to settlement terms or authorizing a fund transfer. Binding every consent to a paramsHash, caseVersion, and stepUpId makes financial execution safe by construction.

What's next for VelaPal

  • Controlled Sandbox Pilot (V2): Expanding live malware and OCR scanning pipelines, automated SLO deadline schedulers, and full PayPal Sandbox webhook replay testing across multi-merchant accounts.
  • Expanded Provider Capabilities: Supporting physical return-and-replacement tracking, official PayPal dispute evidence packet handoffs when internal mediation does not reach consensus, and automated 60-case adversarial fairness evaluations before production launch.

Built With

Share this project:

Updates

Submission history