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
-
Clone the repository:
git clone https://github.com/JoelA510/SquadLogic.git
cd SquadLogic
-
Install dependencies:
npm ci
-
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.
-
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
🛡️ Security & Governance
🚀 Roadmap & Operations
📄 License
This project is licensed under the ISC License.
