apac-ops-bot/QUICKSTART.md

Quick Start Guide - APAC Ops Bot

Phase 1: Foundation - COMPLETED ✅

What's Been Built

Backend:

• ✅ FastAPI application structure
• ✅ PostgreSQL database setup via Docker
• ✅ Redis for caching
• ✅ SQLAlchemy models (User, Conversation, Message, TokenUsage, Session, UserMemory)
• ✅ Alembic migrations setup
• ✅ Configuration management
• ✅ Logging system
• ✅ Multi-stage Dockerfile

Frontend:

• ✅ React 18 + TypeScript project
• ✅ Dark & Gold theme CSS
• ✅ Basic UI structure
• ✅ Multi-stage Dockerfile
• ✅ Environment configuration

---

Prerequisites

1. Docker Desktop - Install from https://www.docker.com/products/docker-desktop
2. Node.js 18+ (for local frontend development)
3. Python 3.11+ (for local backend development)

---

Getting Started

Step 1: Configure Azure AD (Required for Authentication)

1. Go to Azure Portal
2. Navigate to "Azure Active Directory" → "App registrations"
3. Click "New registration"
4. Configure:
   • Name: "APAC Ops Bot"
   • Supported account types: "Accounts in this organizational directory only"
   • Redirect URI: http://localhost:8048/api/v1/auth/msal/callback
5. After registration, note down:
   • Application (client) ID
   • Directory (tenant) ID
6. Go to "Certificates & secrets" → "New client secret"
7. Note down the Client secret value

Step 2: Update Environment Variables

Backend (backend/.env):

# Update these with your Azure AD values:
AZURE_TENANT_ID=your-actual-tenant-id
AZURE_CLIENT_ID=your-actual-client-id
AZURE_CLIENT_SECRET=your-actual-client-secret

Frontend (frontend/.env):

# Update these with your Azure AD values:
REACT_APP_AZURE_CLIENT_ID=your-actual-client-id
REACT_APP_AZURE_TENANT_ID=your-actual-tenant-id

Step 3: Start with Docker (Recommended)

# From project root
cd /Volumes/SSD/Projects/Oliver/APAC\ ops\ Bot/apac-ops-bot

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

# Wait for services to be healthy (about 10 seconds)
docker-compose logs postgres

# Build and start backend
docker-compose up --build backend

The backend will be available at: http://localhost:8048

• API Docs: http://localhost:8048/docs
• Health Check: http://localhost:8048/health

Step 4: Run Database Migrations

# In a new terminal, run migrations
docker-compose exec backend alembic upgrade head

Step 5: Start Frontend (Local Development)

# Open new terminal
cd frontend

# Install dependencies
npm install

# Start development server
npm start

The frontend will be available at: http://localhost:3000

---

Verify Installation

Test Backend

# Health check
curl http://localhost:8048/health

# Expected response:
# {"status":"healthy","app":"The APAC OpsBot","environment":"development"}

Test Frontend

1. Open http://localhost:3000 in your browser
2. You should see the "The APAC OpsBot" welcome screen with:
   • Gold header with robot avatar
   • Welcome message
   • Message input field

---

Project Structure

apac-ops-bot/
├── backend/               # FastAPI backend
│   ├── app/
│   │   ├── models/       # Database models ✅
│   │   ├── api/          # API endpoints (Phase 2)
│   │   ├── services/     # Business logic (Phase 2)
│   │   └── ...
│   ├── alembic/          # Database migrations ✅
│   ├── .env              # Environment config ✅
│   └── Dockerfile        # Docker config ✅
│
├── frontend/             # React frontend
│   ├── src/
│   │   ├── components/   # React components (Phase 2)
│   │   ├── styles/       # Dark & Gold theme ✅
│   │   └── App.tsx       # Main app ✅
│   ├── .env              # Environment config ✅
│   └── Dockerfile        # Docker config ✅
│
└── docker-compose.yml    # Services orchestration ✅

---

✅ COMPLETE - All Features Implemented!

Phase 1: ✅ Foundation (Backend + Frontend structure) Phase 2: ✅ Core Features (OpenAI + Auth + Chat) Phase 3: ✅ UI Complete (Sidebar + Analytics + Management)

What's Working:

1. ✅ OpenAI Integration - Responses API with RAG enforcement
2. ✅ Authentication - MSAL with JWT sessions
3. ✅ Chat Functionality - Full conversation management
4. ✅ Token Tracking - Complete analytics dashboard
5. ✅ UI Features - Sidebar, navigation, conversation management

---

Troubleshooting

Docker Issues

Problem: "Cannot connect to Docker daemon" Solution: Start Docker Desktop application

Problem: Port already in use Solution:

# Check what's using the port
lsof -i :8048  # or :5432, :6399

# Stop existing containers
docker-compose down

Backend Issues

Problem: Database connection error Solution:

# Ensure PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres

Frontend Issues

Problem: Module not found Solution:

cd frontend
rm -rf node_modules package-lock.json
npm install

---

Useful Commands

# View all running containers
docker-compose ps

# View logs
docker-compose logs -f backend
docker-compose logs -f postgres

# Stop all services
docker-compose down

# Restart a service
docker-compose restart backend

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

# Run backend tests
docker-compose exec backend pytest

# Access backend shell
docker-compose exec backend bash

---

Environment Configuration

All sensitive data is in .env files (NOT committed to git).

Backend variables:

• SECRET_KEY - JWT secret (generate with: openssl rand -hex 32)
• DATABASE_URL - PostgreSQL connection string
• OPENAI_API_KEY - OpenAI API key (already configured)
• AZURE_* - Azure AD credentials (UPDATE REQUIRED)

Frontend variables:

• REACT_APP_API_URL - Backend API URL
• REACT_APP_AZURE_* - Azure AD credentials (UPDATE REQUIRED)

---

Support

For issues:

1. Check logs: docker-compose logs -f
2. Verify all environment variables are set
3. Ensure Docker Desktop is running
4. Check README.md for detailed documentation

---

Phase 1 Status: ✅ COMPLETE Next Phase: Phase 2 - Core Chat Features