---
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/security
- status/active
- tech/authjs
- tech/azure-ad
- tech/claude
- tech/docker
- tech/ffmpeg
- tech/nextjs
- tech/ollama
- tech/pgvector
- tech/postgresql
- tech/prisma
- tech/react
- tech/recharts
- tech/shadcn
- tech/sharp
- tech/tailwind
- tech/tanstack-query
- tech/typescript
- tech/zustand
- type/project
type: project
---

# HP CG Production Tracker - Developer Manual

## Architecture Overview

The application is a full-stack web application built with Next.js 16 (App Router). It follows a client-server architecture with server-side rendering (SSR) and client-side hydration.

- **Frontend:** React 19+ with App Router, Tailwind CSS 4, and shadcn/ui components.
- **State Management:** TanStack Query v5 for server state, Zustand for client state.
- **Data Layer:** Prisma 7 ORM connected to PostgreSQL 17 with pgvector for semantic search capabilities.
- **Authentication:** Auth.js v5 integrated with Microsoft Entra ID (Azure AD) using PKCE flow for SPA.
- **AI Integration:** Dual-provider AI setup using Anthropic (Claude) and Ollama (local/fallback) for chat and embeddings.

## Tech Stack

| Layer | Technology |
|-------|------------|
| Framework | Next.js 16 (App Router, Turbopack) |
| Language | TypeScript 5.9 |
| Styling | Tailwind CSS 4 + shadcn/ui (Radix) |
| Database | PostgreSQL 17 + pgvector + Prisma 7 |
| Auth | Auth.js v5 (Microsoft Entra ID SSO) |
| State | TanStack Query v5 + Zustand |
| Forms | React Hook Form + Zod v4 |
| AI Chat | Claude API + Ollama (dual provider) |
| Embeddings | Ollama (nomic-embed-text) |
| Charts | Recharts |
| Media | Sharp (images), FFmpeg + HLS.js (video) |
| PDF | @react-pdf/renderer |
| Deployment | Docker + Docker Compose |

## Local Setup

### Prerequisites
- Node.js 18+
- Docker & Docker Compose
- PostgreSQL 17 (or use Docker compose)
- Local Ollama instance (optional, for local AI)

### Steps

1. **Clone the Repository**
   ```bash
   git clone <repo-url>
   cd hp-prod-tracker
   ```

2. **Environment Configuration**
   Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```
   Update the following variables:
   - `DATABASE_URL`: Connect to your local DB (default `postgresql://postgres:postgres@localhost:5432/hp_prod_tracker`)
   - `AUTH_SECRET`: Generate with `openssl rand -base64 32`
   - `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_REDIRECT_URI`: From your Azure AD App Registration.
   - `ANTHROPIC_API_KEY`: For primary AI chat.
   - `OLLAMA_HOST`: Set to `http://localhost:11434` if running Ollama locally.

3. **Start Infrastructure**
   ```bash
   docker compose up -d db
   ```
   This starts PostgreSQL with pgvector enabled.

4. **Install Dependencies**
   ```bash
   npm install
   ```

5. **Run Database Migrations**
   ```bash
   npx prisma migrate dev
   ```

6. **Start the Application**
   ```bash
   npm run dev
   ```
   The app will be available at `http://localhost:3000`.

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `DATABASE_URL` | PostgreSQL connection string | Yes |
| `AUTH_SECRET` | Secret for session management | Yes |
| `AZURE_CLIENT_ID` | Azure AD Application Client ID | Yes |
| `AZURE_TENANT_ID` | Azure AD Tenant ID | Yes |
| `AZURE_REDIRECT_URI` | Login page URL registered in Azure | Yes |
| `DEV_BYPASS_AUTH` | Set to `true` to skip SSO in dev | No |
| `ANTHROPIC_API_KEY` | API key for Claude AI | No |
| `OLLAMA_HOST` | URL for local Ollama instance | No |
| `CRON_SECRET` | Secret for cron job verification | No |

## Key Services & Entry Points

### 1. Authentication (`src/app/api/auth/[...nextauth]/route.ts`)
- Implements Auth.js v5.
- Uses Microsoft Entra ID provider.
- In dev mode, if `DEV_BYPASS_AUTH=true`, it auto-logs in as `DEV_USER_ID`.

### 2. Database Schema (`prisma/schema.prisma`)
- Defines models for `Project`, `Deliverable`, `Stage`, `User`, etc.
- Uses `pgvector` for embedding vectors in `Deliverable` for semantic search.

### 3. AI Services (`src/ai/`)
- **Embeddings:** Uses `nomic-embed-text` via Ollama.
- **Chat:** Primary provider is Claude (Anthropic), with Ollama (`gemma4` or `qwen3`) as fallback.

### 4. Pipeline Logic
- Enforced in Prisma relations and backend middleware.
- Critical gates (Stage 3, 5) block updates if not approved.

### 5. UI Components
- **`src/components/command-palette.tsx`**: Global command palette (`Cmd+K`).
- **`src/components/theme-provider.tsx`**: Next-themes integration.
- **`src/components/query-provider.tsx`**: TanStack Query client setup.

## API Reference

### Health Check
- **GET** `/api/health`
  - Returns `200 OK` if the app and DB are healthy.

### Auth
- **POST** `/api/auth/signin` (Handled by Auth.js)
- **POST** `/api/auth/signout` (Handled by Auth.js)

### Projects
- **GET** `/api/projects`
  - Returns list of projects (filtered by auth).
- **POST** `/api/projects`
  - Create a new project.

### Deliverables
- **GET** `/api/projects/[projectId]/deliverables`
  - List deliverables for a project.
- **PATCH** `/api/projects/[projectId]/deliverables/[deliverableId]`
  - Update status or files.

## Deployment

### Docker Compose Deployment
The `docker-compose.yml` defines:
- `db`: PostgreSQL 17 with pgvector.
- `app`: Next.js container.

**Production Steps:**
1. Build the Docker image:
   ```bash
   docker compose build
   ```
2. Run the stack:
   ```bash
   docker compose up -d
   ```
3. Ensure `NODE_ENV=production` and all sensitive env vars are set securely.
4. Configure Azure AD redirect URI to point to the production domain.

## Known Gotchas

1. **Critical Gates:** Developers must ensure the DB triggers or Prisma middleware correctly block status updates if prerequisites are incomplete. Bypassing this logic will corrupt pipeline integrity.
2. **AI Fallback:** If `ANTHROPIC_API_KEY` is not set, the app falls back to Ollama. Ensure Ollama is running and the model `gemma4` or `qwen3` is pulled.
3. **PKCE Flow:** Since this is an SPA, do not use `AZURE_CLIENT_SECRET`. Ensure the Azure App Registration is set up as a "Single Page Application" with PKCE.
4. **Vector Search:** Ensure `pgvector` is enabled in PostgreSQL. The Docker volume `./docker/db-init.sql` handles this, but verify it runs on DB restart.
5. **File Uploads:** Media uploads are stored in `uploads_data` volume. Ensure the Docker user has write permissions to `/data/uploads`.

## Related
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL]]
- [[01 Projects/enterprise-ai-hub-nexus/DEVELOPER_MANUAL]]
- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL.md]]
- [[01 Projects/olivas/DEVELOPER_MANUAL.md]]
- [[01 Projects/Oliver-ai-bot_2.0/DEVELOPER_MANUAL.md]]
- [[01 Projects/hp-prod-tracker/DEVELOPER_MANUAL.md]]