← Research & specs
AdPilot · Corpus

Runbook — running AdPilot locally

Runbook — running AdPilot locally

All commands from the repository root. Node ≥ 20 (built with Node 22).


1. Mobile app (Expo — iOS, Android, Web)

cd apps/mobile
npm install            # first time only
npx expo start         # Metro dev server

Then press:

Or scan the QR code in the terminal with Expo Go on your physical phone (same Wi-Fi).

The app seeds demo data on first launch: two running campaigns with 2 weeks of history, alerts, and a welcome chat message. No API keys or accounts needed.

Verify everything (CI does the same)

npm run typecheck      # tsc --noEmit, strict
npm test               # vitest — 22 engine tests (planner, content, optimizer, metrics, seed)
npx expo export --platform web      # production web bundle → dist/
npx expo export --platform android  # android JS bundle check

Optional: connect a real LLM

Settings → AI engine → switch to Live → enter any OpenAI-compatible base URL + key + model (OpenAI, Azure OpenAI, OpenRouter, Groq, a local Ollama endpoint…). Any failure falls back to the on-device demo engine automatically.

2. Backend agent-gateway

cd apps/backend
npm install
cp .env.example .env   # edit: add OPENAI_API_KEY to enable the live LLM path
npm run dev            # http://localhost:8787

Smoke test:

curl localhost:8787/health
curl -X POST localhost:8787/api/plan \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Launch a $500 sales campaign for my candle shop"}'
curl -X POST localhost:8787/api/launch \
  -H 'Content-Type: application/json' \
  -d '{"name":"Candle Shop","goal":"sales","durationDays":14,
       "audienceDescription":"Home & living enthusiasts",
       "budgetSplit":[{"platform":"meta","amount":300},{"platform":"google","amount":200}]}'
npm run typecheck && npm test   # backend tests

3. Project layout

apps/mobile/src
├── app/                 # expo-router routes
│   ├── (tabs)/          # dashboard, copilot, campaigns, studio, settings
│   └── campaign/[id]/   # campaign detail
├── lib/                 # the engine (see docs/07-architecture.md)
│   ├── planner.ts       #   prompt → plan (intent, parsing, budget split)
│   ├── content.ts       #   creative generation per platform
│   ├── optimizer.ts     #   rebalancing, alerts, reports
│   ├── metrics.ts       #   deterministic delivery simulation
│   ├── adapters.ts      #   AdPlatformAdapter interface + sandbox impls
│   ├── aiClient.ts      #   optional live LLM
│   └── store.ts         #   Zustand store + persistence + agent actions
├── components/          # UI kit (cards, charts, chat bubbles)
└── theme.ts
apps/backend/src         # Hono gateway: /api/plan, /api/launch, /api/budget

4. Troubleshooting

Symptom Fix
expo start port busy npx expo start --clear --port 8081
Tests fail on a fresh clone run npm install inside apps/mobile first; tests need no device
iOS Simulator doesn't open Xcode → Settings → Command Line Tools set; or use Expo Go on a phone
Web export empties after an android export both write dist/; re-run the web export last
Live-LLM mode silent fallback check Settings → AI engine values; all errors fall back by design