e100f83cb6
Changes: - Uncommented frontend service in docker-compose.yml - Updated README.md with complete setup instructions for both backend and frontend - Added DEPLOYMENT.md with comprehensive production deployment guide Docker Compose: - Frontend now included in docker-compose up - All services (postgres, redis, backend, frontend) start together - Frontend runs on port 3000 with hot reload in development mode README Updates: - Added frontend .env setup instructions - Listed all required environment variables for both services - Updated "Access the application" section with frontend URL - Clarified that database tables are created automatically on first run DEPLOYMENT.md (new): - Complete production deployment guide - Server setup with Docker installation - Production environment configuration - Nginx reverse proxy setup with SSL/TLS - Let's Encrypt SSL certificate instructions - Database backup and restore procedures - Monitoring and logging setup - Security checklist - Performance optimization tips - Scaling strategies for high-traffic scenarios - Troubleshooting guide Now users can: 1. Run `docker-compose up --build` to start all services 2. Access frontend at http://localhost:3000 3. Access backend API at http://localhost:8000 4. Follow DEPLOYMENT.md for production deployment Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
230 lines
5.1 KiB
Markdown
230 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd apac-ops-bot
|
|
```
|
|
|
|
### 2. Configure environment variables
|
|
|
|
**Backend:**
|
|
```bash
|
|
cd backend
|
|
cp .env.example .env
|
|
# Edit .env with your actual values
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
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: http://localhost:8000/api/v1)
|
|
|
|
### 3. Start services with Docker Compose
|
|
|
|
```bash
|
|
# From project root
|
|
docker-compose up --build
|
|
```
|
|
|
|
This will start:
|
|
- PostgreSQL (port 5432)
|
|
- Redis (port 6379)
|
|
- Backend API (port 8000)
|
|
- 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:8000/docs
|
|
- **Health Check:** http://localhost:8000/health
|
|
|
|
## Development
|
|
|
|
### Backend Development
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Install dependencies
|
|
cd frontend
|
|
npm install
|
|
|
|
# Start development server
|
|
npm start
|
|
```
|
|
|
|
### Database Migrations
|
|
|
|
```bash
|
|
# Create a new migration
|
|
alembic revision --autogenerate -m "description"
|
|
|
|
# Apply migrations
|
|
alembic upgrade head
|
|
|
|
# Rollback migration
|
|
alembic downgrade -1
|
|
```
|
|
|
|
### Docker Commands
|
|
|
|
```bash
|
|
# 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:8000/docs
|
|
- ReDoc: http://localhost:8000/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
|
|
|
|
```bash
|
|
# Backend tests
|
|
cd backend
|
|
pytest
|
|
|
|
# Frontend tests
|
|
cd frontend
|
|
npm test
|
|
```
|
|
|
|
## Deployment
|
|
|
|
See [DEPLOYMENT.md](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.
|