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:
i— open the iOS Simulator (macOS + Xcode required)a— open an Android Emulator (Android Studio required)w— open in a web browser
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 |