obsidian/01 Projects/olivas/OliVAS.md

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

# 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