SoA Platform — Monorepo

Agent Commerce Command Center. Measures Share of Algorithm across AI shopping agents.

Structure

packages/
  shared/               Python package shared by both apps
    soa_shared/         Models, database, config
                        → pip install -e packages/shared

apps/
  api/                  FastAPI + React frontend → Deploy to Vercel
    api/
      index.py          Vercel serverless entry point (imports app only)
    app/
      app.py            FastAPI application
      schemas.py        Pydantic request/response models
      routers/
        studies.py      GET /api/studies, /api/studies/{type}/queries
        entities.py     GET/POST /api/entities
        cycles.py       GET/POST /api/cycles, /api/cycles/check
    web/                React/Vite frontend
      src/
        App.jsx         View routing (dashboard ↔ wizard)
        api.js          API client
        components/
          CycleDashboard.jsx   Cycle management page
          NewCycleWizard.jsx   5-step new cycle wizard
    requirements.txt
    vercel.json

  pipeline/             Pipeline runner + worker → Deploy to Railway
    orchestrator/       PipelineOrchestrator (runner → coding → metrics)
    runners/            ChatGPT, Gemini, Claude, Perplexity runners
    parser/             Response coding and validation
    metrics/            Metrics calculation and xlsx export
    seeds/              Query and entity seed scripts
    alembic/            Database migrations
    worker.py           Polling worker (polls soa_cycles every 30s)
    main.py             CLI entry point
    railway.toml
    requirements.txt

Architecture

The API and pipeline communicate ONLY through the database.

Browser → Vercel (apps/api)
  POST /api/cycles
  → writes soa_cycles status='planned'
  → returns 201 immediately

Railway (apps/pipeline/worker.py)
  → polls soa_cycles every 30s
  → picks up status='planned'
  → runs PipelineOrchestrator
  → updates status='complete'

Local Development

1. Shared package

cd packages/shared
pip install -e . --break-system-packages

2. Pipeline worker

cd apps/pipeline
pip install -r requirements.txt --break-system-packages
cp .env.example .env  # fill DATABASE_URL
python worker.py      # start polling
# or use CLI directly:
python main.py pipeline --cycle 2026-05 --study-type retailer_sephora

3. API + Frontend

cd apps/api
pip install -r requirements.txt --break-system-packages
cp .env.example .env  # fill DATABASE_URL
uvicorn app.app:app --reload --port 8000 &
cd web && npm install && npm run dev
# Frontend: http://localhost:5173
# API:      http://localhost:8000/api

Deployment

Vercel (apps/api)

1. Connect repo to Vercel
2. Set Root Directory: apps/api
3. Set env vars:
   • DATABASE_URL_POOLED (Supabase Transaction pooler URL)
   • USE_POOLED_DB=true
   • the email vars below

Email env vars

Both outbound senders in apps/api (app/services/demo_request_email.py and app/services/lead_notification_email.py) post to Resend's HTTP API directly. Neither ever raises: if RESEND_API_KEY or EMAIL_FROM is missing they log a warning, return False, and the request they hang off succeeds anyway — so a missing var degrades to "no notification", never to a failed submission.

Var	Used by	Default if unset
RESEND_API_KEY	both senders	none — no email is sent
EMAIL_FROM	both senders	none — no email is sent
LEAD_NOTIFY_EMAIL	both audit notifications — audit-started (a visitor starts an audit run) and new-audit-lead (they later enter their email)	falls back to DEMO_REQUEST_NOTIFY, then [email protected]
DEMO_REQUEST_NOTIFY	demo-request notification (the "Book your walkthrough" / "Talk to us about TrueSync" form)	[email protected]
PUBLIC_AUDIT_BASE_URL	the report link inside every notification	https://parleo.io/audit

LEAD_NOTIFY_EMAIL exists so audit notifications can be routed to a different alias than demo requests; leave it unset to send both to the same place.

Note on volume: an audit-started email goes out for every accepted POST /api/public/soa-lite, not only for runs that become leads. The per-IP and global rate limits in public_lite.py are the only cap on how many that can be. They're configurable via env vars RATE_LIMIT_PER_IP_HOUR (default 3), RATE_LIMIT_PER_IP_DAY (default 10) and GLOBAL_RATE_LIMIT_PER_HOUR (default 20). Rejected requests — failed captcha, tripped rate limit — send nothing, since they raise before the row is written.

Railway (apps/pipeline)

1. Connect repo to Railway
2. Set Root Directory: apps/pipeline
3. Start command: python worker.py
4. Set env vars:
   • DATABASE_URL (Supabase direct connection)
   • USE_POOLED_DB=false
   • OPEN_AI_API_KEY
   • GEMINI_API_KEY
   • PERPLEXITY_API_KEY
   • ANTHROPIC_CLAUDE_API_KEY