a8151fbe66
Backend Tests: - Add pytest configuration with async support (conftest.py) - Add model tests: User, Conversation, Message, TokenUsage, Session, UserMemory - Add configuration tests: Settings validation and environment variables - Add API tests: Health endpoint and future endpoint stubs - Add database tests: Connection, transactions, query execution Phase 1 Foundation: - FastAPI application structure with main.py - SQLAlchemy async models for all entities - Alembic migrations setup - Configuration management via Pydantic Settings - Logging system (English only) - Docker multi-stage builds for backend - Docker Compose orchestration (PostgreSQL, Redis, backend) - Frontend React + TypeScript structure - Dark & Gold theme CSS implementation - Environment configuration examples All code and comments in English as per requirements. Tests cover model relationships, cascade deletes, and constraints. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
213 lines
4.6 KiB
Markdown
213 lines
4.6 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
|
|
```
|
|
|
|
**Required 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
|
|
|
|
### 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)
|
|
|
|
### 4. Access the application
|
|
|
|
- **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.
|