Architecture
How the Sherpa system components connect and communicate.
System overview
Basecamp ──webhooks──→ Agent (Railway, Docker)
↕ Claude Code CLI
User ──browser──→ Console (Railway, Node.js)
↕ Supabase (Cloud)
↕ LemonSqueezy (Payments)
Console ──provision_jobs──→ Worker (Railway)
↕ Railway API (provisions agent instances)Agent
Railway (Docker) — Receives Basecamp webhooks, runs Claude
Console
Railway (Node.js) — Dashboard for managing instances
Worker
Railway (Node.js) — Provisions/destroys agent instances on Railway
Database
Supabase Cloud — Auth, user data, job queue
Data flow
- User signs up on the Console and creates an instance
- Console redirects to LemonSqueezy for payment
- On payment success, LemonSqueezy webhook triggers a
provision_jobsentry in Supabase - Worker polls for pending jobs, calls the Railway API to deploy a Docker container
- Worker reports the instance status back to Console
- The running Agent receives Basecamp webhooks (via Hookdeck), processes them with Claude, and posts replies back to Basecamp
Logs
| Component | Where |
|---|---|
| Agent webhook logs | /root/.logs/ in the container (date-stamped JSON files) |
| Agent deduplication | /root/memory.json |
| Console | Railway service logs |
| Worker | Railway service logs (stdout shows poll results) |
| Database | Supabase dashboard → Logs |