apac-ops-bot/README.md

APAC Ops Bot

AI-powered operations assistant for Oliver Agency's APAC region. Built with FastAPI, React, and OpenAI Responses API.

Features

• 🔐 Azure AD Authentication - Secure SSO via MSAL with PKCE flow
• 🤖 RAG-powered Chatbot - Strictly answers from Vector Store documents (no hallucinations)
• 💬 Multi-turn Conversations - Maintains context across conversation history
• 📊 Token Usage Tracking - Complete analytics and cost monitoring
• 🎨 Dark & Gold UI - Beautiful, professional interface
• 🐳 Dockerized - Easy deployment with Docker Compose

Tech Stack

Backend:

• FastAPI (Python 3.11+)
• PostgreSQL + SQLAlchemy
• Redis
• OpenAI Responses API
• MSAL Authentication

Frontend:

• React 18 + TypeScript
• MSAL React
• TailwindCSS
• WebSocket for real-time

Prerequisites

• Docker & Docker Compose
• OpenAI API Key with access to Responses API
• Azure AD Application (for MSAL authentication)

Quick Start

1. Clone the repository

git clone <repository-url>
cd apac-ops-bot

2. Configure environment variables

Backend:

cd backend
cp .env.example .env
# Edit .env with your actual values

Frontend:

cd ../frontend
cp .env.example .env
# Edit .env with your actual values

Required Backend environment variables:

• SECRET_KEY - Generate with: openssl rand -hex 32
• AZURE_TENANT_ID - Your Azure AD tenant ID
• AZURE_CLIENT_ID - Your Azure AD application client ID
• AZURE_CLIENT_SECRET - Your Azure AD application client secret
• OPENAI_API_KEY - Your OpenAI API key
• OPENAI_VECTOR_STORE_ID - Your Vector Store ID (default: vs_QkOKiQCqzCHS4iFT5lP9qUxc)

Required Frontend environment variables:

• REACT_APP_AZURE_CLIENT_ID - Same as backend Azure client ID
• REACT_APP_AZURE_TENANT_ID - Same as backend Azure tenant ID
• REACT_APP_API_URL - Backend API URL (default: /apac-ops-bot-back/api/v1)

3. Start services with Docker Compose

# From project root
docker-compose up --build

This will start:

• PostgreSQL (port 5432)
• Redis (port 6399)
• Backend API (port 8048)
• Frontend (port 3000)

First run: The backend will automatically create database tables on startup.

4. Access the application

• Frontend Application: http://localhost:3000
• API Documentation: http://localhost:8048/docs
• Health Check: http://localhost:8048/health

Development

Backend Development

# Install dependencies
cd backend
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run migrations
alembic upgrade head

# Start development server
uvicorn app.main:app --reload

Frontend Development

# Install dependencies
cd frontend
npm install

# Start development server
npm start

Database Migrations

# Create a new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1

Docker Commands

# Start all services
docker-compose up

# Start in detached mode
docker-compose up -d

# View logs
docker-compose logs -f backend

# Stop services
docker-compose down

# Rebuild containers
docker-compose up --build

# Run migrations in container
docker-compose exec backend alembic upgrade head

# Access PostgreSQL
docker-compose exec postgres psql -U apac_ops_bot

Project Structure

apac-ops-bot/
├── backend/                # FastAPI backend
│   ├── app/
│   │   ├── api/           # API endpoints
│   │   ├── models/        # SQLAlchemy models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── services/      # Business logic
│   │   ├── repositories/  # Data access layer
│   │   └── core/          # Security, middleware
│   ├── alembic/           # Database migrations
│   └── tests/             # Backend tests
│
├── frontend/              # React frontend
│   └── src/
│       ├── components/    # React components
│       ├── context/       # State management
│       ├── hooks/         # Custom hooks
│       └── services/      # API services
│
└── docker-compose.yml     # Docker services configuration

API Documentation

Once the backend is running, access the interactive API documentation at:

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

Security

• All code and comments are in English only
• Strict RAG-only responses (no AI hallucinations)
• MSAL PKCE flow for authentication
• Token hashing before storage
• Rate limiting enabled
• CORS configured
• SQL injection protection via ORM

Testing

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

Deployment

See DEPLOYMENT.md for production deployment instructions.

Contributing

1. All code, comments, and commit messages must be in English
2. Follow existing code style (Black for Python, Prettier for TypeScript)
3. Write tests for new features
4. Update documentation as needed

License

Proprietary - Oliver Agency

Support

For issues and questions, please contact the development team.