---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- domain/ai
- status/active
- tech/azure-ad
- tech/gemini
- tech/react
- tech/typescript
- tech/vite
- type/project
type: project
---

# Build-A-Squad Developer Manual

## Architecture Overview

Build-A-Squad is a single-page application (SPA) built with React. It follows a client-side architecture where all state management and calculations occur in the browser.

### Key Components
1.  **Auth Gate:** Manages Microsoft identity integration via MSAL.
2.  **App Container:** Orchestrates state between the three main tabs (Scoping, Configurator, Squad).
3.  **Data Layer:** Static JSON files for assets and routing logic, parsed at build/initialization time.
4.  **AI Service:** Client-side integration with Google Gemini API for scope analysis and auditing.

## Tech Stack

-   **Framework:** React 19 (using Hooks: `useState`, `useMemo`, `useCallback`).
-   **Language:** TypeScript 5.8.
-   **Build Tool:** Vite 6.
-   **Styling:** Tailwind CSS (via CDN).
-   **Auth:** `@azure/msal-react` and `@azure/msal-browser`.
-   **AI:** `@google/genai` (Gemini 3.1 Pro).
-   **Icons:** Lucide React.

## Local Setup

### Prerequisites
-   Node.js (LTS version recommended)
-   npm or yarn

### Installation
1.  Clone the repository.
2.  Install dependencies:
    ```bash
    npm install
    ```
3.  Create a `.env` file in the root directory (see **Environment Variables**).
4.  Start the development server:
    ```bash
    npm run dev
    ```
    The app will run at `http://localhost:3000`.

## Environment Variables

The application relies on Vite's `define` mechanism to inject environment variables at build time. Create a `.env` file with the following keys:

```env
# Google Gemini API Key for AI features
GEMINI_API_KEY=your_gemini_api_key_here

# Microsoft Azure AD B2B/C2B Configuration
AZURE_CLIENT_ID=your_azure_client_id
AZURE_TENANT_ID=your_azure_tenant_id
AZURE_REDIRECT_URI=http://localhost:3000/auth/callback # Or your prod URI
```

*Note: Ensure the Redirect URI in the Azure Portal matches the one in your `.env` file.*

## Key Services & Entry Points

### `index.tsx`
Entry point. Initializes MSAL, checks authentication status, and renders the `App` component wrapped in `MsalProvider`.

### `auth.ts`
Configures the `PublicClientApplication` instance for Azure MSAL. Exports `msalInstance` and `loginScopes`.

### `App.tsx`
The core application logic:
-   **State Management:** Manages `selectedAssets`, `overrides`, `manualStaff`, `scenarios`, and tab navigation.
-   **Tab Logic:**
    -   **Scoping:** Calls Gemini API to analyze `scopingInput` and map to `ASSETS_DATA`.
    -   **Configurator:** Renders filtered lists of `ASSETS_DATA`.
    -   **Squad:** Calculates FTEs using `STAFFING_ROUTES` and `ROLE_DISCIPLINE_MAP`.
-   **Scenario Management:** Saves/loads `Scenario` objects to local state (and supports CSV export/import).

### `mockData.ts`
Loads static data from JSON files:
-   `data/assets.json`: Full catalog of 30+ asset types.
-   `data/staffingRoutes.json`: Map of `uniques` to `{ role: hours }`.
-   `data/roleDisciplineMap.json`: Map of `role` to `discipline`.

*Note on Naming:* Despite the filename `mockData.ts`, this serves as the primary data source for the production catalog. The assets are parsed from `documents/Latest Asset List.md` using `scripts/parse-assets.ts`.

### `scripts/parse-assets.ts`
A utility script to update the catalog data. It parses a pipe-delimited markdown table and outputs the three required JSON files into the `data/` directory.

Run: `npm run parse-catalog`

## API Reference

### AI Integration
The app uses `@google/genai` with `gemini-3.1-pro-preview`.

**Scope Analysis:**
-   **Input:** Project brief text.
-   **Output:** JSON schema-based array of `ScopingResult` objects containing `scopeItem`, `volume`, `catalogId`, and `rationale`.
-   **Usage:** `GoogleGenAI` instance calls `models.generateContent` with structured output schema.

**Operational Audit:**
-   **Input:** Current `selectedAssets`, `overrides`, `manualStaff`.
-   **Output:** Strategic text insights regarding the squad composition.

## Deployment

1.  **Build:**
    ```bash
    npm run build
    ```
    This generates static files in the `dist/` directory.
2.  **Base Path:** In `vite.config.ts`, the base path is set to `/build-a-squad/` for production. Ensure your web server (e.g., IIS, Nginx, Apache) is configured to serve the app from this subdirectory or adjust the `base` config if deploying to the root.
3.  **Azure AD:** Update the `AZURE_REDIRECT_URI` in the `.env.production` file to point to your production deployment URL before building for production.

## Known Gotchas

1.  **State Persistence:** The app does **not** save state to a database. Scenarios are saved only within the current session or via exported CSV. Reloading the page resets all data.
2.  **Asset Catalog Updates:** The catalog is static JSON. You **must** run `npm run parse-catalog` after updating `documents/Latest Asset List.md` to see changes in the app.
3.  **Billable Hours:** The default FTE calculation uses 1,600 hours/year. Change `billableHoursTarget` in the Squad tab if your agency uses a different divisor (e.g., 2,080).
4.  **Tailwind CDN:** The app uses Tailwind via CDN for simplicity in this demo/prototype phase. For production, consider building a full Tailwind CSS pipeline to avoid FOUC (Flash of Unstyled Content) and enable PurgeCSS for smaller bundle sizes.
5.  **MSAL Redirect:** If you encounter auth loops, verify that the `redirectUri` in `auth.ts` (and `.env`) exactly matches the one registered in the Azure Portal App Registration under "Authentication".