Mandatory Compliance Disclosure: AegisFlow Rental is built on the official PayPal Braintree Sandbox (sandbox.braintreegateway.com — using PayPal, Venmo, Security Deposit Holds, Partial Settlement, and Automated Dispute Representment APIs per Official Rules Section 4, confirmed in writing by Hackathon Judge Eddie Jaoude and Organizer Janet on Discord).

Inspiration: The $15,000 Rental Trust Problem

Independent camera, lighting, and AV rental houses ship $15,000 cinema kits on tight turnarounds. Every rental creates two painful bottlenecks:

  1. Before dispatch: Staff have to manually verify whether a security deposit authorization hold actually cleared before handing a camera rig out the door.
  2. At return check-in: When a kit comes back with a broken shotgun microphone mount or a missing high-speed SDXC card, calculating the deduction, capturing part of the security deposit, fixing tomorrow's colliding booking, and defending the inevitable chargeback dispute are completely disconnected across spreadsheets, payment portals, and email threads.

I built AegisFlow Rental to connect physical equipment scheduling, AI return inspection, objective third-party retail replacement pricing, policy-gated partial deposit capture, and chargeback representment into one continuous operational loop.

What It Does (The 6-Step Closed Loop)

  1. Step 1 — Deposit Hold & Dispatch Gate (PayPal Braintree + Bryntum Scheduler): Authorizes a $1,500.00 security deposit hold (submitForSettlement: false) before unlocking equipment dispatch on the 7-day fleet timeline. If a $2,000.00 hold declines in Braintree (2000: Do Not Honor), the server blocks dispatch automatically. Every transaction ID can be verified live against the Braintree Sandbox API directly in-app.
  2. Step 2 — Multimodal Return Inspection (AWS Bedrock Amazon Nova Pro): Compares pre-rental handover records against return check-in notes and photos, flagging a damaged Rode NTG5 Shotgun Microphone (automatically checking the 48-hour maintenance quarantine flag) and a missing SanDisk 128GB Extreme PRO SDXC Card. Nothing advances until the human yard inspector signs off.
  3. Step 3 — Objective Retail Valuation (Channel3 Catalog API): Queries POST https://api.trychannel3.com/v1/search to fetch live third-party retail replacement listings ($53.80 on newegg.com and $639.00 on bhphotovideo.com) and locks the timestamped merchant URLs as price proof before any money is captured.
  4. Step 4 — Deterministic $100.00 Policy Gate & Partial Settlement (PayPal Braintree): A pure TypeScript policy gate routes locked items <= $100.00 ($53.80 SDXC card) to immediate automated child capture via gateway.transaction.submitForPartialSettlement, while holding items > $100.00 ($639.00 shotgun mic) behind a 1-click Finance Approver card. Once settled, the ledger accounts for the $692.80 captured across both child transactions and the $807.20 uncaptured remainder on the $1,500.00 hold.
  5. Step 5 — 48-Hour Maintenance Quarantine & Conflict Resolution (Bryntum Scheduler + Amazon Nova): Inserts a 48-hour bench repair block on Sony FX6 Cinema Kit Unit #1, deterministically detects the schedule overlap with tomorrow's confirmed shoot (BK-9024), uses Amazon Nova to explain the safest eligible backup unit (Sony FX6 Backup Unit #2), and reassigns the booking on the Bryntum timeline in one click.
  6. Step 6 — Grounded Chargeback Defense & Live BI (Braintree Disputes API + AG Studio 3.1): Simulates a customer chargeback in Braintree Sandbox, uses Amazon Nova Pro to draft a 4-section representment brief verified against stored session records, and submits the brief to Braintree (dispute.addTextEvidence + dispute.finalize). All 6 relational tables (customers, assets, bookings, transactions, inspections, disputes) stream live into AG Studio 3.1 with a custom DepositHealthWidget and a streaming Nova BI assistant.

How I Built It

[Next.js 14.2 App Router UI]
  ├── Tab 1: Bryntum Scheduler 7.3.8 Timeline + 6-Step Operations Cockpit
  └── Tab 2: AG Studio 3.1 Canvas + DepositHealthWidget + Custom AgLlmAdapter
         │
[17 Server-Only /api/* Route Handlers + Upstash Redis Session Store & Mutex Locks]
  ├── PayPal Braintree Node SDK v3.35 (Auth Holds, Partial Settlements, Disputes, Live Verify)
  ├── AWS Bedrock SDK (Amazon Nova Pro us.amazon.nova-pro-v1:0 & Nova Lite Converse/Stream)
  ├── Channel3 REST API (Live Retail Replacement Search & Merchant URL Locking)
  └── Pure Deterministic Guardrails (Integer-Cent Money Engine, $100 Gate, Evidence Validator)
  • PayPal / Braintree Integration: Built on [email protected] against sandbox.braintreegateway.com. Uses gateway.transaction.sale({ options: { submitForSettlement: false } }) for deposit holds, gateway.transaction.submitForPartialSettlement() for itemized child captures, gateway.transaction.find() and gateway.dispute.find() for live in-app gateway inspection, and gateway.dispute.addTextEvidence() + gateway.dispute.finalize() for representment.
  • AWS Bedrock Amazon Nova: Uses us.amazon.nova-pro-v1:0 (with automatic failover to us.amazon.nova-lite-v1:0) via @aws-sdk/client-bedrock-runtime (ConverseCommand and ConverseStreamCommand). Untrusted customer return notes are isolated inside <untrusted_record> tags, and all monetary decisions remain strictly server-side in integer cents.
  • AG Grid / AG Studio 3.1: Binds all 6 normalized operational tables with many-to-one foreign-key relationships, custom Dark Cinema theming (studioTheme.withParams), a custom DepositHealthWidget registered via createWidgets, a read-only check_dispute_evidence_readiness tool, and a custom AgLlmAdapter streaming turns from /api/ai/nova-stream.
  • Bryntum Scheduler: Renders the 7-day fleet resource timeline (@bryntum/[email protected]) with accessible non-color-only status badges and server-locked mutation guards so client-side dragging cannot bypass a declined deposit hold.
  • Channel3 & OpenAPI 3.1 / Postman: Live retail replacement lookups via api.trychannel3.com/v1/search with automatic retry resilience, documented across an 808-line OpenAPI 3.1.0 specification (/openapi.yaml) and a Postman v2.1 collection (/postman_collection.json).

What Is Live vs. Sandbox Simulation (Transparency Statement)

  • 100% Live Cloud API Calls: Every Braintree hold, processor decline (2000: Do Not Honor), child partial settlement, dispute evidence upload, Channel3 retail catalog lookup, Amazon Nova Pro analysis, and Upstash Redis session write executes over live HTTPS against real cloud endpoints.
  • Documented Braintree Sandbox Triggers:
    1. In Braintree Sandbox, transitioning an open dispute to Won programmatically requires submitting Braintree's documented test string compelling_evidence alongside the representment brief before calling dispute.finalize(). Our UI displays a permanent disclosure banner explaining this sandbox behavior; in production, issuing banks adjudicate submitted evidence manually over card-network timelines.
    2. To open an instant sandbox dispute without waiting for real-world bank chargeback cycles, Step 6 triggers a sandbox dispute using Braintree's documented instant-dispute test parameters (fake-venmo-account-nonce at $62.01 or Visa dispute test card 4023898493988028) and explicitly reconciles any delta against the locked Channel3 item price in the UI and evidence validator.
  • Evaluation Waivers: Uses @bryntum/[email protected] (45-day public evaluation trial) and [email protected] under the official hackathon evaluation waiver.

Challenges I Ran Into & How I Solved Them

  1. Native Partial Settlement Across Sandbox Payment Rails: Braintree's submitForPartialSettlement is supported specifically on PayPal and Venmo authorizations. After enabling Venmo in the Braintree Sandbox merchant settings, I built a multi-tier gateway wrapper in src/lib/braintree/client.ts that executes native submitForPartialSettlement child captures on Venmo/PayPal holds and includes an automatic vaulted-customer child capture fallback if a merchant account has not enabled PayPal/Venmo yet.
  2. Preventing Double-Click & Two-Tab Settlement Race Conditions: Braintree does not enforce idempotency keys on rapid back-to-back submitForPartialSettlement calls. I implemented an atomic distributed action lock (acquireActionLock using Upstash Redis SET NX PX with in-memory fallback) around /api/braintree/hold, /api/braintree/settle-partial, and /api/braintree/dispute/submit, verified with parallel Promise.all race tests in Vitest ([200, 409]).
  3. Zero-Hallucination Financial Evidence: LLMs should never invent transaction IDs or dollar figures in legal chargeback briefs. I wrote a deterministic post-generation validator (src/lib/domain/evidence-validator.ts) that parses every $ amount in Amazon Nova's draft and rejects any number not matching the session's whitelisted integer-cent records ($1,500.00 hold, $750.00 rental fee, $53.80 / $639.00 Channel3 prices, and $62.01 sandbox dispute trigger).
  4. Next.js SSR Compatibility with Canvas Libraries: Both Bryntum Scheduler and AG Studio 3.1 measure browser DOM APIs (window, ResizeObserver) on import. Wrapping their inner canvas components in next/dynamic(..., { ssr: false }) allowed all 22 static and dynamic routes to compile cleanly in Next.js 14.2 production builds.

What I Learned & What's Next

Building AegisFlow Rental taught me how to design bounded AI architectures for financial operations—where multimodal LLMs handle unstructured inspection notes and evidence drafting, while deterministic integer-cent state machines govern actual payment captures. Next, I plan to add Braintree webhook listeners (dispute_opened, dispute_won, transaction_settled) and multi-location warehouse barcode scanning.

License

Released under the MIT License (OSI-Approved Open Source License) — see /LICENSE in the repository root.

Built With

Share this project:

Updates

Submission history