Lead Grabber / LeadLine AI (VoiceAgent AI Internal)

Current State

• Marketing site: root static files (index.html, style.css, script.js)
• Backend API foundation: backend/ (FastAPI + auth + migration)
• Dashboard app placeholder: frontend/

Start Backend

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
cp backend/.env.local.example backend/.env.local

Create database and run migration:

createdb voiceagent_dev
export DATABASE_URL='postgresql://localhost:5432/voiceagent_dev'
./backend/scripts/run_migration.sh

Run API:

cd backend
uvicorn app.main:app --reload

Or run by profile from repo root:

backend/scripts/start-profile.sh minimal

The profile runner loads profile defaults first, then backend/.env.local overrides.

Implemented Endpoints

• GET / service status
• GET /api/health
• GET /api/health/live
• GET /api/health/ready
• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/me
• POST /api/webhooks/twilio/voice/inbound
• POST /api/webhooks/twilio/voice/gather
• POST /api/webhooks/twilio/voice/status
• POST /api/webhooks/twilio/voice/lead
• GET /api/notifications/events (auth required)
• POST /api/notifications/retry (auth required)

Security and performance knobs are in backend/.env.example:

• TWILIO_AUTH_TOKEN for signature validation
• WEBHOOK_ASYNC_ENABLED + WEBHOOK_QUEUE_MAXSIZE for low-latency queued writes

Deployment profiles:

• backend/.env.minimal.example (Postgres only)
• backend/.env.scaled.example (Postgres + Redis)
• backend/scripts/start-profile.sh minimal|scaled
• backend/scripts/check-notifications-config.sh (validate local SMS/email env vars)
• backend/scripts/init-local-env.sh (create backend/.env.local)
• backend/scripts/retry-notifications.sh <email> <password> [max_events] (auth + retry endpoint helper)

Unified Release Gate

Run one command from repo root to verify backend + frontend release readiness:

scripts/release-check-all.sh

Useful options:

• --connectivity (checks provider connectivity in backend predeploy)
• --apply-migrations (applies SQL migrations using DATABASE_URL)
• --skip-backend-tests
• --require-live-frontend (requires hosted frontend API + NEXT_PUBLIC_DEMO_MODE=false)
• --frontend-api-base <url> (sets frontend API base for this run)
• --frontend-demo-mode <true|false|unset> (sets frontend demo mode for this run)
• --skip-frontend
• --skip-dead-code

Frontend live env template:

• frontend/.env.production.example

Backend URL (Render Quickstart)

Fastest path to get a backend URL:

1. Create a PostgreSQL service in Render.
2. Create a Web Service from this repo with:
   • Root Directory: backend
   • Build Command: pip install -r requirements.txt
   • Start Command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
3. Add env vars:
   • APP_ENV=production
   • JWT_SECRET_KEY=<long-random-secret>
   • NOTIFICATION_DRY_RUN=true
   • DATABASE_URL=<Render Postgres URL>
4. Health check path: /api/health

Then your backend URL is the Render web service URL (for example https://leadline-api.onrender.com).

Blueprint option (fastest):

1. Push this repo with render.yaml.
2. In Render: New + -> Blueprint.
3. Select the repo and apply.
4. Render provisions:
   • leadline-postgres (PostgreSQL)
   • leadline-api (Web Service)