---
name: "Build-A-Squad"
client: Oliver Internal
status: active
server: local
tech: [React 19, TypeScript, Vite, Tailwind CSS, Google Gemini, Lucide React]
local_path: /Users/ai_leed/Documents/Projects/Oliver/build-a-squad
deploy: npm run build
url: http://localhost:3000
tags: [oliver, staffing, fte, calculator, gemini]
created: 2026-04-14
port: 3000
---

## Overview

**Build-A-Squad** is a client-side React 19 + TypeScript staffing calculator designed for creative agencies. Users paste a project brief (or upload a screenshot), select deliverables from a 30+ asset catalog, and receive an instant FTE breakdown by discipline and role. The app leverages Google Gemini AI for scope analysis, image OCR, and operational auditing. With no backend required, all logic runs entirely in the browser, making it ideal for rapid prototyping and internal agency workflows.

## Tech Stack

- **Frontend:** React 19, TypeScript 5.8, Vite 6, Tailwind CSS (CDN)
- **Backend:** None (fully client-side)
- **Database:** None (all data in browser; scenarios saved to localStorage)
- **Infrastructure:** Vite dev server (port 3000)
- **AI/ML:** Google Gemini 2.0 Flash (`@google/genai`)
- **Key libraries:** Lucide React (icons), @azure/msal-react (SSO support), @azure/msal-browser

## Architecture

**Build-A-Squad** is a monolithic React application structured around three tabs and a data-driven catalog system:

```
┌─────────────────────────────────────────────────────────────┐
│                        App.tsx                               │
│  (Monolithic component: all state + UI logic + AI calls)    │
└────────────┬────────────────────────────────────────────────┘
             │
    ┌────────┼────────┐
    ▼        ▼        ▼
 Scoping  Configurator  Squad Projection
  Tab      Tab          Tab
    │        │           │
    └────────┼───────────┘
             │
   ┌─────────▼──────────────────┐
   │   mockData.ts              │
   │ (Typed data re-exports)    │
   └─────────┬────────────────┬─┴────────┐
             │                │          │
   ┌─────────▼──┐  ┌──────────▼──┐  ┌───▼──────────────┐
   │ assets.json│  │staffingRoutes│  │roleDisciplineMap│
   │   (30+)    │  │  .json       │  │    (40 roles)   │
   └────────────┘  └──────────────┘  └─────────────────┘
```

### Data Flow

1. **Asset Catalog** (`data/assets.json`) — 30+ creative assets with metadata (name, category, master/adapt type, complexity, Pencil Pro flag).
2. **Staffing Routes** (`data/staffingRoutes.json`) — Maps each asset to roles with base hours required (e.g., "Brand Audit" → Designer 120h, PM 40h, Strategist 80h).
3. **Role → Discipline Mapping** (`data/roleDisciplineMap.json`) — Defines 40+ roles across 8 disciplines (Design, Strategy, Project Management, etc.).
4. **FTE Calculation** — For each selected asset:
   - Base hours per role (from staffing route) × asset volume (quantity selected)
   - Sum hours by role, divide by billable hours target (default 1,600 h/year)
   - Project FTE across disciplines
5. **AI Integration** — Three Gemini calls:
   - **Scope Analysis:** Analyzes brief text → returns matching asset IDs + volumes
   - **Image OCR:** Extracts text from screenshot → passes to scope analysis
   - **Operational Audit:** Analyzes completed squad → returns strategic insights

### Key Components & State

- **App.tsx** — Single component managing:
  - `selectedAssets`: array of assets with user-selected volumes
  - `scenarios`: named snapshots of squads with timestamps
  - `manualOverrides`: FTE adjustments per role
  - `billableHoursTarget`: editable staffing productivity baseline
  - Tab navigation and all UI rendering
- **mockData.ts** — Provides `ASSETS_DATA`, `STAFFING_ROUTES`, `ROLE_DISCIPLINE_MAP` as typed constants, plus computed arrays: `ROLES`, `CATEGORIES`, `DISCIPLINES`.
- **types.ts** — TypeScript interfaces: `Asset`, `SelectedAsset`, `RoleProjection`, `ManualStaff`, `Scenario`, `RoleHours`.

### Three-Tab Workflow

1. **Scoping Tab** — Paste a brief or upload a screenshot. Gemini analyzes and suggests matching assets. Users can bulk-add matches and set volumes.
2. **Configurator Tab** — Browse full asset catalog. Filter by category, master/adapt type, Pencil Pro flag. Manually add assets with quantity selection.
3. **Squad Projection Tab** — View FTE breakdown by discipline/role. Adjust billable hours target, override individual role FTE, add bespoke staff, save/compare scenarios, run operational audit, export CSV/PDF.

### Design System

- **Styling:** Tailwind CSS (CDN-hosted in `index.html`)
- **Aesthetic:** Neo-brutalist — 4px borders, 6px offset shadows, yellow (#F5C518) accents, Public Sans font (400/700/900)
- **Icons:** Lucide React

## Dev Commands

```bash
# Install dependencies
npm install

# Start dev server (port 3000)
npm run dev

# Production build (outputs to dist/)
npm run build

# Preview production build locally
npm run preview

# Re-parse asset catalog from documents/ → data/*.json
npm run parse-catalog
```

## Deployment

- **Server:** Local / Internal (no production server deployed)
- **Deploy:** `npm run build` → outputs to `dist/` (ready for static hosting)
- **URL:** http://localhost:3000 (dev only)
- **Port:** 3000
- **Service:** None (Vite dev server)
- **Local path:** /Users/ai_leed/Documents/Projects/Oliver/build-a-squad

**Notes on deployment:**
- Bitbucket remote exists (`git@bitbucket.org:zlalani/build-a-squad.git`), but no production deploy workflow is documented.
- `deploy.sh` script exists (added in commit 89ab022) — check its contents for deployment instructions.
- Git log shows recent Azure SSO/MSAL integration (v5) and Gemini model updates.

## Environment Variables

Create `.env.local` in the project root:

- **`GEMINI_API_KEY`** — Google Gemini API key (required for all AI features: scope analysis, image OCR, operational audit). Exposed to client (dev/internal use only; not suitable for production).

## API / Endpoints

**No backend API.** All AI interactions are client-side calls to Google Gemini via `@google/genai`:

- **Scope Analysis** — `POST` to Gemini with brief text → JSON array of matched asset IDs + volumes
- **Image OCR** — `POST` to Gemini with base64 image → extracted text (fed to scope analysis)
- **Operational Audit** — `POST` to Gemini with squad FTE breakdown → strategic insights in JSON

All calls use JSON schema-based structured output for reliable parsing.

## Known Issues

- **Model ID mismatch** — README references `gemini-3.1-pro-preview`, but actual model used in `App.tsx` may differ (check source for authoritative value).
- **No test runner or linter configured** — add before production hardening.
- **API key exposed to client** — acceptable for internal/dev use only; not suitable for public deployment.
- **Tailwind CSS via CDN** — not a local PostCSS build; all styling depends on internet connectivity.
- **Single monolithic component** — `App.tsx` contains all logic and UI; refactoring recommended for maintainability as features grow.
- **No error boundaries** — Gemini API failures may cause unhandled promise rejections.
- **Catalog updates require manual re-parse** — running `npm run parse-catalog` is necessary after editing source docs in `documents/`.

## Git

- **Remote:** `git@bitbucket.org:zlalani/build-a-squad.git`
- **Recent activity:** SSO integration (MSAL), Gemini model updates, scoping expansion, role deletion feature
- **Deploy script:** `deploy.sh` added (commit 89ab022) — review for production deployment steps

## 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
- [[gmal-scope-builder/GMAL Scope Builder]]
- [[lusa-back-planner/LUSA Back Planner]]