Call Goblin is an AI-assisted outbound call platform where users submit a mission and the backend places calls via company-managed telephony. This page covers setup, architecture, operations, security, billing, and launch readiness.

1. Install dependencies: cd backend && npm install
2. Set environment variables in backend/.env.
3. Start backend: npm run dev
4. Open: http://localhost:8787
5. Create account, complete intake, and dispatch a mission.

• Frontend: static app at web/index.html + web/app.js.
• Backend API: Node.js HTTP server in backend/server.js.
• Persistence: JSON/file-store by default, with strict-mode production gates that require Postgres readiness before launch.
• Session state: secure cookie sessions with server-side validation/store.
• Provider integrations: Stripe for billing, Vapi for telephony/voice.
• Asynchronous work: retries, reconciliation, and retention sweeps.

Core

• PUBLIC_BASE_URL, CORS_ORIGIN, TERMS_VERSION
• COOKIE_ONLY_AUTH, SESSION_TTL_MS
• USE_POSTGRES, DATABASE_URL, REDIS_URL
• FIELD_ENCRYPTION_KEY (base64, 32-byte key)

Vapi

• VAPI_API_KEY, VAPI_ASSISTANT_ID, VAPI_PHONE_NUMBER_ID
• VAPI_WEBHOOK_SECRET

Stripe

• STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
• STRIPE_PRICE_*, STRIPE_TAX_ENABLED

• Cookie-first authentication with optional strict mode via COOKIE_ONLY_AUTH=true.
• Email/password signup + login with abuse throttling and lockout controls.
• Email verification and password reset with expiring signed tokens.
• TOTP MFA setup, verify, and enable flow for account hardening.
• Session listing and revoke-all for account containment.

• Users submit scenario + authority + boundaries + escalation rules.
• Consent and terms acceptance are required before dispatch.
• Call jurisdiction is inferred server-side from destination area code with strict fallback to two-party mode when unknown.
• In two-party mode, the agent must disclose AI identity and ask recording/transcript consent before detailed collection.
• Missions follow explicit state transitions (queued, active, completed, blocked, failed).
• Event stream captures call updates, transcript outcomes, and evidence artifacts.
• High-risk and policy-restricted flows can be blocked or escalated to human review.

• Stripe manages subscription lifecycle and invoicing.
• Backend normalizes plan entitlements and monthly usage quotas.
• Metering is based on verified call outcomes, not mission form creation alone.
• Dunning and failed-payment states limit dispatch until recovery.
• Reconciliation jobs verify Stripe events against internal usage records.

Auth

• POST /auth/signup, POST /auth/login, POST /auth/logout
• GET /auth/sessions, POST /auth/revoke-all-sessions
• POST /auth/mfa/setup, POST /auth/mfa/enable, POST /auth/mfa/verify
• POST /auth/password-reset/request, POST /auth/password-reset/confirm

Missions

• POST /intake-scenarios/custom-generate (LLM-routed scenario drafts)
• POST /missions/dispatch, GET /requests, GET /requests/:id
• POST /requests/:id/start-vapi-call, POST /requests/escalate
• GET /requests/:id/vapi-events, GET /requests/:id/mission

Billing

• GET /metrics (health + runtime telemetry, including llmTelemetry routing counters).
• GET /billing/plans, GET /billing/entitlements
• POST /billing/checkout, POST /billing/portal
• POST /billing/webhook, GET /billing/reconcile-report (admin)

• Strict request validation on API inputs.
• Hardened headers, CORS allowlisting, and CSRF protections for cookie auth surfaces.
• Webhook signature verification + replay protection (event dedupe + timestamp tolerance).
• Sensitive fields encrypted at rest with key-managed encryption.
• Immutable audit events for consent and terms acceptance.
• Policy-sensitive call behaviors (AI disclosure + two-party consent ask) are enforced via server-generated mission prompt constraints.
• Rate limits and abuse controls for auth and dispatch endpoints.

• Preflight checks: cd backend && npm run preflight
• Migrations: npm run db:migrate
• Smoke tests: npm run smoke
• Security tests: npm run test:security
• Contract tests: npm run test:contract
• Billing reconcile runtime: npm run billing:reconcile:runtime

Does the browser get Vapi credentials?
No. Credentials stay server-side.

When is usage billed?
On verified billable outcomes, not mission drafts.

Can users control what the agent is allowed to do?
Yes. Authority, boundaries, and escalation instructions are explicit and required.

Can we enforce cookie-only auth?
Yes. Set COOKIE_ONLY_AUTH=true.