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

# 🦙 Sandbox NotebookLM Developer Manual

## Architecture Overview
The application is a monorepo split into two main containers:
1. **Frontend**: A Next.js application serving the UI.
2. **Backend**: A Python FastAPI/Streamlit hybrid application handling business logic, AI integration, and database operations.

It uses **PostgreSQL** for persistent storage and **Redis** for caching/sessions. All services are containerized via Docker Compose.

## Tech Stack
- **Frontend**: Next.js (React), TypeScript.
- **Backend**: Python 3, FastAPI, Streamlit (for some components), SQLAlchemy, LlamaIndex.
- **Database**: PostgreSQL 18.
- **Cache/Broker**: Redis 7.
- **AI/ML**: LlamaIndex, OpenTelemetry, various LLM providers (OpenAI, Anthropic, Groq, etc.).
- **Infrastructure**: Docker, Docker Compose.

## Local Setup

### Prerequisites
- Git
- Docker & Docker Compose
- Python 3.10+ (if running backend locally without Docker)

### Steps
1. **Clone Repository**:
   ```bash
   git clone git@bitbucket.org:zlalani/sandbox-notebookllamalm-nextjs.git
   cd sandbox-notebookllamalm-nextjs
   ```

2. **Configure Environment Variables**:
   - Create `backend/.env` with the following keys:
     ```env
     OPENAI_API_KEY=sk-...
     LLAMACLOUD_API_KEY=llx-...
     pgql_user=postgres
     pgql_psw=admin
     pgql_db=postgres_nextjs
     # Optional: AZURE_CLIENT_ID, AZURE_AUTHORITY, etc. for SSO
     ```
   - Create `frontend/.env.local` for local dev:
     ```env
     NEXT_PUBLIC_API_URL=http://localhost:9000
     NEXT_PUBLIC_WS_URL=ws://localhost:9000
     ```

3. **Build and Start Services**:
   ```bash
   docker compose up -d --build
   ```
   This starts:
   - Backend: Port 9000
   - Frontend: Port 4000
   - PostgreSQL: Port 5433
   - Redis: Port 6380

4. **Initialize Database**:
   ```bash
   docker compose exec backend /app/.venv/bin/python -c \
     "import sys; sys.path.insert(0, '/app/src/notebookllama'); from database import init_db; init_db(); print('Done')"
   ```

## Environment Variables

### Backend
- `OPENAI_API_KEY`: Key for OpenAI models.
- `LLAMACLOUD_API_KEY`: Key for LlamaIndex Cloud services.
- `pgql_user`, `pgql_psw`, `pgql_db`: PostgreSQL connection details.
- `ELEVENLABS_API_KEY`: (Optional) For podcast generation.
- `AZURE_CLIENT_ID`, `AZURE_AUTHORITY`, `AZURE_REDIRECT_URI`: (Optional) For Microsoft SSO.

### Frontend
- `NEXT_PUBLIC_API_URL`: Base URL for backend API calls.
- `NEXT_PUBLIC_WS_URL`: WebSocket URL for real-time updates.
- `NEXT_PUBLIC_AZURE_*`: Azure SSO configuration.

## Key Services & Entry Points

### Backend (`backend/src/notebookllama/`)
- `server.py`: Main FastMCP server defining tools (`process_file_tool`, `get_mind_map_tool`, `query_index_tool`).
- `auth.py`: Handles local password authentication (bcrypt) and SSO user creation/update.
- `instrumentation_init.py`: Initializes OpenTelemetry tracing for LlamaIndex observability.
- `instrumentation.py`: Custom SQL engine for exporting OpenTelemetry traces to PostgreSQL.
- `cost_tracker.py`: Lightweight HTTP client for tracking AI usage costs.

### Frontend (`frontend/`)
- Next.js App Router structure.
- Environment variables baked into the Docker build via `frontend/.env.production`.

## API Reference

### Health Check
- **GET** `/api/health`
- Returns 200 if backend is healthy.

### MCP Tools (Internal)
The backend exposes three main tools via FastMCP:
1. `process_file_tool(filename: str)`: Processes uploaded files, returns summary and text.
2. `get_mind_map_tool(summary: str, highlights: list[str])`: Generates mind map data.
3. `query_index_tool(question: str)`: Queries the LlamaIndex vector store.

## Deployment
1. Ensure all required `OPENAI_API_KEY` and `LLAMACLOUD_API_KEY` are set.
2. Build the Docker images:
   ```bash
   docker compose build
   ```
3. Run in production mode:
   ```bash
   docker compose up -d
   ```
4. Configure reverse proxy (e.g., Nginx) to point to ports 9000 (backend) and 4000 (frontend) if not using the provided domain directly.

## Known Gotchas
- **Database Initialization**: The database tables are **not** auto-created. You must run the `init_db` command after the first run.
- **SSO Merging**: If a user logs in via SSO after registering locally, the system merges the accounts (updates provider to SSO, clears password). Ensure your email addresses match exactly.
- **Service Availability**: The backend checks for `LLAMACLOUD_API_KEY` and `OPENAI_API_KEY` at startup. If missing, processing tools will return errors. Check logs for `Missing required environment variables`.
- **Health Checks**: The backend health check waits 30 seconds (`start_period`) before checking. Do not rely on immediate health check success on startup.
- **Port Mapping**: PostgreSQL is mapped to host port 5433, not 5432. Redis to 6380. Adjust local database clients accordingly.

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