---
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/devops
- domain/security
- tech/azure-ad
- tech/celery
- tech/docker
- tech/fastapi
- tech/lamaindex
- tech/nextjs
- tech/postgresql
- tech/python
- tech/rag
- tech/redis
- tech/typescript
- type/sop
type: sop
---

# Oliver AI Bot 2.0 (Nexus MVP) - Developer Manual

## Architecture Overview

Nexus is a microservices-oriented monorepo structured for scalability and security. It runs in production on a GCE VM using Docker Compose, with heavy processing offloaded to Google Cloud Run.

### Core Components
1.  **Backend (FastAPI/Python):** The central API handling auth, business logic, and orchestration.
2.  **Frontend (Next.js 14):** SPA serving the UI and handling client-side routing.
3.  **Database (PostgreSQL 16):** Relational storage for users, metadata, and config.
4.  **Vector DB (Qdrant):** Stores document embeddings for RAG retrieval.
5.  **Cache/Broker (Redis 7):** Manages rate limiting, session storage, and Celery task queues.
6.  **Worker Service (Cloud Run):** Stateless Python/FastAPI service for heavy document parsing (LLAMAParse integration).

## Technology Stack

*   **Backend:** Python 3.11, FastAPI, SQLAlchemy (Async), Pydantic Settings.
*   **Frontend:** Next.js 14, TypeScript, Tailwind CSS.
*   **Infrastructure:** Docker Compose, GCE, Google Cloud Run, Apache (Reverse Proxy).
*   **Auth:** Microsoft Entra ID (Azure AD), JWT (HS256), Python-JWT.
*   **AI/ML:** OpenAI/Anthropic/Google LLMs, Qdrant (Vector DB), LangChain/LlamaIndex (implied by RAG pipeline).

## Local Setup

### Prerequisites
*   Docker & Docker Compose
*   Python 3.11+
*   Node.js 18+

### Steps
1.  **Clone Repository:**
    ```bash
    git clone <repo_url>
    cd nexus-mvp
    ```
2.  **Environment Configuration:**
    ```bash
    cp backend/.env.example backend/.env
    # Edit .env with your local DB passwords and Azure AD credentials
    ```
3.  **Start Infrastructure:**
    ```bash
    docker-compose up -d db redis qdrant
    ```
4.  **Backend Setup:**
    ```bash
    cd backend
    pip install -r requirements.txt
    python seed_data.py  # Initialize regions/departments
    uvicorn app.main:app --reload
    ```
5.  **Frontend Setup:**
    ```bash
    cd frontend
    npm install
    npm run dev
    ```

## Environment Variables

Key variables are defined in `.env.example` and `docker-compose.yml`:

| Variable | Description | Default/Example |
| :--- | :--- | :--- |
| `ENTRA_CLIENT_ID` | Azure AD App Registration Client ID | Required |
| `ENTRA_CLIENT_SECRET` | Azure AD App Registration Secret | Required |
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://...@db:5432/nexus_db` |
| `REDIS_URL` | Redis connection string | `redis://redis:6379/0` |
| `QDRANT_URL` | Qdrant Vector DB URL | `http://qdrant:6333` |
| `JWT_SECRET` | Secret for signing JWT tokens | Required |
| `OPENAI_API_KEY` | OpenAI API Key for LLMs | Required |
| `LOG_LEVEL` | Logging verbosity | `INFO` |

## Key Services & Entry Points

*   **`backend/app/main.py`**: FastAPI application entry point. Includes CORS, Rate Limiting, and Auth middleware.
*   **`backend/app/config.py`**: Pydantic `BaseSettings` class for type-safe environment variable loading.
*   **`backend/celery_app.py`**: Celery configuration. Defines workers, queues (`sharepoint`, `default`), and beat schedules (e.g., hourly SharePoint sync, 30-min token refresh).
*   **`backend/cloud_run_service.py`**: Standalone FastAPI app deployed to Cloud Run. Handles `POST /process-document` for heavy text extraction/chunking, returning raw chunks for the main backend to embed.
*   **`backend/seed_data.py`**: Script to populate initial `Region` and `Department` taxonomy data.

## API Reference

### Authentication
*   `POST /api/v1/auth/login`: Initiates Entra ID PKCE flow.
*   `GET /api/v1/auth/callback`: Handles OAuth2 callback from Azure AD.

### Documents
*   `POST /api/v1/documents/upload`: Uploads file to Qdrant/Postgres.
*   `GET /api/v1/documents/search?q=<query>`: Retrieves context for RAG.

### Health
*   `GET /health`: Standard health check for all services.

## Deployment

### Production (GCE + Cloud Run)
1.  **Backend:** Deploy Docker container to GCE VM. Use Apache as reverse proxy (`/etc/apache2/sites-available/nexus.conf`).
2.  **Workers:** Scale Celery workers on GCE VM.
3.  **Cloud Run:** Deploy `backend/cloud_run_service.py` as a separate service in Google Cloud Run for elastic scaling during peak document processing.
4.  **Database:** Use managed PostgreSQL (Cloud SQL) and Redis (Memorystore) in production instead of Docker containers.

### Docker Compose
For local/dev/staging, use `docker-compose.yml`. It orchestrates `db`, `redis`, `qdrant`, and `backend` services.

## Known Gotchas

1.  **Azure AD Redirect URI:** Ensure `ENTRA_REDIRECT_URI` matches the Azure Portal configuration exactly. Defaults to `http://localhost:8000/api/v1/auth/callback` locally.
2.  **Qdrant Ports:** Qdrant exposes `6333` (HTTP) and `6334` (gRPC). Ensure firewall rules allow this.
3.  **Celery Timeouts:** Task hard limit is 30 mins. Heavy documents may fail if they exceed this; consider increasing `task_time_limit` or splitting large files before upload.
4.  **JWT Expiration:** Default is 15 minutes. Refresh tokens last 7 days. Ensure frontend handles silent refresh properly.
5.  **Environment Consistency:** Never commit `.env`. Use `.env.example` as the source of truth for config keys.

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