---
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/typescript
- type/sop
type: sop
---

# OliVAS Developer Manual

## Architecture Overview
OliVAS is a full-stack web application with a clear separation between frontend and backend services, managed via Docker Compose.

- **Frontend**: React 18 SPA with TypeScript, Vite, Tailwind CSS, Zustand (state), and React Router.
- **Backend**: FastAPI (Python) with async SQLAlchemy and Pydantic v2. Handles API logic, file processing, and ML model inference.
- **Database**: PostgreSQL 16 (via Docker).
- **Auth**: Azure AD SSO via MSAL.
- **ML**: Local GPU/CPU inference or offloaded to Google Cloud Run.

## Tech Stack
| Layer | Technology |
|-------|------------|
| **Frontend** | React 18, TypeScript, Vite, Tailwind CSS, Zustand, React Router |
| **Backend** | FastAPI, Python 3.12, SQLAlchemy (async), Pydantic v2 |
| **Database** | PostgreSQL 16 |
| **Auth** | Azure AD (MSAL) |
| **ML** | DeepGaze Models, Optional: Anthropic API |

## Local Setup

### Prerequisites
- Docker and Docker Compose
- Python 3.12+ (for local backend dev if not using container)

### Step-by-Step
1. **Clone the Repository**
   ```bash
   git clone <repo-url>
   cd olivas
   ```

2. **Configure Environment**
   Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

3. **Start Services**
   ```bash
   docker-compose up --build
   ```
   This starts:
   - `postgres` on port `5453`
   - `backend` on port `8000`
   - `frontend` on port `1577`

4. **Access the App**
   - Frontend: `http://localhost:1577/olivas`
   - Backend API: `http://localhost:8000/docs`

## Environment Variables

### General
- `DATABASE_URL`: PostgreSQL connection string (e.g., `postgresql+asyncpg://olivas:olivas@localhost:5453/olivas`)
- `UPLOAD_DIR`: Local path for storing uploaded images (e.g., `./data/uploads`)
- `DEVICE`: ML device (`auto`, `cpu`, `cuda`)
- `CORS_ORIGINS`: Allowed frontend origins (e.g., `http://localhost:1577`)
- `BACKEND_HOST/PORT`: Server binding settings

### Authentication (Azure AD)
- `AZURE_AUTH_ENABLED`: `true`/`false`
- `AZURE_TENANT_ID`: Your Azure AD Tenant ID
- `AZURE_CLIENT_ID`: Your Azure AD Application Client ID
- `VITE_AZURE_*`: Frontend Azure AD config (Tenant, Client, Redirect URI)

### Optional Services
- `ANTHROPIC_API_KEY`: Enable AI Design Analysis via Claude Sonnet 4.6
- `CLOUD_RUN_*`: Enable Google Cloud Run offloading for ML models

## Key Services & Entry Points

### Frontend (`frontend/src/`)
- **`App.tsx`**: Route definitions. All routes are protected by `RequireAuth`.
- **`auth/RequireAuth.tsx`**: Checks MSAL authentication status. Redirects to Login if unauthenticated.
- **`auth/msalConfig.ts`**: MSAL instance configuration.
- **`components/AuthImage.tsx`**: Helper to fetch images via authenticated API requests and convert to Blob URLs.

### Backend (`backend/`)
- **Main Entry**: FastAPI app initialization (see `main.py` or `app.py` in backend dir).
- **API Client**: Frontend uses a configured axios/fetch client with baseURL `/api`.
- **ML Inference**: 
  - Local: Uses DeepGaze models based on `DEVICE` env var.
  - Cloud: Sends requests to `CLOUD_RUN_SALIENCY_URL` if configured.

## API Reference

### Authentication
- **Login**: Azure AD Login Redirect. Handled by MSAL.
- **Protected Endpoints**: All API endpoints require a valid Azure AD bearer token.

### Endpoints (Examples)
- `GET /api/projects`: List all projects.
- `POST /api/projects`: Create a project.
- `POST /api/analyses`: Trigger analysis on an uploaded image.
- `GET /api/analyses/{id}`: Get analysis details (heatmap URLs, metrics, insights).
- `GET /api/analyses/{id}/image`: Retrieve original image (authenticated blob).

## Deployment

### Production Considerations
1. **HTTPS**: Ensure reverse proxy (Nginx/Traefik) handles SSL termination.
2. **CORS**: Update `CORS_ORIGINS` to include production domain.
3. **Secrets**: Do not commit `.env` files. Use CI/CD secrets or Vault.
4. **Storage**: Map `UPLOAD_DIR` to persistent cloud storage (e.g., S3) in production.
5. **ML Acceleration**: Set `DEVICE=cuda` and ensure GPU drivers are available on the host.

### Google Cloud Run Offload
- Set `CLOUD_RUN_SALIENCY_URL` and `CLOUD_RUN_PROCESSING_URL` to point to deployed Cloud Run services.
- Set `GOOGLE_CLOUD_PROJECT`.

## Known Gotchas
1. **MSAL Redirect Issues**: Ensure `VITE_AZURE_REDIRECT_URI` matches the Azure AD portal configuration exactly. Note the `/olivas` suffix for the frontend basename.
2. **Image Loading**: Images stored on the server must be fetched via `/api/analyses/{id}/image` to include auth tokens. Do not use direct filesystem paths in production.
3. **Database Connection**: The backend uses asyncpg. Ensure `DATABASE_URL` uses the `postgresql+asyncpg://` dialect.
4. **CORS**: During development, ensure `CORS_ORIGINS` includes `http://localhost:1577`. In production, specify your actual domain.
5. **AI Insights Disabled**: If `ANTHROPIC_API_KEY` is empty, the AI Insights tab will show a message indicating AI analysis is unavailable.

## Related
- [[01 Projects/oliver-sales-ops-platform/DEVELOPER_MANUAL]]
- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/gmal-scope-builder/DEVELOPER_MANUAL]]
- [[01 Projects/enterprise-ai-hub-nexus/DEVELOPER_MANUAL.md]]
- [[01 Projects/oliver-ai-assistant/DEVELOPER_MANUAL.md]]
- [[01 Projects/olivas/DEVELOPER_MANUAL.md]]