SquadLogic

Focus on the Field.

SquadLogic converts raw GotSport registration data into actionable teaming and scheduling frameworks, designed specifically to support youth sports organizations.

Release status: the latest release is v1.2.0 (2026-10-22), the version package.json carries and Sentry reports: the Phase A privacy and access work, the team-delete and timezone fixes, and the team-count recommendation; v1.1.0 (2026-10-20) brought the "Lightning-class" redesign, the heat forecast and the production-readiness remediation. Production deploys every merge to main, so it also runs anything under "Unreleased" in CHANGELOG.md as 1.2.0. See docs/operations/ci-cd.md. CI: Deployment: https://squadlogic.vercel.app/

---

🚀 Overview

SquadLogic is a comprehensive tool for youth sports administrators. It simplifies the complex logistics of organizing leagues by automating team generation, practice scheduling, and game scheduling. Built with a modern tech stack and the cobalt "Lightning-class" design system (light & dark themes), it offers a premium, intuitive user experience.

✨ Features

Core platform (v1.0)

• Core Domain & Utilities: Shared @squadlogic/core package for metrics, evaluation, normalization, and error handling (pure JS, framework-agnostic).
• Automated Team Generation: Snapshot-aware, incremental allocation of players to teams honoring mutual buddy requests, coach assignments, and manual locks across re-runs.
• Practice & Game Scheduling Engines: Conflict-aware round-robin generation and field/time slot allocation.
• Evaluation Pipeline: Automated readiness scoring, fairness metrics, and conflict detection.
• Supabase Persistence: Edge Functions and audited SECURITY DEFINER RPCs for all state changes — no direct table writes.
• Durable CSV Import: Staged GotSport ingestion (players, coaches, field slots) with validation, idempotent re-import, apply/rollback, and expanded field mapping (years played, waitlist, gendered divisions).
• Role-Based Access Control (RBAC): Comprehensive permission enforcement across all UI flows and RLS policies.
• Multi-Tenant Enforcement: Strict organization partitioning ensuring data isolation.
• Facility Management: Full CRUD UI for venues, fields, blackout dates, and availability profiles.
• Notifications: trigger-based notifications (rainouts, schedule changes). Availability marking (RSVP) and team chat were removed on 2026-10-22: families are reached through the league's registration platform.
• Calendar Sync: A team's ICS feed, a link an admin hands to its coach or families.
• Reporting: Game score entry, standings calculations, and tie-breaker logic.

Lightning-class redesign

• Design system: Cobalt light + dark themes driven by CSS tokens (data-theme on <html>, persisted preference), self-hosted Public Sans, and a shared UI primitive library.
• App chrome: Top bar with org/season switchers, global search (/ shortcut), and nested collapsible navigation; admins only (coaches never sign in).
• Players workspace: Excel-grade editable, virtualized data grid (click-to-edit, keyboard navigation, multi-select bulk actions, instant search) smooth at 1,400+ rows.
• Record pages: Tabbed player records (overview, guardians, schedule) and team records absorbing the team portal (roster, schedule, staff).
• Team Builder: Drag-and-drop roster balancing with a serpentine signal balancer (rating or years-played), buddy links, and coach-parent spreading — every move audited.
• Org feature configuration: Per-organization toggles (player rating, years played, buddy requests, coaching interest, waitlist) and a division gender model — gendered (U8B/U8G) or co-ed display with real merge/split transitions.
• Season Setup: Resumable checklist that derives progress from live data — leave and return without losing your place.
• Admin dashboard: The league overview for admins and staff (there is no coach, parent or player view: only league admins sign in; families stay on the league's registration platform).

🛠️ Tech Stack

• Frontend: React 19, Vite 7, react-router-dom v7
• Styling: Vanilla CSS design tokens ("Lightning-class" design system, light & dark) + Tailwind CSS 4
• Backend: Node.js, Supabase (PostgreSQL, Edge Functions, Storage, Auth)
• Testing: Vitest (unit/integration), Playwright-BDD (E2E)
• Analysis: TypeScript (checkJs + allowJs), ESLint (flat config), Prettier

🗺️ Current Routes

The application is structured around the following workflows (see frontend/src/App.jsx; legacy paths redirect):

• / — Home: The admin dashboard (KPIs, setup progress, permit reminders).
• /setup — Season Setup: Resumable onboarding/season checklist (/setup/features for feature selection).
• /import — Data Import: Staged GotSport CSV ingestion (players, coaches, field slots) with rollback.
• /players — Players: Editable roster grid; /players/:playerId for individual records.
• /teams — Teams: Generation, analysis, and re-runs; /teams/builder for drag-and-drop balancing; /team/:teamId for team records.
• /coaches — Coaches: Volunteer review, promotion, and team assignment.
• /fields — Field Management: Venues, sub-units, and priorities; /scheduling/blackouts for blackout dates.
• /schedule/practice & /schedule/game — Scheduling: Practice slot assignment and round-robin game generation.
• /scores & /standings — Results: Score entry and standings.
• /exports — Exports: Output generation (rosters, schedules).
• /admin/* — Administration: Members, reports, analytics, audit logs.
• /settings — Settings: Organization configuration, feature toggles, invites, and audit log.

🏁 Getting Started

Prerequisites

• Node.js 24 (the version .nvmrc pins; package.json engines requires ^24.15.0, and CI and the Vercel build run on it). With nvm: nvm use.
• npm (v10 or higher)
• A Supabase Project (for database and auth) — or run in mock mode (below) with no backend at all

Installation

1. Clone the repository:

   git clone https://github.com/JoelA510/SquadLogic.git
   cd SquadLogic
   

2. Install dependencies:

   npm ci
   

3. Environment Setup: Copy .env.example to .env.local and populate your Supabase credentials. For a full list of all environment variables (frontend, Edge Functions, CI/CD), see Environment Variables Reference.

4. Start the development server:

   npm run frontend:dev
   

   The application will be available at http://localhost:5173.

Mock mode: set VITE_USE_MOCK_SUPABASE=true (or omit Supabase credentials) to run against a fully seeded in-browser mock — no database required. This is how the E2E suite runs.

Building for Production

To create a production build:

npm run frontend:build

📄 Documentation

The SquadLogic knowledge base is organized into a categorized hierarchy for high discoverability and audit traceability. For the full index, see docs/README.md.

🏛️ Architecture & Core

• System Overview: Full tech stack and system diagram.
• Frontend Architecture: Routing, hooks, and component patterns.
• Data Modeling: Database schema and multi-tenant isolation.
• Scheduling Algorithms: Team generation and field allocation logic.

🛡️ Security & Governance

• CSP Policy: Enforced Content-Security-Policy and waiver rationale.
• RLS Policies: Strict multi-tenant data access rules.
• Lessons Learned: Durable engineering knowledge from the build-out.
• Governance Framework: RPC enforcement and Zod validation mandates.

🚀 Roadmap & Operations

• Expansion Roadmap: Current sprint and milestone tracking.
• E2E Testing Master Plan: Playwright-BDD coverage and quality gates.
• Production Cutover: Deployment runbook and environment setup.
• UI/UX Guidelines: "Lightning-class" design standards and accessibility requirements.

📄 License

This project is licensed under the ISC License.