AI Receptionist Platform

A multi-tenant SaaS platform that enables businesses to deploy and configure AI-powered receptionists that communicate with customers primarily through WhatsApp.

Features

• 🤖 AI-powered conversational receptionist using OpenAI
• 💬 WhatsApp Business Platform integration
• 📅 Google Calendar integration for appointments
• 📚 RAG-based knowledge retrieval with pgvector
• 🔐 Secure multi-tenant architecture with complete data isolation
• 📊 Business dashboard for monitoring and management
• 🔄 LangGraph-based AI workflow orchestration

Architecture

The platform follows a three-tier architecture:

• Frontend: Next.js 14 (App Router) with TypeScript and Tailwind CSS
• Backend: Python FastAPI with async support
• Database: PostgreSQL 15+ with pgvector extension

Project Structure

ai-receptionist-platform/
├── apps/
│   ├── web/                    # Next.js Business Dashboard
│   └── api/                    # FastAPI Backend
├── infra/                      # Docker and deployment configs
├── packages/                   # Shared packages (optional)
├── docs/                       # Documentation
└── docker-compose.yml          # Local development environment

Prerequisites

• Node.js 20+
• Python 3.11+
• Docker and Docker Compose
• PostgreSQL 15+ (or use Docker)
• OpenAI API key
• WhatsApp Business Account (for production)
• Google Cloud Project with Calendar API enabled (for production)

Getting Started

1. Clone the repository

git clone <repository-url>
cd ai-receptionist-platform

2. Set up environment variables

Backend:

cp apps/api/.env.example apps/api/.env
# Edit apps/api/.env with your configuration

Frontend:

cp apps/web/.env.example apps/web/.env
# Edit apps/web/.env with your configuration

3. Start with Docker Compose (Recommended)

docker-compose up -d

This will start:

• PostgreSQL with pgvector (port 5432)
• FastAPI backend (port 8000)
• Next.js frontend (port 3000)

4. Manual Setup (Alternative)

Backend Setup

cd apps/api

# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

# Run database migrations
poetry run alembic upgrade head

# Start the server
poetry run uvicorn app.main:app --reload

Frontend Setup

cd apps/web

# Install dependencies
npm install

# Start development server
npm run dev

Development

Backend Development

cd apps/api

# Run tests
poetry run pytest

# Format code
poetry run black .
poetry run ruff check --fix .

# Type checking
poetry run mypy app

Frontend Development

cd apps/web

# Run linter
npm run lint

# Format code
npm run format

# Build for production
npm run build

Pre-commit Hooks

Install pre-commit hooks to ensure code quality:

# Install pre-commit
pip install pre-commit

# Install git hooks
pre-commit install

# Run manually
pre-commit run --all-files

API Documentation

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Database Migrations

cd apps/api

# Create a new migration
poetry run alembic revision --autogenerate -m "Description"

# Apply migrations
poetry run alembic upgrade head

# Rollback
poetry run alembic downgrade -1

Testing

# Backend tests
cd apps/api
poetry run pytest

# Frontend tests
cd apps/web
npm test

Deployment

See docs/deployment-guide.md for production deployment instructions.

Environment Variables

Backend (.env)

Key variables:

• DATABASE_URL: PostgreSQL connection string
• SECRET_KEY: JWT secret key
• OPENAI_API_KEY: OpenAI API key
• WHATSAPP_API_KEY: WhatsApp Business Platform credentials
• GOOGLE_CLIENT_ID: Google OAuth credentials

See apps/api/.env.example for full list.

Frontend (.env)

Key variables:

• NEXT_PUBLIC_API_URL: Backend API URL
• NEXTAUTH_SECRET: NextAuth.js secret

See apps/web/.env.example for full list.

Contributing

1. Create a feature branch
2. Make your changes
3. Run tests and linting
4. Submit a pull request

License

[Add your license here]

Support

For support, please contact [your-contact-info].