---
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/security
- tech/azure-ad
- tech/docker
- tech/fastapi
- tech/gemini
- tech/nextjs
- tech/postgresql
- tech/python
- tech/redis
- type/sop
type: sop
---

# Enterprise AI Hub Nexus - Developer Manual

## Architecture Overview
Nexus is a microservices-based architecture deployed on a Google Cloud Engine (GCE) VM with Docker Compose, supplemented by Google Cloud Run for heavy document processing tasks.

### High-Level Components
1. **Frontend**: Next.js 14 application (SSG/SSR hybrid).
2. **Backend**: FastAPI (Python 3.11) handling business logic, auth, and API routes.
3. **Database**: PostgreSQL 16 for relational data (users, metadata).
4. **Vector DB**: Qdrant for RAG embeddings and semantic search.
5. **Cache/Queue**: Redis for caching and task queues.
6. **Processing Service**: Google Cloud Run microservice for heavy document ingestion.

## Tech Stack
- **Frontend**: Next.js 14, React, Tailwind CSS, Lucide Icons, Radix UI.
- **Backend**: Python 3.11, FastAPI, SQLAlchemy, Pydantic.
- **Auth**: Microsoft Entra ID (Azure AD) with PKCE, JWT (HS256).
- **Data**: PostgreSQL, Redis, Qdrant.
- **AI**: OpenAI, Anthropic, Google Gemini APIs.

## Local Setup

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

### Steps
1. **Clone the repository**.
2. **Configure Environment**:
   ```bash
   cp .env.example .env
   # Edit .env with your local/dev values
   ```
3. **Start Infrastructure**:
   ```bash
   docker-compose up -d db redis qdrant
   ```
4. **Install Backend Dependencies**:
   ```bash
   cd backend
   pip install -r requirements.txt
   ```
5. **Run Backend**:
   ```bash
   uvicorn main:app --reload --host 0.0.0.0 --port 8000
   ```
6. **Install Frontend Dependencies**:
   ```bash
   cd frontend
   npm install
   ```
7. **Run Frontend**:
   ```bash
   npm run dev
   ```
8. **Access**: Frontend at `http://localhost:3000`, Backend at `http://localhost:8000`.

## Environment Variables
Key variables in `.env`:

| Variable | Description | Example |
|----------|-------------|---------|
| `ENVIRONMENT` | App mode (`development`, `production`) | `development` |
| `DEBUG` | Enable debug mode | `true` |
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://user:pass@db:5432/nexus_db` |
| `REDIS_URL` | Redis connection string | `redis://redis:6379/0` |
| `QDRANT_URL` | Vector DB URL | `http://qdrant:6333` |
| `ENTRA_CLIENT_ID` | Azure AD App Registration Client ID | `uuid-here` |
| `ENTRA_TENANT_ID` | Azure AD Tenant ID | `uuid-here` |
| `ENTRA_REDIRECT_URI` | Callback URL for Auth | `http://localhost:8000/api/v1/auth/callback` |
| `JWT_SECRET` | Secret for signing JWTs | `secure-string` |
| `OPENAI_API_KEY` | OpenAI API Key | `sk-...` |
| `GOOGLE_API_KEY` | Google Gemini API Key | `AIza...` |
| `ANTHROPIC_API_KEY` | Anthropic API Key | `sk-ant-...` |

## Key Services & Entry Points

### Backend Entry Point
- **File**: `backend/main.py` (or similar, based on FastAPI structure)
- **Router**: `/api/v1/`
- **Auth Callback**: `/api/v1/auth/callback`

### Database Migrations
- Use Alembic for SQLAlchemy migrations.
- Run migrations before starting the backend:
  ```bash
  alembic upgrade head
  ```

### Qdrant Collection
- Ensure a collection exists in Qdrant (e.g., `nexus_knowledge`) for storing embeddings.

## API Reference
- **Base URL**: `http://localhost:8000/api/v1`
- **Auth**: Bearer Token (JWT) required for most endpoints.

#### Key Endpoints
- `POST /auth/login`: Initiates Entra ID login flow.
- `GET /auth/callback`: Handles OAuth2 redirect.
- `GET /chat`: Retrieve chat history.
- `POST /chat`: Send message and get RAG response.
- `POST /docs/upload`: Upload document to knowledge base.
- `GET /docs`: List documents.

## Deployment
### Production
1. **Infrastructure**: Deploy on GCE VM (`optical-web-1`).
2. **Reverse Proxy**: Apache serves as the reverse proxy.
3. **Docker Compose**: Manages backend services (db, redis, qdrant, backend).
4. **Cloud Run**: Handles heavy document processing tasks.
5. **Environment**: Set `ENVIRONMENT=production` and `LOG_LEVEL=INFO`.
6. **Security**: 
   - Never commit `.env`.
   - Use strong passwords for DB.
   - Ensure CORS origins are restricted to `https://ai-sandbox.oliver.solutions`.

## Known Gotchas
1. **CORS Errors**: Ensure `CORS_ORIGINS` in `.env` matches the frontend URL exactly.
2. **DB Health Check**: The `docker-compose.yml` includes health checks for DB, Redis, and Qdrant. If services fail to start, check `pg_isready` and `redis-cli ping`.
3. **Entra ID Redirect URI**: Must exactly match the configured URI in the Azure Portal App Registration.
4. **Qdrant Port**: Qdrant exposes both HTTP (6333) and gRPC (6334) ports. The backend uses HTTP.
5. **JWT Expiration**: Default is 15 minutes for access tokens (configured via `JWT_EXPIRATION_MINUTES`), but the README mentions 8-hour lifetime. Verify if refresh tokens are used for extended sessions.

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