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: v1.0.1 (2026-04-23) shipped; the "Lightning-class" enterprise redesign has since merged to
main(unreleased). SeeCHANGELOG.mdanddocs/operations/ci-cd.md. CI:Deployment: https://squadlogic.vercel.app/
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.
- Core Domain & Utilities: Shared
@squadlogic/corepackage 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, payment status, waitlist, guardians, 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.
- Communication: RSVP tracking, trigger-based notifications (rainouts, schedule changes), and team messages.
- Calendar Sync: Public ICS feeds for parents and coaches.
- Registration & Compliance: Custom form builder, waiver/payment/medical tracking (boolean toggles — no document storage), and a compliance dashboard.
- Reporting: Game score entry, standings calculations, and tie-breaker logic.
- Design system: Cobalt light + dark themes driven by CSS tokens (
data-themeon<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 role preview; nested collapsible navigation with role-scoped views for coaches and parents. - 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, compliance) and team records absorbing the team portal (roster, schedule, staff, messages, RSVP).
- 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, medical forms, 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.
- Role dashboards: Admin KPI home, coach dashboard, and parent dashboard, each scoped to what that role needs.
- 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
The application is structured around the following workflows (see frontend/src/App.jsx; legacy paths redirect):
/— Home: Role-scoped dashboard (admin KPIs, coach view, parent view)./setup— Season Setup: Resumable onboarding/season checklist (/setup/featuresfor feature selection)./import— Data Import: Staged GotSport CSV ingestion (players, coaches, field slots) with rollback./players— Players: Editable roster grid;/players/:playerIdfor individual records./teams— Teams: Generation, analysis, and re-runs;/teams/builderfor drag-and-drop balancing;/team/:teamIdfor team records./coaches— Coaches: Volunteer review, promotion, and team assignment./fields— Field Management: Venues, sub-units, and priorities;/scheduling/blackoutsfor 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, compliance, forms, reports, analytics, audit logs./settings— Settings: Organization configuration, feature toggles, invites, and audit log.
- Node.js (v20 or higher)
- npm (v10 or higher)
- A Supabase Project (for database and auth) — or run in mock mode (below) with no backend at all
-
Clone the repository:
git clone https://github.com/JoelA510/SquadLogic.git cd SquadLogic -
Install dependencies:
npm ci
-
Environment Setup: Copy
.env.exampleto.env.localand populate your Supabase credentials. For a full list of all environment variables (frontend, Edge Functions, CI/CD), see Environment Variables Reference. -
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.
To create a production build:
npm run frontend:buildThe SquadLogic knowledge base is organized into a categorized hierarchy for high discoverability and audit traceability. For the full index, see docs/README.md.
- 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.
- 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.
- 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.
This project is licensed under the ISC License.