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](https://portal.azure.com)
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:8000/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`):
```bash
# 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`):
```bash
# 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)

```bash
# 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:8000**
- API Docs: http://localhost:8000/docs
- Health Check: http://localhost:8000/health

### Step 4: Run Database Migrations

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

### Step 5: Start Frontend (Local Development)

```bash
# 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

```bash
# Health check
curl http://localhost:8000/health

# Expected response:
# {"status":"healthy","app":"Seapac Ops Bot","environment":"development"}
```

### Test Frontend

1. Open http://localhost:3000 in your browser
2. You should see the "Seapac Ops Bot" 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:**
```bash
# Check what's using the port
lsof -i :8000  # or :5432, :6379

# Stop existing containers
docker-compose down
```

### Backend Issues

**Problem:** Database connection error
**Solution:**
```bash
# Ensure PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres
```

### Frontend Issues

**Problem:** Module not found
**Solution:**
```bash
cd frontend
rm -rf node_modules package-lock.json
npm install
```

---

## Useful Commands

```bash
# 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](README.md) for detailed documentation

---

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