gmal-scope-builder/README.md

# GMAL Scope Builder

A Dockerized web application for scoping new client ratecards and team shapes against the GMAL master asset database. Uses AI (Claude Opus 4.6) to match client briefs to standardized GMAL assets, build ratecards with hours per role, and calculate team FTE headcount.

## Tech Stack

- **Docker** with docker-compose (3 services)
- **PostgreSQL 16** - persistent data store
- **Python / FastAPI** - backend API
- **React + Vite + TypeScript** - frontend
- **Claude API** (Opus 4.6) - AI matching and document parsing

## Quick Start (Local Development)

```bash
# 1. Clone
git clone git@bitbucket.org:zlalani/gmal-scope-builder.git
cd gmal-scope-builder

# 2. Create .env
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# 3. Add the GMAL Excel file
# Place "U-Studio GMAL Asset Job Routes Apr25 ForFranky.xlsx" in the data/ directory

# 4. Build and start
docker compose build
docker compose up -d

# 5. Wait for services to be ready (~30 seconds)
docker compose logs backend --tail 5
# Look for "Application startup complete"

# 6. Ingest GMAL data
curl -X POST http://localhost:8001/api/gmal/ingest

# 7. Open the app
open http://localhost:3010
```

## Deploying to a Server

### 1. Get the code on the server

```bash
git clone git@bitbucket.org:zlalani/gmal-scope-builder.git
cd gmal-scope-builder
```

### 2. Copy data files from your local machine

```bash
# From your local machine:
scp backups/scope_builder_deploy.sql user@server:/path/to/gmal-scope-builder/backups/
scp "data/U-Studio GMAL Asset Job Routes Apr25 ForFranky.xlsx" user@server:/path/to/gmal-scope-builder/data/
```

### 3. Create the .env file

```bash
cp .env.example .env
nano .env
```

```
POSTGRES_PASSWORD=scope_pass_2024
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
```

### 4. Update ports (if needed)

Edit `docker-compose.yml` to change the exposed ports. Defaults:
- **5433** - PostgreSQL
- **8001** - Backend API
- **3010** - Frontend

### 5. Build and start

```bash
docker compose build
docker compose up -d
```

### 6. Import the database

Wait for containers to be healthy, then import the dump (includes all GMAL data + AI descriptions):

```bash
# Wait for DB
docker compose logs db --tail 5

# Import (the -T flag is important for piped input)
docker compose exec -T db psql -U scope_user -d scope_builder < backups/scope_builder_deploy.sql
```

### 7. Verify

```bash
# Check data
docker compose exec db psql -U scope_user -d scope_builder -c "SELECT COUNT(*) FROM gmal_assets;"
# Expected: 390

docker compose exec db psql -U scope_user -d scope_builder -c "SELECT COUNT(*) FROM gmal_assets WHERE ai_enhanced_description IS NOT NULL;"
# Expected: 135+

# Check API
curl http://localhost:8001/api/health
curl http://localhost:8001/api/gmal/stats

# Open frontend
# http://your-server:3010
```

## Creating a Fresh Database Backup

```bash
cd gmal-scope-builder
docker compose exec db pg_dump -U scope_user -d scope_builder > backups/scope_builder_$(date +%Y%m%d).sql
```

## Restoring a Database Backup

```bash
docker compose exec -T db psql -U scope_user -d scope_builder < backups/scope_builder_YYYYMMDD.sql
```

## Features

### Core Workflow
1. **Create Project** - name, client, select model type (Current O+, AI O+, Current Local, AI Local, Asset Factory)
2. **Upload Client Brief** - Word (.docx) or Excel (.xlsx), AI extracts assets with descriptions and volumes
3. **AI Matching** - matches each client asset to the closest GMAL equivalent with confidence scores and caveats
4. **Build Ratecard** - hours per role per asset, multiplied by volume
5. **Team Shape** - FTE headcount per role (hours / 1,800)
6. **AI Efficiency** - model 10/25/50/75/90% efficiency reductions on delivery roles
7. **Export** - Excel (ratecard + asset detail + team shape + efficiency tabs) and PDF (caveats report)

### Additional
- **GMAL Browser** - search/filter all 390 assets with full detail view
- **GMAL Editor** - inline editing of assets, hours per role per model type
- **AI Descriptions** - batch-generate rich brief-friendly descriptions for better matching
- **AI Cost Tracking** - real-time token usage and cost per project
- **Debug Panel** - inspect every AI call (prompt, response, tokens, cost)
- **Help Page** - full user guide with model type explanations

## Project Structure

```
gmal-scope-builder/
  docker-compose.yml
  .env / .env.example
  data/                          # GMAL Excel file (gitignored)
  backups/                       # Database dumps (gitignored)
  backend/
    Dockerfile
    requirements.txt
    start.sh                     # DB init + uvicorn
    app/
      main.py                    # FastAPI app
      config.py                  # Settings from env
      database.py                # SQLAlchemy async engine
      models/                    # SQLAlchemy models
      schemas/                   # Pydantic schemas
      api/                       # Route handlers
      services/                  # Business logic
        excel_parser.py          # GMAL Excel ingestion
        doc_parser.py            # Client document parsing
        ai_matching.py           # Claude matching engine
        ai_descriptions.py       # AI description generator
        ratecard_builder.py      # Ratecard from matches
        team_shape.py            # FTE calculator
        export_excel.py          # Excel export
        export_pdf.py            # PDF caveats export
      utils/
        claude_client.py         # Anthropic SDK wrapper + cost tracking
  frontend/
    Dockerfile
    src/
      pages/                     # Dashboard, ProjectView, GmalBrowser, GmalEditor, Help
      components/
      api/client.ts
      types/index.ts
```

## API Pricing

Claude Opus 4.6: $3/M input tokens, $15/M output tokens

Typical costs per project:
- Document parsing: ~$0.05-0.15
- Matching (per asset): ~$0.02-0.05
- Full project (50 assets): ~$1-3
- AI description generation (one-off): ~$1-2 for all 243 assets