---
name: "OliVAS — Visual Attention Software"
client: OLIVER
status: active
server: optical-dev
tech: [React 19, FastAPI, Python 3.12, PostgreSQL 16, Docker, Google Cloud Run, PyTorch, Azure AD]
local_path: /Users/ai_leed/Documents/Projects/Oliver/olivas
deploy: bash deploy.sh
url: https://optical-dev.oliver.solutions/olivas
tags: [oliver, visual-attention, ai, heatmap, saliency, design-analysis]
created: 2026-04-14
port: 1577
db: PostgreSQL 16
---

## Overview

**OliVAS** (OLIVER Visual Attention Suite) is an open-source web application that predicts where humans look during the first 3–5 seconds of viewing an image using DeepGaze ML models. It generates saliency heatmaps, gaze sequence predictions, hotspot analysis, and a Design Effectiveness Score (0–100) to provide actionable design insights without physical eye-tracking hardware. Optional integration with Claude Sonnet 4.6 adds AI-powered design critique. The application serves OLIVER staff through a React SPA backed by a FastAPI server, with optional offloading of ML inference to Google Cloud Run.

## Tech Stack

- **Frontend:** React 19, TypeScript, Vite, Azure AD MSAL (Microsoft SSO)
- **Backend:** FastAPI, Python 3.12, Uvicorn, Alembic (migrations)
- **Database:** PostgreSQL 16 (Docker container on port 5453)
- **Infrastructure:** Docker Compose, Apache 2 (reverse proxy), Google Cloud Run (optional offload)
- **AI/ML:** DeepGaze IIE + III (saliency), PyTorch, Anthropic Claude Sonnet 4.6 (optional)
- **Key libraries:** Pillow (image processing), matplotlib (heatmap overlay), ReportLab (PDF generation), sqlalchemy (ORM)

## Architecture

OliVAS follows a **layered architecture** with optional cloud offloading:

```
┌─────────────────────────────────────────────────────────────────┐
│ Browser (React 19 SPA)                                          │
│ - Azure AD MSAL login → JWT token                               │
│ - Upload images, view results, download PDF reports             │
└───────────────────────────────┬─────────────────────────────────┘
                                │ REST API
                    ┌───────────v───────────┐
                    │   Apache 2 (LB)       │
                    │ - TLS termination     │
                    │ - /olivas → SPA       │
                    │ - /api/ → FastAPI     │
                    └───────────┬───────────┘
         ┌──────────────────────┴──────────────────────┐
         │                                              │
    ┌────v────────────┐                    ┌──────────v────────┐
    │ FastAPI Backend │                    │ PostgreSQL 16     │
    │ - Auth validation                   │ - Projects        │
    │ - Analysis pipeline                 │ - Analyses        │
    │ - Orchestration                     │ - AOIs            │
    │ - Report generation                 │ - Comparisons     │
    └────┬────────────┘                    └───────────────────┘
         │
         ├─► Local DeepGaze (in-process) OR
         │   ┌────────────────────────────────────────┐
         │   │ Google Cloud Run (optional offload)    │
         │   ├─ Saliency service (GPU-free inference) │
         │   └─ Processing service (heatmap/gaze gen) │
         │
         └─► File Storage
             ├─ /app/data/uploads/{id}/
             │  ├─ original.png
             │  ├─ thumbnail.png
             │  ├─ heatmap_overlay.png
             │  ├─ heatmap_standalone.png
             │  ├─ gaze_sequence.png
             │  └─ report.pdf
             │
             └─► Optional Claude Sonnet 4.6
                 (design insights via Anthropic API)
```

**Analysis Pipeline Flow:**
1. User uploads image → validated, stored, Analysis record created (status=pending)
2. **Saliency inference** → DeepGaze model predicts attention map (local or Cloud Run)
3. **Post-processing** → heatmap overlay, gaze sequence image, hotspot detection
4. **Scoring** → Design Effectiveness Score computed from saliency metrics
5. **Storage** → all artefacts saved to filesystem under `data/uploads/{id}/`
6. **AI insights** (optional) → Claude critique generated
7. **PDF report** → ReportLab compiles visuals, metrics, and insights

## Dev Commands

```bash
# Prerequisites: Python 3.12+, Node.js 18+, Docker, Docker Compose v2

# Clone and initial setup
git clone git@bitbucket.org:zlalani/olivas.git
cd olivas
cp .env.example .env
# Edit .env: set ANTHROPIC_API_KEY if needed; AZURE_AUTH_ENABLED=false for dev

# Start database
make db-up                          # PostgreSQL 16 on port 5453

# Backend setup and run
make setup-backend                  # Create .venv, install deps (~200 MB model weights)
make db-migrate                     # Run Alembic migrations
make dev-backend                    # Start FastAPI on http://localhost:8000 (with --reload)

# Frontend setup and run
make setup-frontend                 # npm install
make dev-frontend                   # Vite dev server on http://localhost:1577

# Full Docker Compose (dev with hot reload)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

# Full Docker Compose (prod-like, no hot reload)
docker compose up --build

# Cleanup
docker compose down                 # Stop all services
docker compose down -v              # Stop and remove volumes (destructive)

# API documentation
# Open http://localhost:8000/docs (Swagger UI)
```

## Deployment

- **Server:** optical-dev.oliver.solutions
- **Deploy:** SSH to production server, run `cd /opt/olivas && bash deploy.sh`
- **URL:** https://optical-dev.oliver.solutions/olivas
- **Port:** 1577 (frontend via Apache), 8000 (backend internal), 5453 (PostgreSQL)
- **Service:** None (Docker Compose managed, not systemd)
- **Local path:** /Users/ai_leed/Documents/Projects/Oliver/olivas

**Deploy script details:**
- Pulls latest from `main` branch (`git pull --ff-only`)
- Builds backend Docker image, starts PostgreSQL, runs migrations
- Builds frontend with Vite, deploys dist to `/var/www/html/olivas/`
- Health check: `curl http://localhost:8000/api/health`
- Idempotent and safe to re-run

**Production paths:**
- Repo: `/opt/olivas`
- Frontend dist: `/var/www/html/olivas/`
- Apache config: `/opt/olivas/olivas-apache.conf`
- Logs: `/var/log/apache2/olivas-{error,access}.log`

## Environment Variables

`AZURE_AUTH_ENABLED` — Enable Azure AD SSO (default: true; set false for local dev without Microsoft account)

`ANTHROPIC_API_KEY` — Anthropic API key for Claude Sonnet 4.6 design insights (optional; if empty, AI insights disabled)

`DATABASE_URL` — PostgreSQL connection string (default: `postgresql://olivas:olivas@postgres:5432/olivas`)

`CLOUD_RUN_SALIENCY_URL` — (Optional) URL of Cloud Run saliency inference service; if set, uses remote inference instead of local

`CLOUD_RUN_PROCESSING_URL` — (Optional) URL of Cloud Run heatmap/gaze processing service; if set, uses remote processing

`AZURE_AD_CLIENT_ID` — Microsoft Entra app registration ID (required if `AZURE_AUTH_ENABLED=true`)

`AZURE_AD_TENANT_ID` — Microsoft Entra tenant ID (required if `AZURE_AUTH_ENABLED=true`)

`AZURE_AD_CLIENT_SECRET` — Microsoft Entra client secret (required if `AZURE_AUTH_ENABLED=true`)

`VITE_API_BASE_URL` — Frontend API base URL (default: `http://localhost:8000` in dev; `/api` in prod via Apache proxy)

## API / Endpoints

**Base URL:** `http://localhost:8000/api` (dev) or `https://optical-dev.oliver.solutions/api` (prod)

**Key endpoints:**
- `POST /projects` — Create project
- `POST /projects/{id}/analyses` — Upload image and trigger analysis
- `GET /projects/{id}/analyses/{analysis_id}` — Get analysis results (saliency, hotspots, gaze sequence)
- `GET /projects/{id}/analyses/{analysis_id}/report` — Download PDF report
- `GET /health` — Health check

See `docs/project/api_spec.md` for full endpoint documentation.

## Known Issues

- **Model loading latency:** First backend startup takes 30–60 seconds (DeepGaze weights load into memory)
- **Upload size limit:** 50 MB per image (set in Apache `LimitRequestBody` and FastAPI config)
- **Cloud Run offloading:** Optional; if not configured, all ML inference runs locally (requires GPU or sufficient CPU)
- **Azure AD required in production:** Local dev should disable `AZURE_AUTH_ENABLED`

## Git

- **Remote:** git@bitbucket.org:zlalani/olivas.git
- **Branch:** main
- **Recent activity:** Authentication (Azure AD SSO), Cloud Run integration, Design Effectiveness Score (replaced entropy), Apache rewrite fixes for `/olivas/` subpath deployment

## Sessions
### 2026-04-14 – Project catalogued
**Done:** Added to Obsidian second brain.

---
## Change Log
| Date | Requested | Changed | Files |
|------|-----------|---------|-------|
| 2026-04-14 | Initial setup | Note created | — |

## Related
- [[cinema-studio-pro/Cinema Studio Pro]]
- [[semblance/Semblance]]