Oliver/build-a-squad
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
build-a-squad/CLAUDE.md
Manish Tanwar e277e612e4 add msal sso
2026-03-13 06:40:01 +05:30

3.6 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run Commands

npm install          # Install dependencies
npm run dev          # Start Vite dev server on port 3000
npm run build        # Production build (outputs to dist/)
npm run preview      # Preview production build
npm run parse-catalog  # Re-parse asset catalog from documents/ → data/*.json

Requires GEMINI_API_KEY set in .env.local for AI features (scope analysis, image OCR, operational audit).

No test runner or linter is configured.

Architecture

Build-A-Squad is a client-side React 19 + TypeScript staffing calculator for creative agencies. It uses Google Gemini for AI-powered scope analysis and team projection. No backend — everything runs in the browser.

Core Files

  • App.tsx — Monolithic component containing the entire application UI and logic. All state management uses React hooks (useState, useMemo). This is the primary file you'll edit for feature work.
  • types.ts — TypeScript interfaces: Asset, SelectedAsset, RoleProjection, ManualStaff, Scenario, RoleHours.
  • index.tsx — React entry point, mounts <App /> into #root.
  • mockData.ts — Re-exports data from data/*.json as typed constants: ASSETS_DATA, STAFFING_ROUTES, ROLE_DISCIPLINE_MAP, plus derived ROLES, CATEGORIES, DISCIPLINES arrays.
  • data/ — JSON source of truth: assets.json (asset catalog), staffingRoutes.json (role-hour mappings per asset), roleDisciplineMap.json (40+ roles → 8 disciplines). Generated by scripts/parse-assets.ts from documents/.
  • index.html — Entry point with embedded neo-brutalist CSS (4px borders, 6px shadows, yellow focus states) and an import map for CDN-hosted ESM modules (lucide-react, react, react-dom, @google/genai).
  • vite.config.ts — Dev server on port 3000, injects GEMINI_API_KEY env var, path alias @/* → project root.

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 the squad.
  2. Configurator — Browse/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/role. Supports manual FTE overrides, bespoke staff additions, scenario save/compare, AI operational audit, and CSV/PDF export.

Key Patterns

  • FTE Calculation: STAFFING_ROUTES maps each asset to roles with base hours → multiplied by asset volume → summed per role → divided by billable hours target (default 1600) to get FTE.
  • AI Integration: Uses @google/genai with Gemini 2.0 Flash. Three distinct AI calls: scope analysis (brief → asset matches), image OCR (screenshot → text), operational audit (squad → strategic insights). All use JSON schema-based structured output.
  • Scenario Management: Users save squad snapshots as Scenario objects with timestamps. Scenarios can be compared side-by-side with delta indicators.
  • Styling: Neo-brutalist aesthetic via Tailwind CSS (CDN) + custom CSS in index.html. Bold borders, offset shadows, yellow (#F5C518) accents. "Public Sans" font at 400/700/900 weights.
  • Path aliases: Use @/ to import from the project root (e.g., @/types).

Reference Data

The documents/ directory contains the source asset catalog in CSV/MD/XLSX formats and example scope scenarios (XLSX). To update the catalog, edit those source files and run npm run parse-catalog to regenerate data/*.json.