---
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/security
- tech/azure-ad
- tech/claude
- tech/docker
- tech/fastapi
- tech/postgresql
- tech/python
- tech/react
- tech/redis
- tech/typescript
- type/project
type: project
---

# OLIVER Sales Ops Platform — Developer Manual

## Architecture Overview
The platform is a full-stack web application with a React frontend and a Python FastAPI backend, orchestrated via Docker Compose for local development and production.

### High-Level Components
1. **Frontend**: React SPA with TypeScript, using `@tanstack/react-query` for data fetching and `@azure/msal-react` for Azure AD authentication.
2. **Backend**: Python FastAPI application handling business logic, AI agent orchestration (Anthropic Claude), state machine management, and API endpoints.
3. **Database**: PostgreSQL 16 for persistent storage of opportunities, stages, artifacts, and users.
4. **Cache/Queue**: Redis 7 for session management, caching, and potential async task queues.
5. **AI Integration**: Anthropic API for running specialized "Claude Agents" at each stage.
6. **Auth**: Azure AD SSO via MSAL. Supports a `DEV_AUTH_BYPASS` mode for local development.

## Tech Stack
- **Frontend**: React 18, TypeScript, React Router, Tailwind CSS (implied by styles), Axios (implied by API client).
- **Backend**: Python 3.11+, FastAPI, SQLAlchemy (async), Pydantic, Anthropic SDK, Mailgun SDK.
- **Infrastructure**: Docker, Docker Compose, PostgreSQL 16, Redis 7.

## Local Setup

### Prerequisites
- Docker & Docker Compose
- Node.js 18+
- Python 3.11+
- An Anthropic API Key
- Azure AD App Registration (for SSO)

### Steps
1. **Clone the Repo**
   ```bash
   git clone <repo_url>
   cd oliver-sales-ops-platform
   ```

2. **Environment Variables**
   Copy `.env.example` to `.env` and configure:
   - `POSTGRES_PASSWORD`: Set a strong password.
   - `ANTHROPIC_API_KEY`: Your Anthropic key.
   - `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`: From your Azure AD app registration.
   - `DEV_AUTH_BYPASS`: Set to `true` for local dev to skip SSO. **Never set in production.**
   - `DATA_DIR`: Directory for reference data (e.g., `./data`).
   - `APP_PUBLIC_URL`: e.g., `http://localhost:3011`.
   - `APP_PATH_PREFIX`: e.g., `/oliver-sales-ops-platform`.

3. **Start Infrastructure**
   ```bash
   docker-compose up -d db redis
   ```

4. **Initialize Database**
   Run database migrations (assuming Alembic or similar):
   ```bash
   docker-compose exec backend alembic upgrade head
   ```

5. **Start Backend**
   ```bash
   docker-compose up backend
   ```

6. **Start Frontend**
   ```bash
   cd frontend
   npm install
   npm run dev
   ```

7. **Access the App**
   Open `http://localhost:3011` (or your configured port) in a browser.

## Environment Variables
| Variable | Required | Description |
|---|---|---|
| `POSTGRES_PASSWORD` | Yes | DB password |
| `ANTHROPIC_API_KEY` | Yes | Anthropic API key |
| `AZURE_TENANT_ID` | Yes | Azure AD Tenant ID |
| `AZURE_CLIENT_ID` | Yes | Azure AD Client ID |
| `DEV_AUTH_BYPASS` | No | Skip SSO in dev (set to `true`) |
| `MAILGUN_API_KEY` | No | Email notifications |
| `MAILGUN_DOMAIN` | No | Mailgun domain |
| `APP_PUBLIC_URL` | No | Public URL for links |
| `APP_PATH_PREFIX` | No | URL prefix for routing |
| `DATA_DIR` | No | Path to reference data |

## Key Services & Entry Points

### Backend (`/backend`)
- **Main Entry**: `app/main.py` (FastAPI app init).
- **Stage Logic**: `/backend/app/stages/` contains agent definitions and state machine logic.
- **API Routes**: `/backend/app/api/` exposes REST endpoints for opportunities, approvals, and artifacts.
- **Auth Middleware**: Handles Azure AD token validation. Falls back to `DEV_AUTH_BYPASS` claims if enabled.

### Frontend (`/frontend`)
- **Main Entry**: `src/main.tsx` (React app bootstrapping).
- **Routing**: `src/App.tsx` defines routes for Dashboard, Opportunities, and Approvals.
- **Auth**: `src/auth/AuthProvider.tsx` handles MSAL login, redirect, and access control.
- **Components**: Stage-specific components (e.g., `Stage9DeliveryModel.tsx`) handle UI for each phase.

### Database Models
- **Opportunity**: Represents a single deal/project.
- **StageArtifact**: Stores AI-generated JSON and metadata (cost, tokens) per stage.
- **Approval**: Tracks approval status for gated stages.

## API Reference (Key Endpoints)
- `POST /api/opportunities`: Create new opportunity.
- `GET /api/opportunities/{id}`: Get opportunity details.
- `POST /api/opportunities/{id}/stages/{n}/complete`: Complete stage `n`.
- `POST /api/opportunities/{id}/delivery-model`: Trigger Stage 9 agent.
- `GET /api/opportunities/{id}/artifacts/{n}`: Get artifacts for stage `n`.
- `POST /api/approvals/{id}/approve`: Approve an approval gate.

## Deployment
1. **Build Docker Images**: `docker-compose build`.
2. **Set Production Env Vars**: Ensure `DEV_AUTH_BYPASS` is **unset** or `false`. Set all secrets securely.
3. **Deploy**: Use `docker-compose up -d` or your orchestrator (K8s, etc.).
4. **Database**: Run migrations in the running container.

## Known Gotchas
1. **Auth Bypass**: Accidentally leaving `DEV_AUTH_BYPASS=true` in production will disable SSO and allow unauthorized access.
2. **Path Prefixes**: Ensure `APP_PATH_PREFIX` in `.env` matches the reverse proxy configuration (e.g., Nginx/Apache) and the `basename` in `BrowserRouter`.
3. **AI Costs**: Every AI call is logged. Monitor token usage via the UI to avoid unexpected Anthropic bills.
4. **Stage Locking**: Stages are strictly sequential. Ensure upstream stages are complete before attempting downstream operations.
5. **Mailgun**: If `MAILGUN_API_KEY` is empty, emails are logged only. Ensure a key is set for production notifications.

## Related
- [[01 Projects/olivas/DEVELOPER_MANUAL]]
- [[01 Projects/cc-dashboard/DEVELOPER_MANUAL]]
- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/oliver-ai-assistant/DEVELOPER_MANUAL.md]]
- [[01 Projects/Oliver-ai-bot_2.0/DEVELOPER_MANUAL.md]]
- [[01 Projects/oliver-sales-ops-platform/USER_MANUAL.md]]