Growfit FA

A grassroots football platform for player development, team management, and talent visibility, built for Growfit Sports Academy (Greater Durban, an NPC) and designed so other South African academies can run on it too. Coaches, players, parents and admins each get a home screen made for the job they do that day.

---

What it does

Role	Core capability
Coach	Squads, fixtures, training and attendance; the tactics board; playing-time planner; term reviews; a squad-aware AI assistant
Player	A Today home and a Passport (position and role, attributes, ratings), plays and homework from the coach, skill challenges, development milestones
Parent	A Today home for their own child (next match or training, forms to sign, the coach's weekly note), a weekly family digest, digital document signing
Admin	Today home with registration health, teams to chase and welfare count; academy-wide players, teams, drills, term dates, analytics, SAFA document compliance

Every screen shows the academy's own name and crest. Pages with several areas use URL tabs (?tab=), so a tab can be bookmarked or shared (lib/tabs.ts, QueryTabs).

Safeguarding rules the code enforces

• A parent sees only their own child. A player sees only their own results, never a teammate comparison.
• Nothing AI-written reaches a child or parent until a coach has approved it.
• Video analysis of a child needs recorded consent (ai_analysis_consent).
• Photos are served only with photo consent; personal data is scrubbed before it reaches Sentry.

Tactics

A pitch-diagram animation studio, built to match dedicated tools like The Tactics App and Final Third:

• A board dock (Players, Draw, Move, Coach AI), full-pitch formations with attack and defend shapes for both teams (including 4-3-2-1), and half-pitch for U12 and below
• Tell the board: type or dictate an instruction ("overlap", "underlap", "press", "shift across") and the board turns it into movement, previews it, then applies it. Gemini returns actions, not coordinates
• With and without ball shapes, a timeline scrubber, phases, play folders, and per-frame duration and easing
• Pitch sizes, training grids and an equipment palette for drawing a Wednesday drill as well as a Sunday shape
• Player spotlight and per-player notes, filtered so a player or parent only sees notes about them
• Share: WhatsApp-ready MP4 (720x1280, WebCodecs with a MediaRecorder fallback), a PDF handout, PNG, and plays shared to the squad with a voice note. Positions and first names only
• Match Film: telestration over a phone-clip frame, photo or YouTube/Vimeo embed
• Positions with roles, and age-relative attribute presets (hidden until Buhle approves the wording: PRESETS_APPROVED in lib/attribute-presets.ts)

Training and development

• Attendance (P/A/L/E) that survives a bad connection, with the 75% threshold surfacing a welfare check-in
• Playing-time planner, tactics homework, skill challenges, a drill library (academy-wide, with diagrams), session effort and session memory
• Five milestone categories per season, term plans, and term reviews (band descriptions are coach-drafted and gated by BAND_DESCRIPTIONS_APPROVED in lib/term-review.ts)
• Player self-assessments and coach notes (only approved notes reach families)

AI

Gemini only, grounded in FIFA LTPD, the 4-Corner Model, SAFA NDP and CAF youth principles. It covers the session planner, player insights, development plans, match and parent reports, the academy health report, tactical explainers, opponent analysis, board instructions, drill diagrams, weekly family digest and a conversational coach assistant that suggests an XI and writes match plans.

It reads the academy's own data (ratings, form, attendance against the 75% policy, results) so advice names real players, and it is constrained not to invent players or statistics. Results are stored (ai_artefacts), cached, rate limited, and retried with an optional fallback model (GEMINI_MODEL_FALLBACK). AI use is tracked per month on the admin analytics page.

---

Tech stack

Layer	Technology
Web frontend	Next.js 16 (App Router, async searchParams), React 19, Tailwind CSS v4
Database	Supabase (PostgreSQL) with Row Level Security
Auth	Supabase Auth, email + password
AI	Google Gemini via @google/genai
Documents and media	pdf-lib (handouts, cards), mediabunny (MP4 export)
Validation	Zod v4
Errors	Sentry (@sentry/nextjs, EU region)
Tests	Jest (unit), Playwright (smoke)
Deployment	Vercel (web, main branch only)

---

Repository structure

growfit/
├── web/                        # Next.js web application
│   ├── src/
│   │   ├── app/
│   │   │   ├── (protected)/dashboard/
│   │   │   │   ├── admin/      # Today, players, teams, drills, development, analytics, academy
│   │   │   │   ├── coach/      # Squad, fixtures, training, tactics, assistant, welfare, settings
│   │   │   │   ├── player/     # Today + Passport tabs, development, homework, challenges, tactics
│   │   │   │   └── parent/     # Today, child detail, fixtures, announcements, settings
│   │   │   ├── actions/        # Server Actions, one file per domain
│   │   │   ├── auth/           # Login, register, password reset, role picker
│   │   │   └── passport/       # Public player passport (no auth)
│   │   ├── components/         # Shared UI (ui/ holds the design primitives)
│   │   └── lib/                # Pure helpers with tests in lib/__tests__
│   │       ├── *-data.ts       # Loaders that read through the user's own session, so RLS applies
│   │       ├── board-*.ts      # Tactics board model, instructions, timeline, video, render
│   │       ├── ai-*.ts         # Gemini guard, cache, retry, safeguards, artefacts
│   │       ├── tabs.ts         # URL tabs
│   │       └── supabase/       # Server and browser clients
├── supabase/migrations/        # 001 to 066 (046 and 047 were never used)
├── site/                       # Public marketing site
└── docs/                       # See Further reading

---

Local development

Prerequisites

• Node.js 20+
• A Supabase project (free tier is enough)
• A Gemini API key for the AI features

1. Clone and install

git clone https://github.com/madlalakhaya25/growfit.git
cd growfit/web
npm install

2. Environment variables

Copy web/.env.example to web/.env.local.

Variable	Needed	Purpose
NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY	Yes	Supabase project
NEXT_PUBLIC_SITE_URL	Yes	Absolute links for shared passports and plays
GEMINI_API_KEY	For AI	Every AI feature
GEMINI_MODEL, GEMINI_MODEL_DOC, GEMINI_MODEL_LITE, GEMINI_MODEL_FALLBACK	Optional	Override model ids (defaults in src/lib/ai-models.ts)
SENTRY_DSN, NEXT_PUBLIC_SENTRY_DSN	Optional	Error reporting
SENTRY_AUTH_TOKEN	Optional	Readable production stack traces
UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN	Optional	Shared rate limiting (falls back to in-memory)

3. Apply the database schema

Run every file in supabase/migrations/ in numerical order, 001_schema.sql through 066_player_positions.sql, in the Supabase SQL Editor (or supabase db push). Migrations are idempotent. The app tolerates a missing table or column, so a feature simply stays empty until its migration has run.

Migrations 030 onward are described, with verification queries, in docs/MIGRATION_RUNBOOK.md. Run any migration that changes policies or data on production deliberately, not as part of a deploy.

Then insert a seed academy (or register one at /register-club):

INSERT INTO academies (id, name, location, province)
VALUES ('00000000-0000-0000-0000-000000000001', 'Growfit Sports Academy', 'Greater Durban', 'KwaZulu-Natal')
ON CONFLICT (id) DO NOTHING;

supabase/seed.sql seeds a fuller test project.

4. Configure Supabase Auth

In Authentication → Providers: enable Email, disable confirmation for a pilot (or configure SMTP), set Site URL to http://localhost:3000, and allow http://localhost:3000/api/auth/callback as a redirect URL.

5. Run it

cd web
npm run dev        # http://localhost:3000
npm test           # Jest
npm run test:e2e   # Playwright smoke tests
npm run build

---

Deployment

The web app deploys to Vercel from main only. web/vercel.json sets an ignoreCommand so every other branch is skipped, which means pull requests get no preview URL; verify visuals locally. Set the environment variables above in the Vercel project settings.

CI (.github/workflows/pr-checks.yml) runs tests and the build on every pull request, alongside CodeQL, SonarCloud and GitGuardian. Commit messages must not carry AI co-author trailers.

---

Key architectural decisions

See docs/ARCHITECTURE.md for the full design.

• Server Components by default: data is fetched on the server; "use client" is for interactive pieces
• Server Actions: all mutations go through typed actions in app/actions/. A "use server" file exports only async functions, and a test guards that
• Row Level Security: access is enforced in the database. *-data.ts loaders use the user's own session so a query can only return what that user may see
• Pure logic in lib/: rules (attendance, playing time, board instructions, Today homes) are plain functions with unit tests, separate from the loaders that fetch data
• Multi-academy: every row is scoped to an academy; each academy has its own name, crest, terms and drill library
• AI is reviewed, not trusted: structured output, safeguards and a coach approval step before anything reaches a child or parent

---

Further reading

• System design and architecture
• Release notes
• Product strategy, its research and feature specs
• Product roadmap and outstanding work
• AI and UX plan
• Migration runbook