Inspiration

Small and mid-sized online merchants who sell physical products and get paid through PayPal live in two disconnected worlds: their products and stock live in spreadsheets or a basic storefront, while their money lives in PayPal. While studying independent diaspora and artisan food brands—modeled around our reference merchant, Spice Route · Artisan West African Pantry—I noticed five compounding operational blind spots:

  1. The Revenue Illusion: A merchant sees $3,193.60 in gross PayPal sales and thinks they had a profitable month—until weighted-average Cost of Goods Sold (COGS), PayPal's 3.49% + $0.49 capture fees, customer refunds, shipping supplies, and monthly team salaries quietly eat the margin.
  2. Surprise Stockouts: Best-selling SKUs (like Smoky Suya Spice Rub or Hibiscus Zobo Loose Leaf) run out of stock because storefront checkouts aren't wired to a live days-of-cover and supplier Purchase Order (PO) engine.
  3. Opaque PayPal Liquidity: Cash is split across unpaid B2B wholesale invoices, PayPal clearing holds, chargeback reserves, available balance, and committed outflows.
  4. Manual Back-Office Errands: Chasing late wholesale buyers, recovering soft card declines, assembling chargeback evidence before PayPal's deadline, and running monthly staff payroll take hours of repetitive admin work every week.
  5. Untrusted AI Automation: Merchants want an AI assistant that can actually do the legwork—not just chat—without ever hallucinating a financial figure or disbursing a single dollar without permission.

I built PekuliarPal to be that trusted AI back-office errand assistant: a unified, industrial-calm operating system where every storefront checkout, SKU movement, PayPal transaction, and AI action is reconciled in real time.

What it does

PekuliarPal unifies a live customer-facing e-commerce storefront with a 14-screen AG Grid Enterprise merchant console and Pekuliar, an embedded context-aware AI shop assistant:

  1. Live Customer Storefront (/shop) → Real-Time Console Sync: Customers browse artisan West African spices, filter by category, unlock free shipping, and check out via PayPal Sandbox. Each checkout immediately creates a live order in the merchant console, deducts SKU inventory in stock_movements, records weighted-average COGS and exact PayPal capture fees, and updates the merchant's P&L and PayPal balance.
  2. Executive Overview & 5-Stage PayPal Liquidity Pipeline (/): Tracks every dollar across five stages: 1. Awaiting Payment → 2. In PayPal Clearing → 3. Hold / Dispute Reserve → 4. Available in PayPal → 5. Committed Outflows, alongside responsive KPI sparklines and period filters (Last 7 Days, Month-to-Date, Last Month).
  3. High-Density AG Grid Enterprise Workbenches: Orders (/orders) & Invoices (/invoices): Retail fulfillment, carrier tracking sync, and B2B wholesale invoicing with algorithmic client lateness scoring and escalating reminders.
  4. Products (/products) & Inventory (/inventory): Full SKU catalogue with unit margin bars, 30-day velocity sparklines, days-of-cover health chips, immutable stock movement logs, and supplier Purchase Orders.
  5. Payments & Heuristic Reconciliation (/payments): Reconciles every PayPal sale, fee, refund, and payout—using heuristic confidence matching (96% confidence) to link unmatched Guest Express checkouts to exact SKU combinations.
  6. Payroll (/payroll), Expenses (/expenses) & Audited GAAP Reports (/reports): Batch salary disbursements via PayPal Payouts, overhead tracking, and an audited Statement of Profit & Loss waterfall.
  7. Protect Suite (/failed-payments & /disputes): Classifies soft vs. hard payment declines for smart retry recovery and drafts fact-locked PayPal chargeback evidence packs with win-odds scoring.
  8. Control Suite (/rules, /audit, /settings): Action-level Autonomy Matrix (Autopilot, Ask First, Never), disbursement dollar caps, an Interactive Policy Gate Simulator, an immutable Audit Log, and persistent AI Memory configuration.
  9. Pekuliar AI Shop Assistant: Docked on the right side of the console with Chat, Errands, and Approvals tabs. Pekuliar executes 10+ typed tools, runs multi-step background errands (such as a Morning Sweep across overdue invoices and low-stock SKUs), learns persistent business facts in its Memory Ledger (e.g., "Remember that Kano Spice Cooperative gives 8% off at 60+ jars"), and stages money-moving actions through a deterministic Policy Gate.

How I built it

  1. Frontend & Workspace Architecture: Built on Next.js 16.4 (App Router + Turbopack), React 19, TypeScript 5, and Tailwind CSS v4. We designed an "Industrial Calm" visual system anchored in deep Spruce (#0b2b26), Fern (#2f8f5b), and Marigold (#e8a800), pairing Bricolage Grotesque display headings with Instrument Sans and tabular JetBrains Mono numerals.
  2. AG Grid Enterprise & AG Charts Enterprise: Powers all 10+ operational ledgers with custom cell renderers, row grouping, status bars, master/detail drawers, inline velocity sparklines, and CSV exports.
  3. AI Brain & Fact-Locked Tool Execution: Powered by Google Gemini (@google/genai) with 10+ strongly-typed function declarations (get_profit_breakdown, get_stock_levels, draft_purchase_order, pay_supplier, run_payroll, issue_refund, remember_fact, get_team_overview, get_merchant_suggestions) backed by a deterministic local execution engine so the assistant responds instantaneously even offline.
  4. Deterministic Policy Gate (src/lib/agent/policy.ts): Every money-moving tool call is intercepted by a policy evaluator that checks the action's autonomy level (autopilot, ask, off) against daily outflow caps ($2,500), single-payee caps ($500), auto-refund limits ($150), and first-time recipient gates.
  5. PayPal REST APIs & Idempotent Webhooks: Integrates PayPal OAuth2, Orders v2, Invoicing v2, Payouts, and Disputes APIs, with a cryptographic webhook router (/api/webhooks/paypal) that deduplicates event deliveries and logs replayable errors.
  6. Data Layer & Testing: Backed by PostgreSQL 17 + Drizzle ORM (db/schema.sql) wrapped in a resilient proxy that falls back seamlessly to rich in-memory Spice Route fixtures. Verified by 496 automated unit and integration tests across 15 test suites.

Challenges I ran into

  1. AI Hallucination: LLMs naturally try to estimate numbers or embellish chargeback replies. I solved this by forcing every query through typed read tools and building a fact-locked verifier that rejects any drafted recovery or dispute message containing a dollar amount or date not present in verified ledger events.
  2. Reconciling the Customer Checkout with Back-Office Application: Probably my most difficult challenge was trying to simulate a customer checkout that accepts money and the Back-Office application captures all the order details. I had to wire the /shop checkout so it simultaneously updates SKU stock cover, appends an immutable stock_movements row, calculates the exact PayPal capture fee, and updates the GAAP P&L waterfall required a unified reactive store across all 14 routes.
  3. Non-Blocking Route Transition Feedback in Next.js 16: High-density enterprise grids carry heavy component trees, this sometimes require the application to take time in fetching information. I engineered a custom branded PekuliarSpinner—featuring a rotating Pekuliar Pal logo inside a dual-orbital rolling gradient arc—triggered via a bubble-phase click listener that gives immediate visual feedback on every route transition without interrupting Next.js's internal link router.

Accomplishments that we're proud of

  1. A True Closed-Loop Merchant OS (Storefront → Stock → PayPal → GAAP P&L): We didn't build a static dashboard mockup. A single customer checkout on our live storefront (/shop) captures a PayPal Orders v2 payment, deducts physical SKU units, logs an immutable stock movement, calculates exact weighted-average COGS and 3.49% + $0.49 PayPal merchant fees, and updates the Net Profit waterfall across all 14 operational screens in real time.
  2. Zero-Hallucination Financial AI with Deterministic Policy Gates: We engineered Pekuliar (@google/genai) so that the LLM never invents financial numbers—every figure comes from 10+ typed SQL/PayPal tools. Better yet, every money-moving action (payroll disbursements, supplier PO payouts, customer refunds, and invoice reminders) passes through a deterministic Action-Level Autonomy Matrix (Autopilot / Ask First / Never) with configurable dollar caps before a single cent moves.
  3. Institutional-Grade Financial Density with "Industrial Calm" Ergonomics: We integrated AG Grid Enterprise 36.2 and AG Charts Enterprise across 10+ master-detail ledgers—complete with inline 30-day SKU velocity sparklines, a 96%-confidence Heuristic Reconciliation Workbench for orphaned guest checkouts, and an automated PayPal Dispute Defense Engine that calculates Expected Value (EV) before merchants spend time fighting a claim.
  4. 496 Passing Automated Tests Across 15 Suites: We backed our financial math, GAAP accounting engine, PayPal webhook idempotency (SHA-256 payload hashing), and every permutation of the Policy Gate (action × autonomy level × dollar cap × amount) with 496 unit and integration tests (100% pass rate) plus zero-config resilient fallback so judges can test every workflow immediately.

What we learned

  1. Autonomy is a spectrum, not a toggle: Merchants don't want "all manual" or "blind autopilot." Giving the user an explicit Action-Level Autonomy Matrix paired with dollar caps—and an Interactive Policy Gate Simulator to test rules before they go live—builds genuine trust in agentic finance.
  2. Context-aware UX beats generic chat: Hiding the AI chatbot on the customer storefront while docking it on the merchant console—complete with de-duplicated screen-aware prompt suggestions that hide while typing or fetching—makes the assistant feel like a disciplined colleague rather than a noisy widget.
  3. AI Systems can reduce workload and time: One of the lessons I learned in building this project was the speed at which the system resolved issues. Disputes that will take painstaking manual processes where cut drastically. The merchant was also eased of many repetitive, boring and stressful tasks like taking stock of inventory, paying salaries one by one, calculating profits etc.

What's next for PekuliarPal Merchant Application

  1. Multi-Currency & Cross-Border Supplier Settlement: Automatic FX conversion tracking for African diaspora merchants paying cooperative suppliers in NGN, GHS, and KES while collecting USD/GBP/EUR in PayPal.
  2. Live Carrier Webhook Ingestion: Direct DHL, FedEx, and USPS tracking webhook ingestion so ITEM_NOT_RECEIVED PayPal disputes auto-attach proof-of-delivery PDFs the moment a claim opens.
  3. Demand Forecasting & Seasonal PO Autopilot: Using 90-day rolling velocity and holiday seasonality to pre-stage cooperative purchase orders weeks before stock cover drops.

Built With

Share this project:

Updates

Submission history