---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/ai
- domain/devops
- tech/celery
- tech/docker
- tech/fastapi
- tech/llamaindex
- tech/nextjs
- tech/postgresql
- tech/python
- tech/react
- tech/redis
- tech/typescript
- type/project
type: project
---

# Oliver AI Assistant - Developer Manual

## Architecture Overview

Oliver AI Assistant is a full-stack application split into two main components:

1. **Frontend**: Built with Next.js, React, and Tailwind CSS. Handles the UI, state management, and API interactions.
2. **Backend**: Built with FastAPI (Python), handling business logic, database interactions, and AI service orchestration.

### High-Level Flow

1. **Client** (Next.js) sends HTTP/WebSocket requests to **Backend** (FastAPI).
2. **Backend** processes requests using services like `DocumentProcessor`, `EmbeddingService`, and `VectorStoreFactory`.
3. **Data Layer** uses PostgreSQL for relational data and a Vector Store (e.g., pgvector) for embeddings.
4. **Async Tasks** (Celery) handle heavy lifting like SharePoint sync and file processing in the background via Redis.

## Tech Stack

- **Frontend**: Next.js 14+, React, TypeScript, Tailwind CSS, Axios/WebSockets.
- **Backend**: Python 3.11+, FastAPI, SQLAlchemy (Async), Pydantic, Celery, Redis.
- **Database**: PostgreSQL (Main DB + Vector Extensions).
- **Object Storage**: MinIO (for temporary file storage).
- **Task Queue**: Celery + Redis (Broker/Backend).
- **ORM/Alchemy**: Alembic for migrations.

## Local Setup

### Prerequisites

- Python 3.11+
- Node.js 18+
- PostgreSQL 14+
- Redis 7+
- Docker & Docker Compose (recommended for infrastructure)

### Step 1: Clone and Install Dependencies

```bash
# Clone the repository
git clone <repo-url>
cd oliver-ai-assistant

# Install Backend dependencies
pip install -r backend/requirements.txt

# Install Frontend dependencies
cd frontend
npm install
cd ..
```

### Step 2: Environment Variables

Copy the `.env.example` files to `.env` in both root and backend directories. Fill in required values:

```bash
cp backend/.env.example backend/.env
cp frontend/.env.local frontend/.env.local
```

Key Variables:
- `DATABASE_URL`: PostgreSQL connection string.
- `REDIS_URL`: Redis connection string (default `redis://localhost:6379/0`).
- `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`: MinIO credentials.
- `OPENAI_API_KEY`: API key for embedding and chat models.
- `SHAREPOINT_CLIENT_ID`, `SHAREPOINT_CLIENT_SECRET`: SharePoint credentials.

### Step 3: Start Infrastructure

```bash
docker-compose up -d postgres redis minio
```

### Step 4: Database Migrations

```bash
# Run main database migrations
alembic upgrade head

# Run vector database migrations
cd backend
alembic -c alembic_vectors.ini upgrade head
```

### Step 5: Run Services

#### Backend
```bash
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

#### Celery Worker
```bash
cd backend
celery -A app.worker.celery_app worker --loglevel=info -Q default
```

#### Frontend
```bash
cd frontend
npm run dev
```

## Environment Variables

| Variable | Description | Required |
|---|---|---|
| `ENV` | Environment mode (development/production) | Yes |
| `DATABASE_URL` | PostgreSQL URI | Yes |
| `REDIS_URL` | Redis URI for Celery/Cache | Yes |
| `MINIO_ENDPOINT` | MinIO host | Yes |
| `MINIO_BUCKET` | Bucket name for file storage | Yes |
| `OPENAI_API_KEY` | Key for AI models | Yes |
| `SECRET_KEY` | JWT Signing Secret | Yes |
| `CORS_ORIGINS` | Comma-separated list of allowed origins | Yes |

## Key Services & Entry Points

### Backend (`backend/app/`)

- **`app/main.py`**: FastAPI application entry point. Manages lifespan (startup/shutdown), middleware setup, and route registration.
- **`app/config.py`**: `RuntimeConfig` class handles loading configuration from DB/Redis with fallback to `.env`. Ensures thread-safe caching.
- **`app/worker.py`**: Celery configuration. Defines tasks like `sync_all_sharepoint`, `cleanup_temp_files`, and scheduled beat jobs.
- **`app/core/document_processor.py`**: Logic for chunking, cleaning, and preparing documents for embedding.
- **`app/core/embedding_service.py`**: Interfaces with AI providers (e.g., OpenAI) to generate vector embeddings.
- **`app/core/vector_store_factory.py`**: Factory pattern to switch between vector store implementations (e.g., pgvector, Pinecone).
- **`app/services/sharepoint_sync.py`**: Handles OAuth2 authentication with Microsoft Graph API and folder synchronization logic.

### Frontend (`frontend/src/`)

- **`app/`**: Next.js App Router pages. `app/chat/page.tsx` is the main AI interface.
- **`components/`**: Reusable UI components (e.g., `ChatInput`, `MessageBubble`).
- **`lib/api.ts`**: API client functions for making requests to the FastAPI backend.

## API Reference

The API follows RESTful conventions and WebSocket for real-time chat.

### Authentication
- **Endpoint**: `POST /api/auth/login`
- **Body**: `{ "email": "user@example.com", "password": "pass" }`
- **Response**: `{ "access_token": "...", "refresh_token": "..." }`

### Chat
- **Endpoint**: `WebSocket /ws/chat` or `POST /api/chat`
- **Payload**: `{ "message": "What is Oliver?", "session_id": "..." }`
- **Response**: `{ "reply": "Oliver is...", "tokens_used": 120 }`

### Admin
- **Endpoint**: `GET /api/admin/users`
- **Auth**: Admin Bearer Token required.
- **Response**: List of user objects.

## Deployment

### Backend
The backend is configured for standalone deployment via `next.config.js` and `pyproject.toml`. Use Docker:

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY backend/. /app
RUN pip install --no-cache-dir -r requirements.txt
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### Frontend
Build the static site:

```bash
cd frontend
npm run build
npm run export # Or next build for standalone output
```

Deploy via Nginx or a static site host (Vercel/Netlify) for the frontend, and a cloud provider (AWS ECS, Azure App Service) for the backend.

## Known Gotchas

1. **Vector Indexing**: Ensure the `pgvector` extension is enabled in PostgreSQL before running migrations. If the database is empty, initial sync tasks may fail silently if not monitored.
2. **Celery Beat**: The `beat_schedule` in `app/worker.py` runs every 4 hours for sync. Ensure the Celery Beat container is running alongside the worker.
3. **Redis Limits**: Default Redis memory limits may need adjustment if storing large numbers of session tokens or config caches.
4. **CORS**: When deploying, update `CORS_ORIGINS` in the backend `.env` to include your frontend's domain to avoid preflight failures.
5. **Timezones**: Celery tasks use UTC. Ensure server time is synchronized or use `enable_utc=True` in Celery config.

## Related
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL]]
- [[01 Projects/Oliver-ai-bot_2.0/DEVELOPER_MANUAL]]
- [[01 Projects/enterprise-ai-hub-nexus/DEVELOPER_MANUAL]]
- [[01 Projects/Oliver-ai-bot_2.0/DEVELOPER_MANUAL.md]]
- [[01 Projects/enterprise-ai-hub-nexus/DEVELOPER_MANUAL.md]]
- [[01 Projects/presenton/DEVELOPER_MANUAL.md]]
- [[01 Projects/sandbox-notebookllamalm-nextjs/DEVELOPER_MANUAL.md]]