build-a-squad/README.md

Build-A-Squad

A client-side staffing calculator for creative agencies. Paste a project brief, select deliverables from a catalog of 30+ creative assets, and get an instant FTE breakdown by discipline and role — powered by AI scope analysis via Google Gemini.

Built with React 19, TypeScript, and Vite. No backend required — everything runs in the browser.

Features

Three-Tab Workflow

1. Scoping — Paste a project brief or upload a screenshot. Gemini analyzes it and suggests matching assets from the catalog. Bulk-add matched assets to your squad.
2. Configurator — Browse and filter the full asset catalog by category, master/adapt type, and Pencil Pro flag. Add assets with volume (quantity) selection.
3. Squad Projection — View calculated FTE breakdown by discipline and role. Supports manual FTE overrides, bespoke staff additions, scenario save/compare, AI operational audit, and CSV/PDF export.

AI Integration

Uses Google Gemini 2.0 Flash for three distinct capabilities:

• Scope Analysis — Analyzes a project brief and matches it to assets in the catalog
• Image OCR — Extracts text from uploaded screenshots of briefs
• Operational Audit — Generates strategic insights from a completed squad projection

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

FTE Calculation

Each asset maps to a set of roles with base hours via staffing routes. Hours are multiplied by asset volume, summed per role, and divided by a configurable billable hours target (default: 1,600 hours/year) to produce FTE projections across 8 disciplines and 40+ roles.

Scenario Management

Save squad snapshots as named scenarios with timestamps. Compare scenarios side-by-side with delta indicators to evaluate different staffing approaches.

Tech Stack

• React 19 — UI framework
• TypeScript 5.8 — Type safety
• Vite 6 — Dev server and bundler
• Tailwind CSS (CDN) — Utility-first styling
• Google Gemini (@google/genai) — AI-powered scope analysis
• Lucide React — Icon library

Design

Neo-brutalist aesthetic: bold 4px borders, 6px offset shadows, yellow (#F5C518) accents, Public Sans font at 400/700/900 weights.

Getting Started

Prerequisites

• Node.js (v18+)
• A Google Gemini API key (required for AI features)

Installation

npm install

Configuration

Create a .env.local file in the project root:

GEMINI_API_KEY=your_api_key_here

Development

npm run dev

Opens at http://localhost:3000.

Production Build

npm run build    # Output to dist/
npm run preview  # Preview the build locally

Project Structure

.
├── App.tsx           # Main application component (UI + logic)
├── types.ts          # TypeScript interfaces
├── mockData.ts       # Asset catalog, staffing routes, role mappings
├── index.html        # Entry point with embedded CSS
├── index.tsx         # React root mount
├── vite.config.ts    # Vite config (port 3000, env injection, path aliases)
├── data/             # Parsed JSON data (assets, staffing routes, role map)
├── scripts/          # Data parsing utilities
└── documents/        # Source asset catalog (CSV/MD/XLSX) and scope samples

Path Aliases

Use @/ to import from the project root:

import { Asset } from '@/types';

Scripts

Command	Description
npm run dev	Start Vite dev server on port 3000
npm run build	Production build to dist/
npm run preview	Preview production build
npm run parse-catalog	Parse source asset catalog into JSON