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

# GMAL Scope Builder Developer Manual

## Architecture Overview

The application is a Dockerized, three-service architecture:
1.  **Frontend**: React + Vite + TypeScript SPA.
2.  **Backend**: Python FastAPI application handling business logic, AI integration, and database interactions.
3.  **Database**: PostgreSQL 16 storing project data, GMAL assets, and user information.

Services communicate via HTTP (Frontend <-> Backend) and network (Backend <-> Database).

## Tech Stack

-   **Containerization**: Docker & Docker Compose
-   **Database**: PostgreSQL 16 (Alpine image)
-   **Backend**: Python, FastAPI, `asyncpg` (async driver), `psycopg2` (sync driver)
-   **Frontend**: React 18+, Vite, TypeScript, `react-router-dom`, `@azure/msal-react` (Authentication)
-   **AI**: Anthropic Claude API (Opus 4.6)
-   **Auth**: Microsoft Entra ID (Azure AD) via MSAL

## Local Setup

### Prerequisites
-   Docker & Docker Compose installed.
-   Git.
-   An Active Anthropic API Key.

### Steps

1.  **Clone & Setup Env**:
    ```bash
    git clone git@bitbucket.org:zlalani/gmal-scope-builder.git
    cd gmal-scope-builder
    cp .env.example .env
    nano .env
    ```
    -   Set `ANTHROPIC_API_KEY`.
    -   Set `POSTGRES_PASSWORD`.
    -   For local dev, set `DEV_AUTH_BYPASS=true` and `VITE_DEV_AUTH_BYPASS=true` to skip Azure login.

2.  **Add Data**:
    Place the master GMAL Excel file (e.g., `U-Studio GMAL Asset Job Routes Apr25 ForFranky.xlsx`) in the `data/` directory.

3.  **Build & Run**:
    ```bash
    docker compose build
    docker compose up -d
    ```

4.  **Wait for Services**:
    Wait for PostgreSQL to be healthy and Backend to startup.
    ```bash
    docker compose logs backend --tail 5
    ```

5.  **Ingest GMAL Data**:
    ```bash
    curl -X POST http://localhost:8001/api/gmal/ingest
    ```

6.  **Access App**:
    Open `http://localhost:3010`.

## Environment Variables

### `.env` (Root)
-   `POSTGRES_PASSWORD`: Password for the `scope_user` DB user.
-   `ANTHROPIC_API_KEY`: Key for Claude API access.
-   `AZURE_TENANT_ID` & `AZURE_CLIENT_ID`: For MSAL authentication.
-   `DEV_AUTH_BYPASS`: Set to `true` to disable SSO in local dev.
-   `VITE_DEV_AUTH_BYPASS`: Frontend flag to bypass auth UI.
-   `DATA_DIR`: Absolute path to directory containing the GMAL Excel file.

### `docker-compose.yml` (Backend Service)
-   `DATABASE_URL`: Async SQLAlchemy connection string.
-   `DATABASE_URL_SYNC`: Sync SQLAlchemy connection string.
-   Environment variables are passed through from the root `.env`.

## Key Services & Entry Points

### Backend
-   **Entry Point**: Implicit in `./backend` Docker build context (likely `main.py` or `app.py` not shown, but standard FastAPI structure).
-   **GMAL Ingestion**: Endpoint `POST /api/gmal/ingest`. Reads Excel from `DATA_DIR`, parses assets/roles/hours, and populates the DB.
-   **AI Integration**: Uses `ANTHROPIC_API_KEY`. Exposes `/ai/usage` and `/ai/debug` endpoints for frontend tracking.
-   **Projects**: CRUD endpoints at `/projects`.

### Frontend
-   **Entry Point**: `frontend/src/main.tsx` -> `App.tsx`.
-   **Auth**: `frontend/src/auth/AuthProvider.tsx`.
    -   Uses `@azure/msal-react`.
    -   Checks `import.meta.env.VITE_DEV_AUTH_BYPASS` to render raw children if true.
-   **Routing** (`frontend/src/App.tsx`):
    -   `/`: Dashboard (List Projects).
    -   `/new`: NewProject Form.
    -   `/projects/:id`: ProjectView.
    -   `/gmal`: GMAL Browser.
    -   `/gmal-editor`: GMAL Editor (Admin only).
    -   `/users`: UserManagement (Admin only).
    -   `/help`: Help Page.
-   **Key Components**:
    -   `Dashboard.tsx`: Displays stats and project list.
    -   `NewProject.tsx`: Form for creating scopes.
    -   `AiCostTracker.tsx`: Polls `/ai/usage` every 5s.
    -   `DebugPanel.tsx`: Polls `/ai/debug` every 3s for LLM debug info.

## API Reference (Key Endpoints)

| Method | Path | Description | Auth |
| :--- | :--- | :--- | :--- |
| POST | `/api/projects` | Create a new project scope | Auth |
| GET | `/api/projects` | List all projects | Auth |
| POST | `/api/gmal/ingest` | Re-ingest GMAL Excel file | Admin |
| GET | `/api/gmal/stats` | Get GMAL asset/role counts | Auth |
| GET | `/api/ai/usage` | Get cumulative AI cost/token usage | Internal/Dev |
| GET | `/api/ai/debug` | Get recent LLM debug logs | Internal/Dev |

## Deployment

### On a Remote Server

1.  **Copy Code & Data**:
    ```bash
    git clone git@bitbucket.org:zlalani/gmal-scope-builder.git
    cd gmal-scope-builder
    # Copy Excel file and DB backup if restoring
    scp "data/*.xlsx" user@server:/path/to/gmal-scope-builder/data/
    ```

2.  **Configure `.env`**:
    ```bash
    cp .env.example .env
    nano .env
    ```
    Ensure production values for passwords and keys. **Never** set `DEV_AUTH_BYPASS=true` in production.

3.  **Adjust Ports**:
    Edit `docker-compose.yml` ports if `127.0.0.1:8002:8000`, `5433`, and `3010` conflict with existing services.

4.  **Start**:
    ```bash
    docker compose build
    docker compose up -d
    ```

5.  **Initial Ingest**:
    ```bash
    curl -X POST http://localhost:8001/api/gmal/ingest # Or your mapped port
    ```

## Known Gotchas

1.  **Double-Counting Efficiency**: When using "AI efficiency" model types in the frontend, do not manually apply additional AI efficiency adjustments. The model type already accounts for this.
2.  **Data Directory Path**: The backend mounts `${DATA_DIR:-./data}`. Ensure this directory exists and is writable by the container user, and contains the valid Excel file. Relative paths in `.env` are resolved relative to the repo root.
3.  **Auth Bypass**: `DEV_AUTH_BYPASS` and `VITE_DEV_AUTH_BYPASS` must remain empty/false in production to ensure security.
4.  **AI Cost**: The AI costs can accumulate quickly during development/debugging due to frequent calls. Monitor the `AiCostTracker` widget.
5.  **Database Restore**: If restoring from `scope_builder_deploy.sql`, ensure the DB user and database name (`scope_builder`, `scope_user`) match the environment variables.
6.  **Excel Format**: The GMAL ingestion logic depends on the specific structure of the "U-Studio GMAL Asset Job Routes..." Excel file. Changes to this file structure will break ingestion unless the backend parser is updated.

## Related
- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/olivas/DEVELOPER_MANUAL]]
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL]]
- [[01 Projects/Oliver-ai-bot_2.0/DEVELOPER_MANUAL.md]]
- [[01 Projects/ac-tool/DEVELOPER_MANINAL.md]]
- [[01 Projects/gmal-scope-builder/USER_MANUAL.md]]