---
name: "Enterprise AI Hub Nexus"
client: Oliver Agency
status: production
tech: [Next.js, FastAPI, PostgreSQL, Qdrant, Docker, Azure AD, OpenAI, Anthropic]
local_path: /Users/ai_leed/Documents/Projects/Oliver/enterprise-ai-hub-nexus
deploy: docker-compose -f docker-compose.prod.yml up -d
url: https://ai-sandbox.oliver.solutions/nexus
server: optical-web-1
tags: [oliver, ai, rag, nextjs, fastapi, azure-ad, m365, qdrant, firecrawl, production]
created: 2026-04-14
last_commit: 2026-04-01
commits: 216
port: 1222
db: PostgreSQL 16
---

## Overview

Enterprise AI Hub Nexus is an internal AI platform for Oliver Agency employees, offering three core capabilities: a RAG-powered knowledge-base chat (Oliver Process Helper), a Microsoft 365 Personal Assistant with delegated M365 access, and a configurable custom-agent builder. The system unifies Azure AD identity management, multi-model LLM orchestration (OpenAI, Anthropic, Google), vector-based document search, and sandboxed code execution in a single web application. Users authenticate via PKCE OAuth2 with Azure AD/Entra ID; feature access is governed by AD group membership. Deployed on GCE VM `optical-web-1` behind Apache reverse proxy at `https://ai-sandbox.oliver.solutions/nexus` in production.

## Tech Stack

- **Frontend:** Next.js 14+, TypeScript, Tailwind CSS, Zustand state management
- **Backend:** FastAPI, Pydantic, SQLAlchemy ORM, Celery (async tasks)
- **Database:** PostgreSQL 16 (metadata), Qdrant v1.12.1 (vectors), Redis 7 (broker/cache)
- **Infrastructure:** Docker Compose, Google Cloud (GCE VM + Cloud Run), Apache 2.4 reverse proxy
- **AI/ML:** OpenAI (embeddings: `text-embedding-3-large`, LLM: `gpt-5.2`), Anthropic (reranking/expansion: `claude-haiku-4-5`, assistant: `claude-sonnet-4-6`), Google Gemini API
- **Key libraries:** FastAPI-CORS, python-jose (JWT), httpx, alembic (migrations), LibreCodeInterpreter (sandboxed execution), Firecrawl (web scraping)

## Architecture

**Multi-tier SPA + FastAPI backend + satellite microservices:**

```
┌─────────────────────────────────────────────────────────────────────────┐
│                          Apache 2.4 Reverse Proxy                       │
│         (optical-web-1, europe-west1, n2d-standard-4 GCE VM)           │
├──────────────────┬──────────────────────────────────┬───────────────────┤
│                  │                                  │                   │
│  ┌─────────────┐ │  ┌──────────────────────────────┐│ ┌───────────────┐ │
│  │   Next.js   │ │  │     FastAPI + Celery         ││ │  Code         │ │
│  │   Static    │ │  │     Docker Container         ││ │  Interpreter  │ │
│  │  Export     │ │  │  (port 1222 → 80/443)        ││ │  Container    │ │
│  │ (/nexus)    │ │  │                              ││ │ (port 8877)   │ │
│  └─────────────┘ │  │  ┌────────────────────────┐  ││ └───────────────┘ │
│                  │  │  │ • Auth (Azure AD PKCE) │  ││                   │
│                  │  │  │ • 14 endpoint modules  │  ││                   │
│                  │  │  │ • RAG retriever        │  ││                   │
│                  │  │  │ • M365 Graph tools     │  ││                   │
│                  │  │  │ • Agent builder        │  ││                   │
│                  │  │  │ • Celery tasks (sync)  │  ││                   │
│                  │  │  └────────────────────────┘  ││                   │
│                  │  └──────────────────────────────┘│                   │
├──────────────────┴──────────────────────────────────┴───────────────────┤
│                          Docker Bridge Network                           │
├──────┬──────────┬──────────┬──────────┬────────────┬──────────────────────┤
│      │          │          │          │            │                      │
│  ┌────────┐ ┌─────────┐┌──────────┐┌──────────┐┌──────┐ ┌──────────────┐ │
│  │Postgres│ │  Redis  ││  Qdrant  ││  MinIO   ││Redis ││ LibreCode    │ │
│  │  :5432 │ │ :6379   ││ :6333    ││  :9000   ││:6379 ││ Interpreter │ │
│  │        │ │         ││          ││          ││      ││   :8000      │ │
│  └────────┘ └─────────┘└──────────┘└──────────┘└──────┘ └──────────────┘ │
│   (metadata) (Celery) (vectors)   (files)   (code)      (sandboxed)      │
└──────────────────────────────────────────────────────────────────────────┘

External Services:
├─ Azure AD / Entra ID (PKCE auth, user profile, AD group sync)
├─ Microsoft Graph API v1.0 (delegated M365 access: mail, calendar, files, teams, people, planner)
├─ Google Cloud Run: nexus-processor (CPU-intensive document extraction/chunking)
└─ OpenAI + Anthropic + Google APIs (LLMs, embeddings, reranking)
```

**Key data flows:**

1. **Auth:** Browser → PKCE login → Azure AD code → Backend JWT + MS Graph access token → AD group sync → feature flags set (`rag`, `assistant`, `admin`)
2. **Chat/RAG:** User message → Config loaded from DB → Query expansion (Haiku) → Vector search (Qdrant) → Reranking (Haiku) → LLM answer (GPT-5.2 or Claude) → SSE stream to client
3. **Document ingestion:** Upload → Firecrawl scrape/crawl → Cloud Run processor → Chunking → OpenAI embeddings → Qdrant indexing → Celery task tracks progress
4. **M365 tools:** User triggers action → Graph token refreshed (with consent check) → Delegated call to Graph API → Return result
5. **Async tasks:** Celery beat scheduler → SharePoint sync, knowledge processing, agent sync tasks → Results stored in DB/Redis

## Dev Commands

```bash
# Clone repo
git clone git@bitbucket.org:zlalani/enterprise-ai-hub-nexus.git
cd enterprise-ai-hub-nexus

# Setup environment
cp backend/.env.example backend/.env
# Edit backend/.env: add OPENAI_API_KEY, ANTHROPIC_API_KEY, JWT_SECRET, ENTRA_CLIENT_ID, ENTRA_TENANT_ID

# Start all local Docker services (Postgres, Redis, Qdrant, Code Interpreter, Backend)
docker-compose -f docker-compose.local.yml up -d

# Run database migrations
docker exec nexus-backend-local alembic upgrade head

# Start frontend dev server (separate terminal)
cd frontend
npm install
npm run dev
# Frontend: http://localhost:3000/nexus

# Verify backend health
curl http://localhost:1222/api/v1/health/live
curl http://localhost:1222/api/v1/health

# Dev login (no Azure AD needed for local dev)
curl -X POST http://localhost:1222/api/v1/auth/login/dev \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","role":"super_admin","display_name":"Dev User"}'

# View logs
docker logs nexus-backend-local -f
docker logs nexus-celery-worker -f

# Stop all services
docker-compose -f docker-compose.local.yml down

# Rebuild after code changes
docker-compose -f docker-compose.local.yml up -d --build nexus-backend-local

# Generate new migration
docker exec nexus-backend-local alembic revision --autogenerate -m "description"

# Swagger API docs
# http://localhost:1222/docs
```

## Deployment

- **Server:** `optical-web-1` (GCE VM, `europe-west1`, machine type `n2d-standard-4`: 4 vCPU, 16 GB RAM)
- **Deploy path:** `/opt/enterprise-ai-hub-nexus/`
- **Web root (frontend):** `/var/www/html/enterprise-ai-hub-nexus/`
- **Deploy command:** 
  ```bash
  cd /opt/enterprise-ai-hub-nexus
  git pull origin main
  ./deploy.sh  # builds frontend, pushes images, runs docker-compose.prod.yml
  ```
- **URL:** `https://ai-sandbox.oliver.solutions/nexus`
- **API base:** `https://ai-sandbox.oliver.solutions/nexus/api/v1`
- **Backend port:** `1222` (localhost bound, exposed via Apache reverse proxy)
- **Service:** Managed via Docker Compose (no systemd service; manual restart via `docker-compose -f docker-compose.prod.yml restart`)
- **Local path:** `/Users/ai_leed/Documents/Projects/Oliver/enterprise-ai-hub-nexus`

**Production Docker services:**
- `nexus-postgres` (5 GB data), `nexus-redis`, `nexus-qdrant` (vector DB), `nexus

## Timeline / Git History
| Date | Change |
|------|--------|
| 2026-04-01 | Fix To-Do tasks filter (MS API rejects complex OR + orderby) |
| 2026-04-01 | Add M365 delegated scopes + offline_access to PKCE login |
| 2026-03-31 | Purge orphaned Qdrant vectors button |
| 2026-03-31 | Batch AI merge (10 pages), doc search, updated user guide |
| 2026-03-31 | Proactive Graph token refresh + needs_reconsent flag |
| 2026-03-31 | SharePoint sync reliability — celery beat, token refresh, scopes |
| 2026-03-31 | AI content structuring before RAG indexing |
| 2026-03-31 | Recursive site crawl via Firecrawl /v1/crawl |

## Sessions
### 2026-04-14 – Project catalogued
**Done:** Added to Obsidian second brain with full details from git history.

---
## Change Log
| Date | Requested | Changed | Files |
|------|-----------|---------|-------|
| 2026-04-01 | Fix MS To-Do filter | Simplify API filter | tasks endpoint |
| 2026-03-31 | Add site crawl | Firecrawl recursive crawl integration | backend |

## Related
- [[Oliver-ai-bot_2.0/Oliver AI Bot 2.0]] (earlier version)
- [[sandbox-notebookllamalm-nextjs/Sandbox NotebookLM]] (same server cluster)
- [[DevOps_Click_UP_sync/DevOps ClickUp Sync]]