​

Voice by aiConnected - Junior Developer PRD

​

Comprehensive Outline

​

PART 1: Foundation & Context

​

1. Project Overview

• 1.1 What We’re Building (plain English)
• 1.2 Why We’re Building It (business problem)
• 1.3 Who It’s For (target users)
• 1.4 Success Looks Like (measurable outcomes)

​

2. Glossary of Terms

• 2.1 Telephony Terms (PSTN, SIP, DTMF, IVR, PBX, etc.)
• 2.2 WebRTC Terms (ICE, STUN, TURN, SDP, etc.)
• 2.3 AI/ML Terms (LLM, STT, TTS, VAD, embeddings, etc.)
• 2.4 Platform Terms (tenant, agency, knowledge base, etc.)
• 2.5 Infrastructure Terms (container, webhook, WebSocket, etc.)

​

3. Architecture Overview

• 3.1 System Diagram (with explanation of each box)
• 3.2 Data Flow Narrative (step-by-step what happens on a call)
• 3.3 Technology Choices (what we’re using and WHY)
• 3.4 What We’re NOT Building (explicit scope boundaries)

​

4. Development Environment Setup

• 4.1 Required Accounts & API Keys
• 4.2 Local Development Tools
• 4.3 Repository Structure
• 4.4 Environment Variables Reference
• 4.5 How to Run Locally

​

PART 2: Database Design

​

5. Database Architecture

• 5.1 Why PostgreSQL
• 5.2 Database Naming Conventions
• 5.3 Common Patterns Used (UUIDs, timestamps, soft deletes)

​

6. Schema: Core Entities

• 6.1 agencies table (full DDL + field explanations)
• 6.2 tenants table (full DDL + field explanations)
• 6.3 users table (full DDL + field explanations)
• 6.4 user_roles and permissions tables

​

7. Schema: Telephony Entities

• 7.1 phone_numbers table
• 7.2 calls table
• 7.3 call_events table (state machine history)
• 7.4 call_transfers table

​

8. Schema: AI & Content Entities

• 8.1 knowledge_bases table
• 8.2 knowledge_documents table
• 8.3 knowledge_chunks table (with embeddings)
• 8.4 transcripts table
• 8.5 recordings table

​

9. Schema: Configuration Entities

• 9.1 voice_configurations table
• 9.2 agent_personalities table
• 9.3 greetings table
• 9.4 business_hours table

​

10. Schema: Billing & Analytics

• 10.1 usage_records table
• 10.2 billing_events table
• 10.3 call_analytics table

​

11. Indexes & Performance

• 11.1 Required Indexes (with explanations)
• 11.2 Partitioning Strategy
• 11.3 Query Patterns to Optimize For

​

12. Migrations

• 12.1 Migration File Naming Convention
• 12.2 Initial Migration Script
• 12.3 How to Add New Migrations

​

PART 3: API Design

​

13. API Architecture

• 13.1 REST vs GraphQL Decision
• 13.2 URL Structure & Naming
• 13.3 Authentication (JWT implementation)
• 13.4 Authorization (RBAC implementation)
• 13.5 Error Response Format
• 13.6 Pagination Standard
• 13.7 Rate Limiting

​

14. Agency Management APIs

• 14.1 POST /api/v1/agencies - Create agency
• 14.2 GET /api/v1/agencies/{id} - Get agency
• 14.3 PUT /api/v1/agencies/{id} - Update agency
• 14.4 GET /api/v1/agencies/{id}/tenants - List tenants
• 14.5 GET /api/v1/agencies/{id}/usage - Get usage

​

15. Tenant Management APIs

• 15.1 POST /api/v1/tenants - Create tenant
• 15.2 GET /api/v1/tenants/{id} - Get tenant
• 15.3 PUT /api/v1/tenants/{id} - Update tenant
• 15.4 DELETE /api/v1/tenants/{id} - Deactivate tenant
• 15.5 GET /api/v1/tenants/{id}/config - Get configuration
• 15.6 PUT /api/v1/tenants/{id}/config - Update configuration

​

16. Phone Number APIs

• 16.1 GET /api/v1/phone-numbers/available - Search available
• 16.2 POST /api/v1/phone-numbers - Provision number
• 16.3 GET /api/v1/tenants/{id}/phone-numbers - List tenant numbers
• 16.4 PUT /api/v1/phone-numbers/{id} - Configure number
• 16.5 DELETE /api/v1/phone-numbers/{id} - Release number

​

17. Call Control APIs

• 17.1 POST /api/v1/calls/outbound - Initiate call
• 17.2 GET /api/v1/calls/{id} - Get call status
• 17.3 POST /api/v1/calls/{id}/transfer - Transfer call
• 17.4 POST /api/v1/calls/{id}/hold - Hold call
• 17.5 POST /api/v1/calls/{id}/resume - Resume call
• 17.6 POST /api/v1/calls/{id}/hangup - End call
• 17.7 GET /api/v1/tenants/{id}/calls - List calls

​

18. Knowledge Base APIs

• 18.1 POST /api/v1/tenants/{id}/knowledge-base - Create KB
• 18.2 GET /api/v1/tenants/{id}/knowledge-base - Get KB
• 18.3 POST /api/v1/knowledge-bases/{id}/documents - Add document
• 18.4 DELETE /api/v1/knowledge-bases/{id}/documents/{did} - Remove
• 18.5 POST /api/v1/knowledge-bases/{id}/query - Query KB

​

19. Recording & Transcript APIs

• 19.1 GET /api/v1/calls/{id}/recording - Get recording URL
• 19.2 GET /api/v1/calls/{id}/transcript - Get transcript
• 19.3 GET /api/v1/tenants/{id}/recordings - List recordings

​

20. Analytics APIs

• 20.1 GET /api/v1/tenants/{id}/analytics/summary - Dashboard data
• 20.2 GET /api/v1/tenants/{id}/analytics/calls - Call metrics
• 20.3 GET /api/v1/tenants/{id}/analytics/usage - Usage metrics

​

21. Webhook Endpoints (Inbound)

• 21.1 POST /webhooks/gotoconnect - Call events
• 21.2 POST /webhooks/livekit - Room events
• 21.3 POST /webhooks/deepgram - Transcription events
• 21.4 Webhook signature validation

​

PART 4: GoToConnect Integration

​

22. GoToConnect Account Setup

• 22.1 Required Account Type
• 22.2 API Credentials Location
• 22.3 Webhook Configuration Steps
• 22.4 Phone Number Provisioning

​

23. GoToConnect Authentication

• 23.1 OAuth 2.0 Flow (step-by-step)
• 23.2 Token Storage
• 23.3 Token Refresh Logic
• 23.4 Error Handling

​

24. Webhook Events from GoToConnect

• 24.1 call.ringing - Inbound call arriving
• 24.2 call.answered - Call connected
• 24.3 call.ended - Call terminated
• 24.4 Event Payload Schemas
• 24.5 Event Processing Logic

​

25. GoToConnect API Calls

• 25.1 Answer Call
• 25.2 Transfer Call
• 25.3 Hold/Resume
• 25.4 Hangup
• 25.5 Get Call Status
• 25.6 List Lines/Extensions

​

26. Phone Number Management

• 26.1 Search Available Numbers
• 26.2 Provision Number
• 26.3 Configure Number Routing
• 26.4 Release Number

​

27. Ooma WebRTC Softphone Integration

• 27.1 What is Ooma Softphone
• 27.2 Why We Need It
• 27.3 Auto-Answer Configuration
• 27.4 Audio Stream Access

​

PART 5: WebRTC Bridge Service

​

28. Bridge Architecture

• 28.1 Purpose of the Bridge
• 28.2 Component Diagram
• 28.3 Threading Model
• 28.4 State Machine

​

29. Browser Automation Layer

• 29.1 Puppeteer/Playwright Setup
• 29.2 Ooma Login Automation
• 29.3 Session Management
• 29.4 Health Monitoring
• 29.5 Crash Recovery

​

30. Audio Capture

• 30.1 Capturing Browser Audio
• 30.2 Audio Format (sample rate, channels, encoding)
• 30.3 Buffer Management
• 30.4 Latency Considerations

​

31. LiveKit Connection

• 31.1 Creating LiveKit Room
• 31.2 Publishing Audio Track
• 31.3 Subscribing to Agent Audio
• 31.4 Track Management

​

32. Audio Routing

• 32.1 Caller → Agent Flow
• 32.2 Agent → Caller Flow
• 32.3 Mixing (if needed)
• 32.4 Volume Normalization

​

33. Bridge Lifecycle

• 33.1 Initialization Sequence
• 33.2 Call Setup Sequence
• 33.3 Active Call Management
• 33.4 Call Teardown Sequence
• 33.5 Error Recovery

​

PART 6: LiveKit Integration

​

34. LiveKit Cloud Setup

• 34.1 Account Creation
• 34.2 Project Configuration
• 34.3 API Credentials
• 34.4 Webhook Configuration

​

35. Room Management

• 35.1 Room Naming Convention
• 35.2 Room Creation Logic
• 35.3 Room Configuration Options
• 35.4 Room Deletion/Cleanup

​

36. Participant Management

• 36.1 Participant Types (caller, agent, supervisor)
• 36.2 Participant Identity Format
• 36.3 Permissions by Role
• 36.4 Participant Lifecycle

​

37. Token Generation

• 37.1 JWT Structure
• 37.2 Claims & Grants
• 37.3 Token Service Implementation
• 37.4 Token Refresh Strategy

​

38. Audio Track Handling

• 38.1 Track Publication
• 38.2 Track Subscription
• 38.3 Track Quality Settings
• 38.4 Mute/Unmute

​

39. LiveKit Webhooks

• 39.1 Room Started
• 39.2 Room Finished
• 39.3 Participant Joined
• 39.4 Participant Left
• 39.5 Track Published/Unpublished

​

40. Recording with Egress

• 40.1 Egress Types
• 40.2 Starting Recording
• 40.3 Stopping Recording
• 40.4 Storage Configuration
• 40.5 Recording Retrieval

​

PART 7: Voice AI Pipeline

​

41. Pipeline Architecture

• 41.1 Component Diagram
• 41.2 Data Flow (audio in → text → response → audio out)
• 41.3 Latency Budget Breakdown
• 41.4 Error Handling Strategy

​

42. Deepgram STT Integration

• 42.1 Account Setup
• 42.2 WebSocket Connection
• 42.3 Audio Streaming Format
• 42.4 Transcription Options (model, language, punctuation)
• 42.5 Handling Interim Results
• 42.6 Handling Final Results
• 42.7 Error Recovery

​

43. Voice Activity Detection (VAD)

• 43.1 What VAD Does
• 43.2 Silero VAD Setup
• 43.3 Configuration Parameters
• 43.4 Speech Start Detection
• 43.5 Speech End Detection
• 43.6 Barge-In Handling

​

44. Claude LLM Integration

• 44.1 API Setup
• 44.2 System Prompt Design
• 44.3 Conversation History Management
• 44.4 Streaming Responses
• 44.5 Function Calling (tools)
• 44.6 Token Management
• 44.7 Error Handling

​

45. Knowledge Base Retrieval (RAG)

• 45.1 When to Query KB
• 45.2 Query Construction
• 45.3 Embedding Generation
• 45.4 Vector Search
• 45.5 Context Injection into Prompt
• 45.6 Citation Handling

​

46. Chatterbox TTS Integration

• 46.1 RunPod Setup
• 46.2 API Endpoint Configuration
• 46.3 Voice Selection
• 46.4 Text Preprocessing
• 46.5 Audio Generation
• 46.6 Streaming Audio Output
• 46.7 Error Handling

​

47. Pipeline Orchestration

• 47.1 Turn-Taking Logic
• 47.2 Interruption Handling
• 47.3 Silence Handling
• 47.4 Timeout Handling
• 47.5 Graceful Degradation

​

PART 8: Agent Service

​

48. LiveKit Agents Framework

• 48.1 What is LiveKit Agents
• 48.2 Agent Architecture
• 48.3 Worker Setup
• 48.4 Agent Dispatch

​

49. Agent Lifecycle

• 49.1 Agent Pool Management
• 49.2 Agent Assignment
• 49.3 Agent State Machine
• 49.4 Agent Cleanup

​

50. Conversation State

• 50.1 State Structure
• 50.2 State Persistence
• 50.3 State Transitions
• 50.4 State Recovery

​

51. Intent Handling

• 51.1 Intent Detection Approach
• 51.2 Common Intents
• 51.3 Intent → Action Mapping
• 51.4 Fallback Handling

​

52. Call Actions

• 52.1 Transfer to Human
• 52.2 Transfer to Another AI
• 52.3 Place on Hold
• 52.4 Schedule Callback
• 52.5 End Call

​

53. Multi-Tenant Agent Configuration

• 53.1 Loading Tenant Config
• 53.2 Personality Injection
• 53.3 Voice Selection
• 53.4 Knowledge Base Binding

​

PART 9: Multi-Tenancy & Security

​

54. Multi-Tenant Architecture

• 54.1 Tenant Isolation Model
• 54.2 Data Segregation
• 54.3 Resource Quotas
• 54.4 Tenant Context Propagation

​

55. Authentication

• 55.1 JWT Implementation Details
• 55.2 Token Claims
• 55.3 Token Validation
• 55.4 Session Management

​

56. Authorization

• 56.1 Role Definitions
• 56.2 Permission Matrix
• 56.3 RBAC Implementation
• 56.4 Resource-Level Permissions

​

57. Data Security

• 57.1 Encryption at Rest
• 57.2 Encryption in Transit
• 57.3 PII Handling
• 57.4 Data Retention Policies

​

58. API Security

• 58.1 Rate Limiting Implementation
• 58.2 Input Validation
• 58.3 SQL Injection Prevention
• 58.4 CORS Configuration

​

59. Audit Logging

• 59.1 What to Log
• 59.2 Log Format
• 59.3 Log Storage
• 59.4 Log Retention

​

PART 10: Deployment & Operations

​

60. Infrastructure Setup

• 60.1 DigitalOcean Configuration
• 60.2 Dokploy Setup
• 60.3 Network Architecture
• 60.4 SSL/TLS Configuration

​

61. Container Configuration

• 61.1 Dockerfile for Each Service
• 61.2 Docker Compose (local dev)
• 61.3 Resource Limits
• 61.4 Health Checks

​

62. Environment Configuration

• 62.1 Environment Variables Reference
• 62.2 Secrets Management
• 62.3 Configuration by Environment

​

63. CI/CD Pipeline

• 63.1 GitHub Actions Setup
• 63.2 Build Process
• 63.3 Test Process
• 63.4 Deploy Process

​

64. Monitoring

• 64.1 Health Check Endpoints
• 64.2 Metrics Collection
• 64.3 Log Aggregation
• 64.4 Alerting Rules

​

65. Scaling

• 65.1 Horizontal Scaling Strategy
• 65.2 Auto-Scaling Configuration
• 65.3 Load Balancing
• 65.4 Database Scaling

​

66. Disaster Recovery

• 66.1 Backup Strategy
• 66.2 Recovery Procedures
• 66.3 Failover Configuration

​

67. Runbooks

• 67.1 Common Issues & Fixes
• 67.2 Escalation Procedures
• 67.3 Incident Response

​

68. Cost Management

• 68.1 Cost Breakdown by Component
• 68.2 Cost Monitoring
• 68.3 Optimization Strategies

​

Summary: 10 Parts

​

Part 1: Foundation & Context

​

Section 1: Project Overview

​

1.1 What We’re Building (Plain English)

• Understand what the human is saying (speech-to-text)
• Figure out what they want (intent recognition)
• Look up information to answer questions (knowledge base)
• Generate appropriate responses (large language model)
• Speak the response out loud (text-to-speech)
• Take actions like transferring to a human, scheduling callbacks, etc.

​

The Product in One Sentence

​

A Concrete Example

1. Oxford Pierpont (an agency) signs up for Voice by aiConnected
2. Oxford Pierpont onboards their client, Smile Dental (a dental office)
3. We provision a phone number: (555) 123-4567
4. Smile Dental advertises this number for appointments
5. Sarah (a patient) calls (555) 123-4567
6. Our AI answers: “Thank you for calling Smile Dental, this is Dr. Smith’s office. How can I help you today?”
7. Sarah says: “I need to schedule a teeth cleaning”
8. The AI accesses Smile Dental’s scheduling information and helps Sarah book an appointment
9. The entire call is recorded and transcribed
10. Oxford Pierpont can see analytics across all their clients
11. Smile Dental can see their own call history and transcripts
12. Sarah never knows she talked to an AI - it sounded that natural

​

What Makes This Different

​

1.2 Why We’re Building It (Business Problem)

​

The Pain Points We’re Solving

1. Phone calls go unanswered. Small businesses miss 40-60% of calls because staff are busy with in-person customers. Each missed call is a missed opportunity - potentially $500+ in lost revenue for a dental office.
2. Hiring is expensive and unreliable. A receptionist costs $35,000-50,000/year plus benefits. They call in sick. They quit. They need training. They can only work 8 hours a day.
3. After-hours coverage is nearly impossible. Answering services cost $1-3 per call and often provide poor experiences. The business loses customers who call at 7 PM.
4. Consistency is a challenge. Human staff have good days and bad days. The customer experience varies wildly.

1. Agencies want to offer AI solutions but can’t build them. They see the opportunity but lack technical expertise.
2. Existing solutions don’t allow reselling. Most AI voice products are direct-to-business. Agencies can’t white-label them.
3. Agencies need recurring revenue. One-time website builds are feast-or-famine. Voice AI is a monthly subscription model.

​

Market Timing

1. LLMs are good enough. Claude, GPT-4, and others can now hold genuinely helpful conversations. Two years ago, they couldn’t.
2. Speech technology has matured. Deepgram’s Nova-2 model achieves >95% accuracy. Text-to-speech voices (like Chatterbox) are nearly indistinguishable from humans.
3. Real-time infrastructure exists. LiveKit provides sub-100ms audio routing. WebRTC is battle-tested.
4. Costs have plummeted. What would have cost 1/minute in 2022 now costs \~0.025/minute.
5. Businesses are actively seeking automation. Post-pandemic labor shortages have made every business owner aware of the need to automate.

​

1.3 Who It’s For (Target Users)

​

Primary Users: Agencies

• Marketing agencies with 10-100 clients
• Digital agencies expanding into AI services
• Call center operators looking to add AI options
• Managed service providers (MSPs)

• Zero technical expertise required to deploy
• Ability to brand as their own
• Management dashboard for all their clients
• Competitive pricing to mark up and profit

• Runs a 5-person marketing agency
• Has 30 small business clients
• Offers websites, SEO, social media
• Wants to add “AI services” to his offerings
• Needs to be able to set up a new client in under an hour
• Wants to charge clients $300-500/month for the service

​

Secondary Users: Tenants (Agency’s Clients)

• Small to medium businesses
• Service-based businesses (dental, legal, HVAC, etc.)
• High call volume but can’t staff phones adequately
• Value customer experience

• Calls answered professionally 24/7
• Accurate information about their business
• Easy access to call recordings and transcripts
• Simple setup (they’re not technical)

• 3-dentist practice
• Receives 50-100 calls/day
• Front desk staff overwhelmed
• Misses 30% of calls
• Loses an estimated $10,000/month in missed appointments
• Willing to pay $400/month to never miss a call again

​

Tertiary Users: Platform Admins (Us - aiConnected)

• Visibility into all agencies and tenants
• Ability to manage billing
• System health monitoring
• Support access when agencies need help

​

1.4 Success Looks Like (Measurable Outcomes)

​

Technical Success Metrics

​

Business Success Metrics (Year 1)

​

What “Done” Looks Like for MVP

1. ✅ An agency can sign up and create their account
2. ✅ The agency can create a tenant (their client)
3. ✅ A phone number can be provisioned for the tenant
4. ✅ The tenant can upload documents to create a knowledge base
5. ✅ Inbound calls to that number are answered by AI
6. ✅ The AI can answer questions using the knowledge base
7. ✅ The AI can transfer calls to a human number
8. ✅ All calls are recorded and transcribed
9. ✅ The agency can view calls across all tenants
10. ✅ The tenant can view their own calls
11. ✅ Response latency is consistently under 1 second
12. ✅ The system handles 10 concurrent calls without degradation

​

Section 2: Glossary of Terms

​

2.1 Telephony Terms

​

PSTN (Public Switched Telephone Network)

​

VoIP (Voice over Internet Protocol)

​

SIP (Session Initiation Protocol)

​

WebRTC (Web Real-Time Communication)

​

DTMF (Dual-Tone Multi-Frequency)

​

IVR (Interactive Voice Response)

​

PBX (Private Branch Exchange)

​

Trunk / SIP Trunk

​

DID (Direct Inward Dialing)

​

ANI (Automatic Number Identification)

​

CDR (Call Detail Record)

​

E.164

​

2.2 WebRTC Terms

​

ICE (Interactive Connectivity Establishment)

​

STUN (Session Traversal Utilities for NAT)

​

TURN (Traversal Using Relays around NAT)

​

SDP (Session Description Protocol)

​

Oer-to-Peer (P2P)

​

SFU (Selective Forwarding Unit)

​

Media Track

​

Codec

​

Opus

​

Sample Rate

​

Frame

​

2.3 AI/ML Terms

​

LLM (Large Language Model)

​

STT (Speech-to-Text)

​

TTS (Text-to-Speech)

​

VAD (Voice Activity Detection)

​

Barge-In

​

Turn-Taking

​

Latency

​

Streaming

​

Embeddings

​

Vector Database

​

RAG (Retrieval-Augmented Generation)

​

Prompt

​

System Prompt

​

Context Window

​

Token

​

Function Calling / Tool Use

​

Hallucination

​

2.4 Platform Terms

​

Agency

​

Tenant

​

Platform Admin

​

Agency Admin

​

Tenant Admin

​

Knowledge Base

​

Voice Configuration

​

Personality

​

2.5 Infrastructure Terms

​

Container

​

Docker

​

Kubernetes / K8s

​

Dokploy

​

Webhook

​

WebSocket

​

REST API

​

JWT (JSON Web Token)

​

UUID (Universally Unique Identifier)

​

Environment Variable

​

Redis

​

PostgreSQL

​

n8n

​

Section 3: Architecture Overview

​

3.1 System Diagram (With Explanation)

┌─────────────────────────────────────────────────────────────────────────────┐
│                              PSTN NETWORK                                    │
│                    (Traditional Phone System)                                │
│                                                                              │
│    📱 Caller's Phone ─────────────────────────────────────────┐             │
│                                                                │             │
└────────────────────────────────────────────────────────────────│─────────────┘
                                                                 │
                                                                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           GOTOCONNECT                                        │
│                    (Cloud Telephony Provider)                                │
│                                                                              │
│    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                   │
│    │   Phone     │    │    Call     │    │  Webhook    │                   │
│    │  Numbers    │    │   Control   │    │   Events    │                   │
│    │   (DIDs)    │    │    API      │    │             │                   │
│    └─────────────┘    └─────────────┘    └──────┬──────┘                   │
│                                                  │                          │
└──────────────────────────────────────────────────│──────────────────────────┘
                                                   │
                    ┌──────────────────────────────┼───────────────────┐
                    │                              │                   │
                    ▼                              ▼                   │
┌─────────────────────────────────────┐  ┌─────────────────────────┐  │
│         ORCHESTRATION LAYER         │  │    WEBRTC BRIDGE        │  │
│              (n8n)                   │  │      SERVICE            │  │
│                                      │  │                         │  │
│  ┌────────────────────────────────┐ │  │  ┌───────────────────┐  │  │
│  │  • Receive call webhooks       │ │  │  │ Ooma WebRTC       │  │  │
│  │  • Route to appropriate flow   │ │  │  │ Softphone         │  │  │
│  │  • Trigger call setup          │ │  │  │ (Browser-based)   │  │  │
│  │  • Handle post-call processing │ │  │  └─────────┬─────────┘  │  │
│  └────────────────────────────────┘ │  │            │            │  │
│                                      │  │  ┌─────────▼─────────┐  │  │
└──────────────────────────────────────┘  │  │ Audio Capture &   │  │  │
                                          │  │ Forwarding        │  │  │
                                          │  └─────────┬─────────┘  │  │
                                          │            │            │  │
                                          └────────────│────────────┘  │
                                                       │               │
                                                       ▼               │
┌─────────────────────────────────────────────────────────────────────────────┐
│                            LIVEKIT CLOUD                                     │
│                    (Real-Time Media Infrastructure)                          │
│                                                                              │
│    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                   │
│    │    Room     │    │   Audio     │    │  Recording  │                   │
│    │ Management  │    │   Routing   │    │   (Egress)  │                   │
│    └─────────────┘    └─────────────┘    └─────────────┘                   │
│                              │                                              │
│                              │ Audio Streams                                │
│                              ▼                                              │
└──────────────────────────────│──────────────────────────────────────────────┘
                               │
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         AI AGENT SERVICE                                     │
│                 (LiveKit Agents Framework + Our Logic)                       │
│                                                                              │
│    ┌─────────────────────────────────────────────────────────────────────┐  │
│    │                        VOICE PIPELINE                                │  │
│    │                                                                      │  │
│    │   ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐   │  │
│    │   │ CALLER  │      │  STT    │      │  LLM    │      │  TTS    │   │  │
│    │   │ AUDIO   │─────▶│Deepgram │─────▶│ Claude  │─────▶│Chatter- │   │  │
│    │   │   IN    │      │ Nova-2  │      │ Sonnet  │      │  box    │   │  │
│    │   └─────────┘      └─────────┘      └────┬────┘      └────┬────┘   │  │
│    │                                          │                │        │  │
│    │                                          ▼                │        │  │
│    │                                    ┌──────────┐           │        │  │
│    │                                    │ Knowledge│           │        │  │
│    │                                    │   Base   │           │        │  │
│    │                                    │  (RAG)   │           │        │  │
│    │                                    └──────────┘           │        │  │
│    │                                                           ▼        │  │
│    │   ┌─────────┐                                      ┌─────────┐    │  │
│    │   │ AGENT   │◀─────────────────────────────────────│  AUDIO  │    │  │
│    │   │ AUDIO   │                                      │   OUT   │    │  │
│    │   │   OUT   │                                      │         │    │  │
│    │   └─────────┘                                      └─────────┘    │  │
│    │                                                                      │  │
│    └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
                               │
                               │ Writes to
                               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          DATA LAYER                                          │
│                                                                              │
│    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                   │
│    │ PostgreSQL  │    │   Redis     │    │   S3/DO    │                   │
│    │  (Primary   │    │  (Cache,    │    │  Spaces    │                   │
│    │   Data)     │    │   State)    │    │(Recordings)│                   │
│    └─────────────┘    └─────────────┘    └─────────────┘                   │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
                               │
                               │ Powers
                               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      MANAGEMENT LAYER                                        │
│                                                                              │
│    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                   │
│    │   REST API  │    │  Web UI     │    │  Webhooks   │                   │
│    │  (Backend)  │    │ (Frontend)  │    │   (Out)     │                   │
│    └─────────────┘    └─────────────┘    └─────────────┘                   │
│                                                                              │
│              Used by: Agencies, Tenants, Platform Admins                    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

​

Component-by-Component Explanation

• Phone numbers (DIDs) that customers call
• The ability to answer and control calls programmatically
• Webhook notifications when calls arrive
• APIs to transfer, hold, and hangup calls

1. Receives the webhook
2. Looks up the phone number to find the tenant
3. Triggers the WebRTC bridge to answer
4. Initiates LiveKit room creation
5. Dispatches an AI agent

1. Runs a headless browser with Ooma’s WebRTC softphone
2. Auto-answers incoming calls
3. Captures the audio stream from the browser
4. Forwards that audio to LiveKit
5. Receives audio from LiveKit (the AI speaking)
6. Plays that audio through the browser to the caller

• Creates “rooms” for each call
• Routes audio between participants (caller, AI agent, supervisors)
• Records calls (via Egress)
• Handles all the WebRTC complexity

1. Subscribes to the caller’s audio from LiveKit
2. Streams audio to Deepgram for transcription
3. Sends transcriptions to Claude for response generation
4. Streams Claude’s response to Chatterbox for speech synthesis
5. Publishes synthesized audio back to LiveKit

• Deepgram Nova-2: Converts caller’s speech to text. Streaming, real-time.
• Claude Sonnet: Generates intelligent responses. Understands context, follows instructions.
• Knowledge Base (RAG): Vector database with tenant-specific information. Grounds Claude’s responses in facts.
• Chatterbox-Turbo: Converts Claude’s text responses to natural-sounding speech. Runs on RunPod GPU.

• PostgreSQL: All persistent data - users, tenants, calls, transcripts, etc.
• Redis: Fast, temporary data - active call state, caching, pub/sub messaging
• S3/DigitalOcean Spaces: Object storage for call recordings (audio files)

• REST API: Backend service that powers all management operations
• Web UI: React-based dashboard for agencies and tenants
• Webhooks (Out): Notify external systems when events occur (call completed, etc.)

​

3.2 Data Flow Narrative (Step-by-Step What Happens on a Call)

​

Phase 1: Call Initiation (0-3 seconds)

• Her phone connects to PSTN
• PSTN routes to GoToConnect (which owns that number)

• Looks up routing for (555) 123-4567
• Finds it’s configured to ring the Ooma softphone extension
• Sends HTTP POST webhook to our n8n endpoint:

{
  "event": "call.ringing",
  "callId": "call-123456",
  "from": "+15559876543",
  "to": "+15551234567",
  "timestamp": "2026-01-25T10:00:00Z"
}

• Workflow triggers
• Looks up phone number +15551234567 in database
• Finds: tenant_id = “smile-dental”, agency_id = “oxford-pierpont”
• Loads tenant configuration: voice settings, greeting, personality
• Creates a call record in PostgreSQL with status = “ringing”

• Sends command: “Answer call on line X”
• Bridge’s browser-based softphone picks up

• GoToConnect sees the softphone answered
• Audio path established: Sarah ↔ GoToConnect ↔ Softphone in Browser
• GoToConnect sends “call.answered” webhook

• Room name: “call-smile-dental-call-123456”
• Generates access tokens for bridge (as “caller”) and agent

• Opens WebSocket connection to LiveKit
• Starts publishing caller audio as an audio track
• Subscribes to receive agent audio track

• n8n notifies Agent Service: “Join room call-smile-dental-call-123456”
• Agent Service assigns an available agent worker
• Agent loads Smile Dental’s configuration and knowledge base

• Subscribes to caller’s audio track
• Ready to publish agent audio track
• Initializes STT connection to Deepgram
• Prepares Claude conversation with system prompt

• Retrieves greeting from tenant config: “Thank you for calling Smile Dental, this is Dr. Smith’s office. How can I help you today?”
• Sends greeting to Chatterbox TTS
• Receives audio stream back
• Publishes to LiveKit
• Sarah hears the greeting through her phone

​

Phase 2: Conversation (Duration varies)

• “Yeah, hi, I need to schedule a teeth cleaning”
• Audio flows: Sarah’s phone → PSTN → GoToConnect → Softphone → Bridge → LiveKit → Agent

• Agent streams audio to Deepgram via WebSocket
• Deepgram sends interim results as Sarah speaks:
  • T+3.2s: “Yeah”
  • T+3.5s: “Yeah hi”
  • T+3.8s: “Yeah hi I need to”
  • T+4.2s: “Yeah hi I need to schedule”
  • T+4.8s: “Yeah hi I need to schedule a teeth cleaning”
• VAD (Voice Activity Detection) detects Sarah stopped speaking at T+5.0s
• Deepgram sends final transcript: “Yeah, hi, I need to schedule a teeth cleaning.”

• Recognizes intent: appointment scheduling
• Queries knowledge base: “teeth cleaning appointment scheduling”
• Retrieves relevant chunks:
  • “Teeth cleaning appointments are 45 minutes”
  • “Available Monday-Friday 8am-5pm, Saturday 9am-2pm”
  • “New patient cleaning: $150, Existing patient:$100”

• Constructs prompt with:
  • System prompt (personality, instructions)
  • Knowledge base context (retrieved chunks)
  • Conversation history (just the greeting so far)
  • User message: “Yeah, hi, I need to schedule a teeth cleaning.”

• Claude processes and generates response (streaming)
• As tokens stream back, agent buffers them into sentence chunks
• First sentence ready: “I’d be happy to help you schedule a cleaning!”

• Sends “I’d be happy to help you schedule a cleaning!” to Chatterbox
• Chatterbox generates audio and streams back

• Publishes audio to LiveKit
• Audio flows: Agent → LiveKit → Bridge → Softphone → GoToConnect → PSTN → Sarah’s phone
• Sarah hears: “I’d be happy to help you schedule a cleaning!”

• Meanwhile, Claude has generated more: “Are you an existing patient with us, or will this be your first visit?”
• TTS generates audio, agent publishes
• Sarah hears the complete response

​

Phase 3: Continued Conversation

• Sarah: “I’ve been there before, maybe two years ago?”
• Agent: (checks if it matters, decides to proceed) “Great, let me check our availability. What days work best for you?”
• Sarah: “Anytime Thursday or Friday afternoon”
• Agent: “I have openings Thursday at 2pm, 3:30pm, or Friday at 1pm and 4pm. Which works best?”
• Sarah: “Thursday at 3:30 works”
• Agent: “Perfect! I have you down for Thursday at 3:30pm for a teeth cleaning. Can I confirm your phone number for appointment reminders?”
• …and so on

• Every utterance is transcribed and stored
• Conversation history grows, sent to Claude each turn
• Agent can access tenant knowledge base as needed
• Full audio is being recorded via LiveKit Egress

​

Phase 4: Call Completion

• Intent: end conversation
• Response: “You’re all set! We’ll see you Thursday at 3:30. Have a great day!”

• Sends command to n8n: “End call call-123456”
• n8n tells GoToConnect to hang up
• GoToConnect terminates the call

1. LiveKit room closes (all participants left)
2. LiveKit Egress finalizes recording, uploads to storage
3. n8n workflow triggers:
   • Updates call record: status = “completed”, duration = 180 seconds
   • Triggers transcript finalization
   • Generates call summary (optional Claude call)
   • Calculates usage for billing
   • Sends webhook to tenant (if configured)

{
  "id": "call-123456",
  "tenant_id": "smile-dental",
  "from_number": "+15559876543",
  "to_number": "+15551234567",
  "direction": "inbound",
  "status": "completed",
  "started_at": "2026-01-25T10:00:00Z",
  "answered_at": "2026-01-25T10:00:01Z",
  "ended_at": "2026-01-25T10:03:00Z",
  "duration_seconds": 180,
  "recording_url": "https://storage.example.com/recordings/call-123456.wav",
  "transcript_id": "transcript-789",
  "outcome": "appointment_scheduled",
  "cost_cents": 45
}

​

3.3 Technology Choices (What We’re Using and WHY)

​

Telephony: GoToConnect

1. Ooma WebRTC Softphone - Critical. GoToConnect offers a browser-based softphone through Ooma, which lets us capture audio without specialized telephony hardware.
2. Webhook support - Sends real-time notifications for call events.
3. Call control API - Programmatic transfer, hold, hangup.
4. Reasonable pricing - ~$0.005/minute for PSTN usage.
5. Existing relationship - Bob’s company already uses GoToConnect.

• Twilio - More developer-friendly but more expensive, no Ooma equivalent
• Vonage - Similar capabilities but less familiar
• Direct SIP - Would require significant telephony expertise

​

Real-Time Media: LiveKit Cloud

1. LiveKit Agents Framework - Purpose-built for AI voice agents. Handles VAD, turn-taking, pipeline orchestration.
2. Cloud-hosted - No infrastructure to manage.
3. Low latency - Sub-100ms audio routing.
4. Recording built-in - Egress feature for call recording.
5. Scalable - Handles thousands of concurrent rooms.

• Self-hosted LiveKit - More control but operational burden
• Twilio Video - Less AI-focused, no agents framework
• Daily.co - Good but less mature agent tooling
• Custom WebRTC - Too much complexity

​

Speech-to-Text: Deepgram Nova-2

1. Accuracy - Nova-2 is best-in-class for conversational speech.
2. Streaming - Real-time results as speech happens.
3. Latency - Designed for real-time use cases.
4. Pricing - $0.0043/minute is competitive.
5. LiveKit integration - Works well with LiveKit Agents.

• Google Speech-to-Text - Good but more expensive
• AWS Transcribe - Higher latency
• Whisper - Not designed for real-time streaming
• AssemblyAI - Good but Deepgram has edge on latency

​

Language Model: Claude Sonnet (Anthropic)

1. Quality - Claude produces natural, helpful responses.
2. Instruction following - Excellent at staying in character.
3. Function calling - Reliable tool use for actions.
4. Context window - 200K tokens handles long conversations.
5. Safety - Built-in refusal of harmful requests.

• GPT-4 - Comparable but OpenAI has reliability concerns
• Llama - Would need to self-host, more complexity
• Claude Opus - Overkill for this use case, more expensive

​

Text-to-Speech: Chatterbox-Turbo on RunPod

1. Quality - Natural-sounding voice synthesis.
2. Cost - Much cheaper than commercial TTS at scale.
3. Customization - Can fine-tune for specific voices.
4. Latency - Fast enough for real-time with GPU acceleration.
5. No per-character fees - Just GPU time.

• ElevenLabs - Excellent quality but $0.30/1000 chars adds up
• Amazon Polly - Robotic sounding
• Google TTS - Better than Polly but not great
• Play.ht - Good but expensive for volume

​

Database: PostgreSQL

1. Reliability - Battle-tested, ACID compliant.
2. pgvector extension - Native vector similarity search for RAG.
3. JSON support - Flexible for varied data shapes.
4. Familiar - Team knows it well.
5. Managed options - DigitalOcean, AWS RDS, etc.

• MySQL - No native vector support
• MongoDB - Less suited for relational data
• Separate vector DB - Added complexity

​

Cache/State: Redis

1. Speed - Sub-millisecond operations.
2. Pub/Sub - Real-time messaging between services.
3. TTL support - Automatic expiration for temporary data.
4. Familiar - Industry standard.

• Memcached - Less feature-rich
• KeyDB - Compatible but less proven

​

Orchestration: n8n

1. Visual workflows - Easy to build and debug.
2. Webhook handling - First-class support.
3. Self-hosted - No per-execution fees.
4. Extensible - Custom code nodes when needed.
5. Bob’s familiarity - Already using it.

• Zapier - Too expensive at scale
• Custom code - More flexibility but slower to develop
• Temporal - Overkill for our needs

​

Deployment: Dokploy on DigitalOcean

1. Simplicity - Easier than Kubernetes.
2. Cost - DigitalOcean is affordable.
3. Control - Self-managed but not too complex.
4. Docker-native - Standard containerization.

• Kubernetes - Overkill for initial scale
• AWS ECS - More complex, vendor lock-in
• Heroku - Expensive at scale
• Render - Good but less control

​

3.4 What We’re NOT Building (Explicit Scope Boundaries)

​

Not Building: Outbound Dialer (MVP)

• Campaign management
• Do-not-call list compliance
• Predictive dialing algorithms
• Different conversation patterns

​

Not Building: Video Calls

• Different pipeline (video processing)
• Higher bandwidth
• Different use cases entirely

​

Not Building: SMS/Chat

• Different interaction patterns
• Different latency expectations
• Different UI

​

Not Building: Custom Voice Cloning

• Voice recording sessions
• Fine-tuning pipelines
• Legal consent frameworks

​

Not Building: On-Premise Deployment

• Different deployment models
• Customer-managed infrastructure
• Support complexity

​

Not Building: Direct Consumer Sales

• Different sales motion
• Support infrastructure
• Competing with our own customers

​

Not Building: Full CRM

​

Not Building: Appointment Scheduling Backend

​

Section 4: Development Environment Setup

​

4.1 Required Accounts & API Keys

​

4.1.1 GoToConnect (Telephony)

• GoToConnect account with API access
• OAuth 2.0 credentials (Client ID and Client Secret)
• At least one phone number provisioned
• Webhook endpoint configured

1. Contact GoToConnect sales for a developer/partner account
2. Access the admin portal at admin.goto.com
3. Navigate to Integrations → API Credentials
4. Create new OAuth 2.0 application
5. Note the Client ID and Client Secret
6. Configure redirect URI for OAuth flow

GOTOCONNECT_CLIENT_ID=your_client_id_here
GOTOCONNECT_CLIENT_SECRET=your_client_secret_here
GOTOCONNECT_REDIRECT_URI=https://yourapp.com/oauth/callback
GOTOCONNECT_WEBHOOK_SECRET=your_webhook_secret

​

4.1.2 LiveKit Cloud

• LiveKit Cloud account
• API Key and Secret
• WebSocket URL for your project

1. Sign up at cloud.livekit.io
2. Create a new project
3. Go to Settings → Keys
4. Note the API Key and Secret
5. Note the WebSocket URL (wss://your-project.livekit.cloud)

LIVEKIT_API_KEY=your_api_key_here
LIVEKIT_API_SECRET=your_api_secret_here
LIVEKIT_WS_URL=wss://your-project.livekit.cloud

​

4.1.3 Deepgram (STT)

• Deepgram account
• API key

1. Sign up at console.deepgram.com
2. Create a new project
3. Go to API Keys
4. Create new key with appropriate permissions

DEEPGRAM_API_KEY=your_api_key_here

​

4.1.4 Anthropic (LLM)

• Anthropic API account
• API key

1. Sign up at console.anthropic.com
2. Go to API Keys
3. Create new key

ANTHROPIC_API_KEY=your_api_key_here

​

4.1.5 RunPod (TTS Hosting)

• RunPod account
• API key
• GPU endpoint URL (after deploying Chatterbox)

1. Sign up at runpod.io
2. Add payment method
3. Go to Settings → API Keys
4. Create new key
5. Deploy Chatterbox template (instructions in Part 7)

RUNPOD_API_KEY=your_api_key_here
CHATTERBOX_ENDPOINT_URL=https://your-endpoint.runpod.ai

​

4.1.6 DigitalOcean

• DigitalOcean account
• API token
• Spaces access keys (for object storage)

1. Sign up at digitalocean.com
2. Go to API → Tokens → Generate New Token
3. Go to Spaces → Manage Keys → Generate New Key

DO_API_TOKEN=your_token_here
DO_SPACES_KEY=your_spaces_key
DO_SPACES_SECRET=your_spaces_secret
DO_SPACES_ENDPOINT=nyc3.digitaloceanspaces.com
DO_SPACES_BUCKET=voice-aiconnected-recordings

​

4.1.7 Database Connection

DATABASE_URL=postgresql://postgres:password@localhost:5432/voice_aiconnected
REDIS_URL=redis://localhost:6379

DATABASE_URL=postgresql://user:pass@db-host:5432/voice_aiconnected?sslmode=require
REDIS_URL=rediss://user:pass@redis-host:6379

​

4.2 Local Development Tools

​

4.2.1 Required Software

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
node --version  # Should show v20.x.x

# Using pyenv (recommended)
curl https://pyenv.run | bash
pyenv install 3.11.7
pyenv global 3.11.7
python --version  # Should show 3.11.x

# macOS
brew install --cask docker

# Ubuntu
sudo apt-get update
sudo apt-get install docker.io docker-compose-v2
sudo usermod -aG docker $USER  # Log out and back in after this

# Verify
docker --version
docker compose version

# macOS
brew install postgresql@15

# Ubuntu
sudo apt-get install postgresql-client-15

# Verify
psql --version

# macOS
brew install redis

# Ubuntu
sudo apt-get install redis-tools

# Verify
redis-cli --version

# Should already be installed, verify:
git --version

# If not:
# macOS: xcode-select --install
# Ubuntu: sudo apt-get install git

​

4.2.2 Recommended IDE Setup

• Python (Microsoft)
• Pylance
• ESLint
• Prettier
• Docker
• GitLens
• Thunder Client (API testing)
• PostgreSQL (ckolkman)

{
  "python.defaultInterpreterPath": "~/.pyenv/shims/python",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/.pytest_cache": true,
    "**/node_modules": true
  }
}

​

4.2.3 Helpful CLI Tools

# HTTPie - Better than curl for API testing
brew install httpie  # or pip install httpie

# jq - JSON processor
brew install jq  # or sudo apt-get install jq

# ngrok - Expose local server for webhooks
brew install ngrok  # or download from ngrok.com

# lazydocker - Docker TUI
brew install lazydocker

​

4.3 Repository Structure

voice-aiconnected/
├── README.md                    # Project overview
├── CLAUDE-CODE-CONTINUATION-PROMPT.md  # Handoff document
├── docker-compose.yml           # Local development services
├── docker-compose.prod.yml      # Production compose file
├── .env.example                 # Example environment variables
├── .gitignore                   # Git ignore rules
│
├── docs/                        # Documentation
│   ├── JUNIOR-DEV-PRD-PART-01.md
│   ├── JUNIOR-DEV-PRD-PART-02.md
│   ├── ... (through PART-10)
│   ├── 01-SYSTEM-ARCHITECTURE-OVERVIEW.md
│   ├── 02-GOTOCONNECT-INTEGRATION-SPECIFICATION.md
│   ├── 03-VOICE-PIPELINE-ARCHITECTURE.md
│   ├── 04-WEBRTC-BRIDGE-TECHNICAL-DESIGN.md
│   └── 05-LIVEKIT-INTEGRATION-SPECIFICATION.md
│
├── services/                    # Backend services
│   │
│   ├── api/                     # REST API service
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   ├── pyproject.toml
│   │   ├── src/
│   │   │   ├── __init__.py
│   │   │   ├── main.py          # FastAPI application
│   │   │   ├── config.py        # Configuration
│   │   │   ├── database.py      # Database connection
│   │   │   ├── models/          # SQLAlchemy models
│   │   │   ├── schemas/         # Pydantic schemas
│   │   │   ├── routers/         # API route handlers
│   │   │   ├── services/        # Business logic
│   │   │   └── utils/           # Utilities
│   │   └── tests/
│   │
│   ├── agent/                   # AI Agent service
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   ├── pyproject.toml
│   │   ├── src/
│   │   │   ├── __init__.py
│   │   │   ├── main.py          # Agent entry point
│   │   │   ├── config.py
│   │   │   ├── agent.py         # Agent implementation
│   │   │   ├── pipeline/        # Voice pipeline components
│   │   │   │   ├── stt.py       # Speech-to-text
│   │   │   │   ├── llm.py       # LLM integration
│   │   │   │   ├── tts.py       # Text-to-speech
│   │   │   │   └── vad.py       # Voice activity detection
│   │   │   ├── knowledge/       # RAG implementation
│   │   │   └── actions/         # Agent actions (transfer, etc.)
│   │   └── tests/
│   │
│   ├── bridge/                  # WebRTC Bridge service
│   │   ├── Dockerfile
│   │   ├── package.json
│   │   ├── src/
│   │   │   ├── index.ts         # Entry point
│   │   │   ├── config.ts
│   │   │   ├── browser.ts       # Browser automation
│   │   │   ├── softphone.ts     # Ooma softphone control
│   │   │   ├── livekit.ts       # LiveKit connection
│   │   │   └── audio.ts         # Audio routing
│   │   └── tests/
│   │
│   └── worker/                  # Background job worker
│       ├── Dockerfile
│       ├── requirements.txt
│       ├── src/
│       │   ├── __init__.py
│       │   ├── main.py
│       │   ├── jobs/            # Job definitions
│       │   └── utils/
│       └── tests/
│
├── web/                         # Frontend application
│   ├── Dockerfile
│   ├── package.json
│   ├── next.config.js
│   ├── src/
│   │   ├── app/                 # Next.js app router
│   │   ├── components/          # React components
│   │   ├── lib/                 # Utilities
│   │   └── styles/              # CSS
│   └── tests/
│
├── migrations/                  # Database migrations
│   ├── alembic.ini
│   ├── env.py
│   └── versions/                # Migration files
│
├── scripts/                     # Utility scripts
│   ├── setup-dev.sh             # Development setup
│   ├── seed-data.py             # Seed database
│   └── deploy.sh                # Deployment script
│
└── infra/                       # Infrastructure configuration
    ├── dokploy/                 # Dokploy configuration
    ├── nginx/                   # Nginx configuration
    └── monitoring/              # Monitoring setup

​

Service Responsibilities

• Handles all HTTP requests from frontend and external systems
• Manages authentication and authorization
• CRUD operations for all entities
• Exposes webhooks for external systems

• LiveKit Agents worker
• Voice pipeline (STT → LLM → TTS)
• Knowledge base queries
• Conversation management

• Browser automation (Puppeteer)
• Ooma softphone control
• Audio capture and routing
• LiveKit media publishing

• Async job processing
• Post-call processing
• Transcript finalization
• Usage aggregation
• Scheduled tasks

• Agency dashboard
• Tenant dashboard
• Admin dashboard
• Configuration interfaces

​

4.4 Environment Variables Reference

# =============================================================================
# ENVIRONMENT CONFIGURATION
# =============================================================================

# Environment: development, staging, production
NODE_ENV=development
PYTHON_ENV=development

# =============================================================================
# DATABASE
# =============================================================================

# PostgreSQL connection string
DATABASE_URL=postgresql://postgres:password@localhost:5432/voice_aiconnected

# Redis connection string
REDIS_URL=redis://localhost:6379

# =============================================================================
# GOTOCONNECT (TELEPHONY)
# =============================================================================

# OAuth 2.0 credentials
GOTOCONNECT_CLIENT_ID=your_client_id
GOTOCONNECT_CLIENT_SECRET=your_client_secret
GOTOCONNECT_REDIRECT_URI=http://localhost:3000/oauth/gotoconnect/callback

# API base URL
GOTOCONNECT_API_URL=https://api.goto.com

# Webhook validation
GOTOCONNECT_WEBHOOK_SECRET=your_webhook_secret

# Ooma Softphone credentials (for browser automation)
OOMA_USERNAME=your_ooma_username
OOMA_PASSWORD=your_ooma_password

# =============================================================================
# LIVEKIT
# =============================================================================

# LiveKit Cloud credentials
LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret
LIVEKIT_WS_URL=wss://your-project.livekit.cloud

# Webhook validation
LIVEKIT_WEBHOOK_SECRET=your_webhook_secret

# =============================================================================
# DEEPGRAM (STT)
# =============================================================================

DEEPGRAM_API_KEY=your_api_key

# Model configuration
DEEPGRAM_MODEL=nova-2
DEEPGRAM_LANGUAGE=en-US

# =============================================================================
# ANTHROPIC (LLM)
# =============================================================================

ANTHROPIC_API_KEY=your_api_key

# Model configuration
ANTHROPIC_MODEL=claude-sonnet-4-20250514
ANTHROPIC_MAX_TOKENS=1024

# =============================================================================
# CHATTERBOX (TTS)
# =============================================================================

# RunPod endpoint
CHATTERBOX_ENDPOINT_URL=https://your-endpoint.runpod.ai
RUNPOD_API_KEY=your_api_key

# Voice configuration
CHATTERBOX_DEFAULT_VOICE=default
CHATTERBOX_SAMPLE_RATE=24000

# =============================================================================
# OBJECT STORAGE (RECORDINGS)
# =============================================================================

# DigitalOcean Spaces (S3-compatible)
DO_SPACES_KEY=your_key
DO_SPACES_SECRET=your_secret
DO_SPACES_ENDPOINT=nyc3.digitaloceanspaces.com
DO_SPACES_BUCKET=voice-aiconnected-recordings
DO_SPACES_REGION=nyc3

# =============================================================================
# AUTHENTICATION
# =============================================================================

# JWT configuration
JWT_SECRET=your_very_long_random_secret_at_least_32_characters
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# Refresh token
REFRESH_TOKEN_SECRET=another_very_long_random_secret
REFRESH_TOKEN_EXPIRATION_DAYS=30

# =============================================================================
# APPLICATION
# =============================================================================

# API service
API_HOST=0.0.0.0
API_PORT=8000
API_BASE_URL=http://localhost:8000

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000

# CORS
CORS_ORIGINS=http://localhost:3000,http://localhost:8000

# =============================================================================
# WEBHOOKS (INBOUND)
# =============================================================================

# n8n webhook URLs (where GoToConnect/LiveKit send events)
N8N_WEBHOOK_BASE_URL=http://localhost:5678/webhook

# =============================================================================
# LOGGING & MONITORING
# =============================================================================

# Log level: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

# Sentry (error tracking)
SENTRY_DSN=https://your_sentry_dsn

# =============================================================================
# FEATURE FLAGS
# =============================================================================

# Enable/disable features
FEATURE_OUTBOUND_CALLS=false
FEATURE_RECORDING=true
FEATURE_TRANSCRIPTION=true

# =============================================================================
# RATE LIMITING
# =============================================================================

# API rate limits
RATE_LIMIT_PER_MINUTE=100
RATE_LIMIT_PER_HOUR=1000

# =============================================================================
# DEVELOPMENT ONLY
# =============================================================================

# Debug mode (never enable in production)
DEBUG=true

# Skip webhook signature validation (never in production)
SKIP_WEBHOOK_VALIDATION=false

# Use mock services (for testing without external APIs)
USE_MOCK_STT=false
USE_MOCK_LLM=false
USE_MOCK_TTS=false

​

4.5 How to Run Locally

​

Step 1: Clone the Repository

git clone https://github.com/oxfordpierpont/Voice-aiConnected.git
cd Voice-aiConnected

​

Step 2: Copy Environment Variables

cp .env.example .env

​

Step 3: Start Infrastructure Services

# Start PostgreSQL, Redis, and other infrastructure
docker compose up -d postgres redis

# Verify they're running
docker compose ps

​

Step 4: Initialize Database

# Create database
docker compose exec postgres psql -U postgres -c "CREATE DATABASE voice_aiconnected;"

# Run migrations
cd services/api
python -m alembic upgrade head

# Seed development data (optional)
cd ../../scripts
python seed-data.py

​

Step 5: Start Backend Services

# From project root
docker compose up -d api agent bridge worker

# View logs
docker compose logs -f api

cd services/api
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn src.main:app --reload --port 8000

cd services/agent
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python src/main.py

cd services/bridge
npm install
npm run dev

​

Step 6: Start Frontend

cd web
npm install
npm run dev

​

Step 7: Start n8n (Workflow Automation)

docker compose up -d n8n

​

Step 8: Expose Webhooks (For Testing)

# Start ngrok tunnel
ngrok http 8000

# Note the URL, e.g., https://abc123.ngrok.io
# Configure this URL in GoToConnect webhook settings

​

Step 9: Verify Everything Works

# Check API health
curl http://localhost:8000/health
# Expected: {"status": "healthy", "version": "0.1.0"}

# Check database connection
curl http://localhost:8000/health/db
# Expected: {"status": "connected"}

# Check Redis connection
curl http://localhost:8000/health/redis
# Expected: {"status": "connected"}

​

Step 10: Make a Test Call

1. Log into the frontend at http://localhost:3000
2. Create a test tenant with a phone number
3. Call the phone number
4. You should hear the AI greeting!

​

Troubleshooting Common Issues

Connection refused to localhost:5432

Connection refused to localhost:6379

401 Unauthorized from Deepgram/Anthropic/etc

GoToConnect shows webhook failed

Puppeteer cannot launch browser

Error: listen EADDRINUSE: address already in use :::8000

​

End of Part 1

1. ✅ Complete understanding of what we’re building and why
2. ✅ Full glossary of every technical term
3. ✅ Detailed architecture with component explanations
4. ✅ Complete development environment setup

• Complete database schema with DDL
• Every table, column, index explained
• Migration strategy
• Query patterns

​

Junior Developer PRD - Part 2: Database Design

​

Section 5: Database Architecture

​

5.1 Why PostgreSQL

​

Reasons for Choosing PostgreSQL

• Agencies have many Tenants
• Tenants have many Phone Numbers
• Phone Numbers receive many Calls
• Calls have Transcripts and Recordings

• Vector data type for storing embeddings
• Vector similarity search operators
• Indexes for fast nearest-neighbor queries

• Tenant configuration varies by tenant
• Call metadata varies by call type
• Webhook payloads from external systems

• ACID compliance (data integrity guaranteed)
• Excellent crash recovery
• Mature replication for high availability
• Decades of production use

• DigitalOcean Managed Databases
• AWS RDS
• Supabase
• Neon

​

What We’re NOT Using

​

5.2 Database Naming Conventions

​

Table Names

• Plural nouns: users, calls, tenants (not user, call, tenant)
• Snake_case: phone_numbers, knowledge_bases (not phoneNumbers, KnowledgeBases)
• Lowercase only: call_events (not Call_Events or CALL_EVENTS)

​

Column Names

• Snake_case: created_at, tenant_id, phone_number
• Lowercase only: Always
• Descriptive: started_at not start, duration_seconds not dur
• Boolean columns: Prefix with is_ or has_: is_active, has_voicemail

- **Foreign keys**: `{referenced_table_singular}_id`: `tenant_id`, `user_id`, `call_id`  

• Timestamps: Suffix with _at: created_at, updated_at, deleted_at, started_at, ended_at

​

Index Names

Format: `ix_{table}_{column(s)}`

• ix_calls_tenant_id
• ix_calls_started_at
• ix_users_email
• ix_phone_numbers_tenant_id_number

​

Constraint Names

**Primary Keys**: `pk_{table}`

• pk_users
• pk_calls

**Foreign Keys**: `fk_{table}_{referenced_table}`

• fk_tenants_agencies
• fk_calls_tenants

**Unique Constraints**: `uq_{table}_{column(s)}`

• uq_users_email
• uq_phone_numbers_number

**Check Constraints**: `ck_{table}_{description}`

• ck_calls_duration_positive
• ck_users_email_format

​

Enum Types

Format: `{table}_{column}_enum` or descriptive name

• call_status_enum
• call_direction_enum
• user_role_enum

​

5.3 Common Patterns Used

​

Pattern 1: UUID Primary Keys

id UUID PRIMARY KEY DEFAULT gen_random_uuid()

• Can be generated client-side without database round-trip
• No sequential guessing (security)
• Easy to merge data from multiple sources
• Works well with distributed systems

• Requires database to generate ID
• Sequential IDs leak information (how many records exist)
• Merging data from multiple sources causes conflicts

​

Pattern 2: Timestamp Columns

created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()

CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- Applied to each table:
CREATE TRIGGER update_users_updated_at
    BEFORE UPDATE ON users
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

​

Pattern 3: Soft Deletes

deleted_at TIMESTAMPTZ DEFAULT NULL

• Data recovery is possible
• Audit trail preserved
• Foreign key relationships don’t break
• Billing and analytics remain accurate

SELECT * FROM tenants WHERE deleted_at IS NULL;

SELECT * FROM tenants WHERE deleted_at IS NOT NULL;

​

Pattern 4: JSONB Configuration Columns

settings JSONB NOT NULL DEFAULT '{}'::jsonb,
metadata JSONB NOT NULL DEFAULT '{}'::jsonb

• Data structure varies between records
• External system payloads
• User-configurable settings
• Data you don’t query by frequently

• Data you query/filter by frequently (use columns)
• Relationships to other tables (use foreign keys)
• Data with strict schema requirements

​

Pattern 5: Enum Types for Status Fields

CREATE TYPE call_status_enum AS ENUM (
    'pending',
    'ringing',
    'answered',
    'completed',
    'failed',
    'cancelled'
);

-- Usage in table:
status call_status_enum NOT NULL DEFAULT 'pending'

• Database enforces valid values
• Typos caught at insert time
• Self-documenting schema
• More efficient storage than strings

• Fixed set of values that rarely changes
• Values are known at schema design time

• Values added/removed frequently
• User-defined values
• Hundreds of possible values

​

Pattern 6: Tenant Isolation

tenant_id UUID NOT NULL REFERENCES tenants(id)

-- CORRECT: Filter by tenant
SELECT * FROM calls WHERE tenant_id = $1 AND id = $2;

-- WRONG: No tenant filter (data leak risk)
SELECT * FROM calls WHERE id = $1;

​

Pattern 7: Audit Columns for Sensitive Operations

created_by UUID REFERENCES users(id),
updated_by UUID REFERENCES users(id)

​

Section 6: Schema - Core Entities

​

6.1 agencies Table

-- =============================================================================
-- AGENCIES TABLE
-- =============================================================================
-- Agencies are businesses that resell Voice by aiConnected to their clients.
-- Each agency can have multiple tenants (their clients).
-- =============================================================================

CREATE TABLE agencies (
    -- Primary Key
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    -- Basic Information
    name VARCHAR(255) NOT NULL,
    slug VARCHAR(100) NOT NULL,  -- URL-friendly identifier: "oxford-pierpont"
    
    -- Contact Information
    contact_email VARCHAR(255) NOT NULL,
    contact_phone VARCHAR(50),
    contact_name VARCHAR(255),
    
    -- Address (for billing/legal)
    address_line1 VARCHAR(255),
    address_line2 VARCHAR(255),
    city VARCHAR(100),
    state VARCHAR(100),
    postal_code VARCHAR(20),
    country VARCHAR(2) DEFAULT 'US',  -- ISO 3166-1 alpha-2
    
    -- Business Details
    company_name VARCHAR(255),  -- Legal company name if different from "name"
    tax_id VARCHAR(50),         -- EIN for US companies
    
    -- Status
    status VARCHAR(50) NOT NULL DEFAULT 'active',  -- active, suspended, cancelled
    is_verified BOOLEAN NOT NULL DEFAULT FALSE,     -- Email/identity verified
    
    -- Limits & Quotas
    max_tenants INTEGER NOT NULL DEFAULT 100,       -- Maximum tenants allowed
    max_concurrent_calls INTEGER NOT NULL DEFAULT 50, -- Across all tenants
    
    -- Billing
    billing_email VARCHAR(255),
    stripe_customer_id VARCHAR(255),  -- For payment processing
    billing_plan VARCHAR(50) DEFAULT 'starter',  -- starter, growth, scale, enterprise
    
    -- Settings (flexible JSON for agency-specific config)
    settings JSONB NOT NULL DEFAULT '{}'::jsonb,
    -- Example settings:
    -- {
    --   "branding": {
    --     "logo_url": "https://...",
    --     "primary_color": "#1a73e8"
    --   },
    --   "defaults": {
    --     "voice_id": "default",
    --     "timezone": "America/New_York"
    --   },
    --   "notifications": {
    --     "email_on_new_tenant": true
    --   }
    -- }
    
    -- Metadata (for internal use)
    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
    
    -- Timestamps
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ DEFAULT NULL,
    
    -- Constraints
    CONSTRAINT uq_agencies_slug UNIQUE (slug),
    CONSTRAINT uq_agencies_contact_email UNIQUE (contact_email),
    CONSTRAINT ck_agencies_status CHECK (status IN ('active', 'suspended', 'cancelled'))
);

-- Indexes
CREATE INDEX ix_agencies_status ON agencies(status) WHERE deleted_at IS NULL;
CREATE INDEX ix_agencies_created_at ON agencies(created_at);
CREATE INDEX ix_agencies_billing_plan ON agencies(billing_plan) WHERE deleted_at IS NULL;

-- Trigger for updated_at
CREATE TRIGGER update_agencies_updated_at
    BEFORE UPDATE ON agencies
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

-- Comments
COMMENT ON TABLE agencies IS 'Businesses that resell Voice by aiConnected to their clients';
COMMENT ON COLUMN agencies.slug IS 'URL-friendly identifier, must be unique';
COMMENT ON COLUMN agencies.max_tenants IS 'Maximum number of tenants this agency can create';
COMMENT ON COLUMN agencies.settings IS 'Agency-specific configuration as JSON';

​

Column Explanations

​

6.2 tenants Table

-- =============================================================================
-- TENANTS TABLE
-- =============================================================================
-- Tenants are end-customer businesses that use Voice AI.
-- Each tenant belongs to one agency.
-- Tenants have their own phone numbers, knowledge base, and configuration.
-- =============================================================================

CREATE TABLE tenants (
    -- Primary Key
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    -- Relationship
    agency_id UUID NOT NULL REFERENCES agencies(id),
    
    -- Basic Information
    name VARCHAR(255) NOT NULL,           -- Display name: "Smile Dental"
    slug VARCHAR(100) NOT NULL,           -- Unique within agency: "smile-dental"
    
    -- Business Information
    business_type VARCHAR(100),           -- dental, legal, hvac, etc.
    timezone VARCHAR(50) NOT NULL DEFAULT 'America/New_York',
    
    -- Contact (for the business)
    contact_email VARCHAR(255),
    contact_phone VARCHAR(50),
    contact_name VARCHAR(255),
    website_url VARCHAR(500),
    
    -- Status
    status VARCHAR(50) NOT NULL DEFAULT 'active',  -- active, suspended, cancelled
    
    -- Limits & Quotas
    max_concurrent_calls INTEGER NOT NULL DEFAULT 10,
    max_monthly_minutes INTEGER,  -- NULL = unlimited
    
    -- Configuration
    settings JSONB NOT NULL DEFAULT '{}'::jsonb,
    -- Example settings:
    -- {
    --   "voice": {
    --     "voice_id": "alloy",
    --     "speaking_rate": 1.0,
    --     "language": "en-US"
    --   },
    --   "behavior": {
    --     "greeting_delay_ms": 500,
    --     "silence_timeout_ms": 5000,
    --     "max_call_duration_seconds": 1800
    --   },
    --   "features": {
    --     "call_recording": true,
    --     "transcription": true,
    --     "sentiment_analysis": false
    --   },
    --   "transfer": {
    --     "default_number": "+15551234567",
    --     "business_hours_only": true
    --   }
    -- }
    
    -- Metadata
    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
    
    -- Timestamps
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ DEFAULT NULL,
    
    -- Constraints
    CONSTRAINT uq_tenants_agency_slug UNIQUE (agency_id, slug),
    CONSTRAINT ck_tenants_status CHECK (status IN ('active', 'suspended', 'cancelled'))
);

-- Indexes
CREATE INDEX ix_tenants_agency_id ON tenants(agency_id) WHERE deleted_at IS NULL;
CREATE INDEX ix_tenants_status ON tenants(status) WHERE deleted_at IS NULL;
CREATE INDEX ix_tenants_created_at ON tenants(created_at);
CREATE INDEX ix_tenants_business_type ON tenants(business_type) WHERE deleted_at IS NULL;

-- Trigger for updated_at
CREATE TRIGGER update_tenants_updated_at
    BEFORE UPDATE ON tenants
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

-- Comments
COMMENT ON TABLE tenants IS 'End-customer businesses that use Voice AI, belonging to an agency';
COMMENT ON COLUMN tenants.slug IS 'URL-friendly identifier, unique within agency';
COMMENT ON COLUMN tenants.timezone IS 'IANA timezone identifier for business hours calculations';
COMMENT ON COLUMN tenants.settings IS 'Tenant-specific configuration as JSON';

​

Column Explanations

​

6.3 users Table

-- =============================================================================
-- USERS TABLE
-- =============================================================================
-- Users are humans who log into the platform.
-- A user can belong to an agency (agency staff) or a tenant (tenant staff).
-- Platform admins have neither agency_id nor tenant_id.
-- =============================================================================

CREATE TABLE users (
    -- Primary Key
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    -- Relationships (one or none, not both)
    agency_id UUID REFERENCES agencies(id),  -- NULL if platform admin or tenant user
    tenant_id UUID REFERENCES tenants(id),   -- NULL if platform admin or agency user
    
    -- Authentication
    email VARCHAR(255) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,  -- bcrypt hash
    
    -- Profile
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    phone VARCHAR(50),
    avatar_url VARCHAR(500),
    
    -- Role (see user_roles table for detailed permissions)
    role VARCHAR(50) NOT NULL DEFAULT 'user',
    -- Possible roles:
    -- 'platform_admin' - Full platform access (aiConnected staff)
    -- 'agency_admin' - Full agency access
    -- 'agency_user' - Limited agency access
    -- 'tenant_admin' - Full tenant access
    -- 'tenant_user' - Limited tenant access
    
    -- Status
    status VARCHAR(50) NOT NULL DEFAULT 'active',  -- active, suspended, invited
    is_verified BOOLEAN NOT NULL DEFAULT FALSE,     -- Email verified
    
    -- Security
    last_login_at TIMESTAMPTZ,
    last_login_ip VARCHAR(45),  -- IPv6 can be 45 chars
    failed_login_attempts INTEGER NOT NULL DEFAULT 0,
    locked_until TIMESTAMPTZ,
    
    -- Password Reset
    password_reset_token VARCHAR(255),
    password_reset_expires TIMESTAMPTZ,
    
    -- Email Verification
    email_verification_token VARCHAR(255),
    email_verified_at TIMESTAMPTZ,
    
    -- Preferences
    preferences JSONB NOT NULL DEFAULT '{}'::jsonb,
    -- Example preferences:
    -- {
    --   "theme": "dark",
    --   "timezone": "America/Los_Angeles",
    --   "notifications": {
    --     "email": true,
    --     "sms": false
    --   },
    --   "dashboard": {
    --     "default_view": "calls"
    --   }
    -- }
    
    -- Timestamps
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ DEFAULT NULL,
    
    -- Constraints
    CONSTRAINT uq_users_email UNIQUE (email),
    CONSTRAINT ck_users_status CHECK (status IN ('active', 'suspended', 'invited')),
    CONSTRAINT ck_users_role CHECK (role IN ('platform_admin', 'agency_admin', 'agency_user', 'tenant_admin', 'tenant_user')),
    -- User must belong to agency OR tenant OR neither (platform admin), not both
    CONSTRAINT ck_users_ownership CHECK (
        (agency_id IS NULL AND tenant_id IS NULL) OR  -- platform admin
        (agency_id IS NOT NULL AND tenant_id IS NULL) OR  -- agency user
        (agency_id IS NULL AND tenant_id IS NOT NULL)  -- tenant user
    )
);

-- Indexes
CREATE INDEX ix_users_email ON users(email) WHERE deleted_at IS NULL;
CREATE INDEX ix_users_agency_id ON users(agency_id) WHERE deleted_at IS NULL;
CREATE INDEX ix_users_tenant_id ON users(tenant_id) WHERE deleted_at IS NULL;
CREATE INDEX ix_users_role ON users(role) WHERE deleted_at IS NULL;
CREATE INDEX ix_users_status ON users(status) WHERE deleted_at IS NULL;

-- Trigger for updated_at
CREATE TRIGGER update_users_updated_at
    BEFORE UPDATE ON users
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

-- Comments
COMMENT ON TABLE users IS 'Human users who log into the platform';
COMMENT ON COLUMN users.password_hash IS 'bcrypt hashed password, never store plaintext';
COMMENT ON COLUMN users.role IS 'User role determining permission level';
COMMENT ON COLUMN users.failed_login_attempts IS 'Counter for rate limiting, reset on successful login';