SKILLIQ

SkillIQ (Pro Am Hockey IQ) is an AI-powered hockey skill-analysis platform that enables players to upload practice or game video, receive automated skill scoring and feedback, and follow personalised training plans.

1. OVERVIEW

SkillIQ (Pro Am Hockey IQ) is an AI-powered hockey skill-analysis platform that enables players to upload practice or game video, receive automated skill scoring and feedback, and follow personalised training plans. The system comprises three interconnected tiers:

A consumer-facing Flutter mobile application for iOS and Android.
A Next.js internal admin dashboard for customer, subscription, and payment management.
A FastAPI Python backend that serves both clients and integrates AI video analysis.

Layer	Project	Primary Stack
Mobile App	Skilliq	Flutter / Dart
Admin Dashboard	skilliq-admin	Next.js 15 · React 18 · TypeScript
Backend API	skilliq-api-main	FastAPI (Python 3) · Uvicorn
Database / Auth	—	Supabase (PostgreSQL + Auth)
File Storage / CDN	—	AWS S3 + CloudFront
AI Analysis	—	12Labs + Anthropic Claude

2. TECH STACK

2.1 Mobile App – skilliq

Concern	Solution
Language / Framework	Dart · Flutter (SDK ≥3.0.0)
State Management	Custom ChangeNotifier (AuthProvider) — no BLoC/Riverpod
Networking	Custom BaseApiService wrapping http · auth headers, token refresh, multipart upload, 30 s timeout
Authentication	supabase_flutter + flutter_secure_storage (token persistence)
Routing	Custom named routes via AppRoutes class
Deep Linking	app_links package
Media	image_picker · video_player
Sharing / Export	share_plus · pdf
API Base URL	https://api.proamhockeyiq.com (hardcoded in api_config.dart)

2.2 Admin Dashboard — skilliq-admin

Concern	Solution
Framework	Next.js 15 (App Router) · React 18.3 · TypeScript 5.6
UI Components	Radix UI primitives + shadcn-style components · Tailwind CSS 4
Networking	Native fetch — app/api/* route handlers act as reverse proxy to backend
Authentication	HTTP-only cookies (separate from mobile JWT); transparent token refresh in fetchWithAuth()
Image CDN	CloudFront (d6jmtt54gyl44.cloudfront.net)
Backend URL	BACKEND_URL=https://api.proamhockeyiq.com/api/v1/admin (env var)

2.3 Backend API — skilliq-api-main

Concern	Solution
Framework	FastAPI (Python 3) · Uvicorn ASGI · Pydantic v2
Authentication	Supabase JWT (ES256) verified via JWKS; separate cookie-based admin session
Database	PostgreSQL via Supabase (anon-key client + service-role client)
File Storage	AWS S3 — presigned upload URLs via boto3
AI — Video	12Labs (video understanding + segmentation)
AI — Analysis	Anthropic Claude (skill scoring & feedback generation)
API Docs	Auto-generated Swagger UI at /docs
Key files	main.py (2 634 lines, all routes) · auth.py · models.py · services.py

3. SYSTEM ARCHITECTURE

The diagram below shows the high-level component topology and primary data flows between the three application tiers and the shared infrastructure services.

4. KEY FLOWS

4.1 Mobile Auth & Session

App signs up or logs in against POST /api/v1/auth/login.
Backend validates credentials via Supabase Auth and returns a Supabase JWT (ES256).
App stores the JWT in flutter_secure_storage and attaches it as a Bearer token on every subsequent request.
On 401 responses, BaseApiService calls POST /api/v1/auth/refresh automatically before retrying.

4.2 Video Upload & AI Analysis

Mobile calls POST /api/v1/upload/presign to obtain a time-limited S3 presigned URL.
Video is uploaded directly from the device to AWS S3 (bypasses the backend for large binary transfer).
App calls POST /api/v1/analyses with the S3 key; backend triggers 12Labs for video segmentation.
Anthropic Claude scores skills and generates feedback from the 12Labs output.
Results (scores, recommendations) are persisted to Supabase and polled by the app via GET /api/v1/analyses.

4.3 Admin Auth & Dashboard

Admin logs in via Next.js route handler POST /api/auth/login, which proxies to POST /api/v1/admin/auth/login.
Backend issues HTTP-only access_token and refresh_token cookies; Next.js rewrites them with Path=/.
All admin API calls are proxied through app/api/* route handlers — the browser never communicates with the backend domain directly.
fetchWithAuth() in lib/api/auth.ts transparently refreshes expired cookies before retrying failed requests.

4.4 Image Delivery

Profile and content images are stored in AWS S3 during upload/analysis.
The admin dashboard fetches images via CloudFront CDN (d6jmtt54gyl44.cloudfront.net), configured in next.config.ts.

This page will establish a WebSocket connection to the server and send messages back and forth.

5. API SURFACE SUMMARY

All endpoints are served under /api/v1/. Mobile clients use Bearer JWT; admin endpoints (/api/v1/admin/*) use HTTP-only cookie sessions.

Route Group	Methods	Description
/api/v1/auth/*	POST	Signup, login, logout, refresh, forgot/reset/change password, MFA, sessions
/api/v1/profile/*	GET · PATCH	Get/update profile, stats, notifications, avatar, account deletion
/api/v1/analyses/*	GET · POST	Submit video for analysis, list results, progress, share, retry
/api/v1/upload/*	POST	S3 presigned URL generation, upload confirmation, sample videos
/api/v1/training/*	GET · PATCH	List plans, active plan, enroll, update status
/api/v1/achievements/*	GET	List user achievements
/api/v1/notifications/*	GET · PATCH	List and manage push notifications
/api/v1/admin/auth/*	POST	Admin login/logout (cookie-based)
/api/v1/admin/customers/*	GET · PATCH	Customer list, detail, search, filter
/api/v1/admin/subscriptions/*	GET · POST · PATCH	Plan management, enroll, status
/api/v1/admin/payments/*	GET	Transaction history, stats
/api/v1/admin/promo-codes/*	GET · POST · PATCH · DELETE	Promo CRUD, usage tracking
/api/v1/admin/dashboard/*	GET	Aggregate stats, recent orders

6. AUTHENTICATION ARCHITECTURE

Two distinct authentication mechanisms operate on the same backend, separated by client type:

Aspect	Mobile (Flutter)	Admin (Next.js)
Token type	Supabase JWT (ES256 Bearer)	HTTP-only cookie pair (access + refresh)
Issued by	POST /api/v1/auth/login	POST /api/v1/admin/auth/login
Storage	flutter_secure_storage	Browser HTTP-only cookies (set by Next.js proxy)
Refresh	POST /api/v1/auth/refresh (auto)	fetchWithAuth() retries with refresh cookie
Verification	JWKS fetch + ES256 verify + issuer/audience check	ADMIN_COOKIE_* env var secrets
Browser access	N/A	Never — cookies are HTTP-only and proxied

7. DATA LAYER

7.1 Database (Supabase / PostgreSQL)

Inferred tables from backend route handlers and Pydantic models:

Table	Purpose
profiles	User profile data — name, avatar, skill levels, linked to Supabase Auth UUID
analyses	AI analysis results — S3 video key, skill scores, status, created_at
training_plans	Plan definitions and user enrolment/progress
achievements	Badge/milestone definitions and user unlocks
subscriptions	User subscription plans and status
payments	Transaction records
promo_codes	Discount codes with usage tracking
notifications	In-app and push notification records
samples	Reference sample videos for analysis comparison

Two Supabase clients are used: an anon-key client (user-scoped row-level security) and a service-role client (bypasses RLS for admin operations). Business logic is implemented via stored procedures called through supabase.rpc().

8. INFRASTRUCTURE & INTEGRATIONS

Service	Provider	Role
PostgreSQL + Auth	Supabase	Primary database and user identity store
File Storage	AWS S3	Video uploads and generated content; accessed via presigned URLs
CDN	AWS CloudFront	Low-latency image delivery to the admin dashboard
Video Understanding	12Labs	Shot segmentation and player tracking from uploaded video
AI Scoring	Anthropic Claude	Natural language skill scoring and training feedback
API Docs	FastAPI /docs	Auto-generated Swagger UI — the only formal API documentation

9. GAPS & RECOMMENDATIONS

No shared API contract

There is no OpenAPI export, Postman collection, or schema file shared between repos. The FastAPI Swagger UI at /docs is the only reference. Recommendation: export the OpenAPI JSON from FastAPI and commit it to a shared location so both client teams can use it.

No project documentation

All three repositories have only generic GitLab boilerplate READMEs. Recommendation: add setup guides, environment variable references, and architecture summaries to each repo’s README.

Hardcoded API URL in Flutter app

The production base URL is hardcoded in api_config.dart. flutter_dotenv is present but disabled. Recommendation: enable .env-based config so staging and production environments can be switched without code changes.

Monolithic backend file

All 2,634 lines of route definitions live in a single main.py. Recommendation: split into routers using FastAPI’s APIRouter (e.g. auth_router, analyses_router, admin_router) to improve maintainability.

Dual auth mechanisms

Two distinct auth flows (Bearer JWT + cookie sessions) run on the same backend. Recommendation: document the boundary clearly and consider unifying the admin flow to JWT-in-cookie for consistency.

Trust and Worth

Our Customers

We are having a diversified portfolio and serving customers in the domains namely Sports Management, Online Laundry System, Matrimonial, US Mortgage, EdTech and so on.