D2C AI Employee

The Problem

Most D2C founders run their business on vibes and stitched-together Excel sheets. They know something is leaking margin — they just can't tell if it's the courier, the payment gateway, or the ad spend. Each system (Shopify, Razorpay, Shiprocket, Meta Ads) looks fine in isolation. The losses only show up in the joins.

What We Built

D2C AI Employee is a single autonomous agent that watches all four systems simultaneously and surfaces actionable alerts with row-level citations — so you know exactly which orders, which zones, and which campaigns are burning money.

Core Features

• Real-time metric monitoring: RTO rate, ROAS, settlement gaps, delivery SLAs
• Two-phase agent architecture: Fast SQL aggregation first, LLM validation only when thresholds breach — keeping costs sane at scale
• Citations, not hallucinations: Every stat maps back to a source_row_ref in the DB; the LLM's output is validated against actual computed values before it reaches the user
• Chat interface: Ask natural-language questions ("Why is Zone 5 bleeding money?") and get answers backed by live data

Architecture

SaaS Sources → FastAPI Connectors → Batched Upserts → Supabase (PostgreSQL) ↓ Agent Engine (Python Scan + GPT-4o-mini) ↓ React + Tambo AI Dashboard ← FastMCP Tools

• Phase 1 (Python Scan): SQL aggregates 6 core metrics per merchant. No LLM. Fast.
• Phase 2 (LLM Validation): Only breached metrics hit the LLM, which outputs plain-English recommendations like "Shift BlueDart Zone 5-6 orders to Delhivery to save ₹42,000/mo."

Why These 4 Connectors?

Together they let you calculate actual profitability. Shopify says the order was placed — Razorpay tells you if the money ever arrived. Shiprocket RTOs it and you're out the shipping cost. Meta Ads acquired the customer at 3x what they spent.

Schema Design

Flat, denormalized tables (orders, payments, deliveries, meta_ads) with source_row_ref as the idempotent conflict key and citation anchor. Every aggregated stat traces back to a specific row. Tenant isolation via Row Level Security on merchant_id.

Challenges We Faced

• Real-time sync: Pagination blocks the event loop on large order histories. Fix: Shopify webhooks (orders/create) would be the right long-term solution.
• Silent credential failures: If a merchant's API keys are wrong, the sync fails with no UI feedback. Needs better error propagation.
• Mock data limitations: Shiprocket and Meta Ads are mocked deterministically (real APIs require merchant-level OAuth + App Review). ROAS calculation uses proportional attribution — a real build needs UTM mapping or Conversions API.

What We Learned

• Cost control matters: Feeding every row to an LLM is a budget suicide. The two-phase scan → validate pattern is the difference between a demo and a product.
• Trust is everything: An AI agent reporting wrong numbers is worse than no agent. The _validate_recommendations layer — silently dropping hallucinated metrics — was the most important 20 lines we wrote.
• Citations aren't optional: Business owners don't trust black-box AI. Mapping every stat to a source_row_ref builds auditability into the architecture from day one.

What's Next

• Replace Shiprocket mock with real OAuth integration
• Redis queue for background syncs (replace blocking HTTP calls)
• One-tap actions: pause a Meta campaign, pull a product, switch a courier zone — directly from the recommendation
• Role-based team workspaces: route "pause this campaign" to the Product Manager, "follow up on RTOs" to the Sales Manager

Built With

• fastapi
• fastmcp
• gpt-4o-mini
• pg-cron
• python
• razorpay-python-sdk
• react
• shopify-rest-api
• supabase-(postgresql)
• tambo-ai
• typescript