📱 Frontend Overview

Cross-Platform Flutter Application

:::tip TL;DR

One Flutter codebase → iOS, Android, Web
Provider for state • Firebase SDK for auth/storage/functions/messaging
Videos are uploaded through requestUploadPath as a single file today; client-side chunking is deferred
All Cloud Function calls go to europe-west1 — don't forget the region
17 Ace components + semantic design tokens (colors, typography, spacing, motion) — see Design System
New users see sample data until their first upload — see Key Features :::

The AceSense frontend is a cross-platform application built with Flutter, supporting iOS, Android, and Web from a single codebase.

🎯 Application Overview

:::info Tech Stack

Repository	Commit	Last Updated
acesense-frontend	`fff006e`	2026-05-28 (v1.0.4+1)

Framework: Flutter 3.10+ / Dart SDK ^3.10.3
State: Provider
Backend: Firebase (Auth, Firestore, Storage, Functions, Messaging)
Video: video_player metadata extraction + Firebase Storage upload
Charts: fl_chart for analytics visualization
UI: Material Design 3 with custom theming :::

🏗️ Application Architecture

📱 Screen Map

📂 Project Structure

Regenerated from the tree on 2026-08-16. This section was previously wrong in a way that mattered: it documented screens/, widgets/, providers/, navigation/ and billing/ as top-level directories and an l10n/messages/*.json catalogue. None of those exist. The app is organised by feature, state lives in state/, routing is go_router, and localisation is ARB-based.

lib/
├── main.dart                 # Entry point + MaterialApp
├── firebase_options.dart     # FlutterFire multi-platform config
├── config/                   # AppConfig + build flags (kUseMockData, App Check)
├── data/                     # mock.dart — drill catalogue, sample notifications
├── dev/                      # Developer-only preview harness (never shipped)
├── ds/                       # Design system
│   ├── theme.dart
│   ├── tokens/               # DsColors, DsType, DsSpacing, DsRadius, DsMotion
│   └── widgets/              # DsButton, DsCard, DsBadge, DsAppShell, …
├── features/                 # One directory per feature, screens live here
│   ├── analysis/             # match_analysis_screen, tabs/, mini_player, court_minimap
│   ├── auth/                 # welcome journey, sign in/up, onboarding, auth_layout
│   ├── billing/              # billing_screen, upgrade_prompt
│   ├── body/                 # training-load + prevention
│   ├── coach/                # player-facing coach dashboard
│   ├── coach_mode/           # coach roster + student notes
│   ├── flows/                # app_flows.dart — upload/record/consent/share flows
│   ├── help/  how_it_works/  legal/  notifications/  settings/  update/
│   ├── home/  sessions/  new_session/  practice/  profile/
│   ├── progression/          # badges, roadmap
│   └── wrapped/              # weekly recap
├── l10n/
│   ├── app_localizations.dart   # Re-export shim
│   ├── arb/                     # app_{en,de,es,fr,it,sv}.arb — 1542 keys each
│   └── generated/               # flutter gen-l10n output, do not hand-edit
├── models/                   # job, notification, tennis_analysis, user_stats
├── routing/                  # app_router.dart (go_router) + NotFoundScreen
├── services/                 # Firebase + domain services (see below)
└── state/                    # Riverpod providers
    ├── locale_provider.dart
    ├── notifications_provider.dart
    ├── player_coach_provider.dart
    └── progress_provider.dart

117 Dart files under lib/, 34 test files under test/.

Localisation

Six locales: en de es fr it sv, 1542 keys each, no drift. Source of truth is lib/l10n/arb/app_*.arb; lib/l10n/generated/ is output — never hand-edit it. Regenerate with flutter gen-l10n.

Two rules the codebase now enforces:

tool/l10n_audit.py runs in CI and fails the build on a hardcoded user-facing string. Excuse a string only in its ALLOW_EXACT/ALLOW_SITES list, with the reason.
Data layers carry facts, not words. PlayerCoachingService, DrillItem and ShotType are reachable from cached providers, so any copy resolved there would survive a language switch. They expose ids and numbers; the widget layer resolves copy per render. ShotType.stableName is the deliberate exception — a locale-independent key for the one comparison that needs it.

🔧 Key Services

AuthService

VideoService

Other services

Service	Purpose
`FirestoreService`	Thin data layer over the `users/`, `jobs/`, `feedback/` collections
`StorageService`	Video preprocess + single-file upload pipeline + signed URL retrieval
`AiConsentService`	First-upload AI analysis consent (App Store Guideline 5.1.1)

🌍 Localization

Language	Code	Status
🇬🇧 English	`en`	✅ Complete
🇩🇪 German	`de`	✅ Complete
🇫🇷 French	`fr`	✅ Complete
🇪🇸 Spanish	`es`	✅ Complete
🇮🇹 Italian	`it`	✅ Complete
🇸🇪 Swedish	`sv`	✅ Complete

📊 State Management

🧪 Testing

Type	Tool	Coverage Target
Unit Tests	`flutter_test`	80%
Widget Tests	`flutter_test`	70%
Integration	`integration_test`	Critical paths
E2E	Patrol	Happy paths

# Run all tests
flutter test

# Run with coverage
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html

🚀 Build & Deploy

Development

# Run on device
flutter run

# Run on web
flutter run -d chrome

# Run on specific device
flutter run -d <device_id>

Production

# iOS
flutter build ios --release

# Android
flutter build appbundle --release

# Web
flutter build web --release
firebase deploy --only hosting:app

☁️ Cloud Functions Integration

The app integrates with Firebase Cloud Functions for video processing.

Callable Functions

Function	Purpose
`requestUploadPath`	Validate video metadata, create job doc, return upload path
`reportUploadFailure`	Mark a still-pending job failed if the client upload fails before Storage finalization
`mergeChunkResults`	Deferred chunk result merge support; not called by the current upload flow

Example Usage

final functions = FirebaseFunctions.instanceFor(region: 'europe-west1');

// Request upload path
final callable = functions.httpsCallable('requestUploadPath');
final result = await callable.call({
  'fileName': 'match.mp4',
  'fileSize': 52428800,
  'duration': 180,
  'width': 1920,
  'height': 1080,
  'format': 'mp4',
});

final uploadPath = result.data['uploadPath'];
final jobId = result.data['jobId'];

try {
  // Upload file bytes to uploadPath with Firebase Storage.
} catch (error) {
  await functions.httpsCallable('reportUploadFailure').call({
    'jobId': jobId,
    'errorMessage': error.toString(),
  });
  rethrow;
}

Storage Trigger

The processVideoOnUpload function automatically triggers when videos are uploaded to the videos/{uid}/{sessionId}/ folder. If the upload fails before Storage finalization, the client calls reportUploadFailure so the job does not remain stuck in pending and the user's concurrent slot is released.

🎯 Next Steps

🎨 Design System — Ace components, design tokens, spacing, motion
⚡ Key Features — routing, analysis tabs, sample data, job status vocab
🔧 Frontend Setup Guide — install Flutter, run the app
📱 Frontend Dev Quickstart — 5-min role-based tour
🔌 API Reference — callable functions
🐛 Troubleshooting — common Flutter/Firebase issues

Was this page helpful?

🎯 Application Overview​

🏗️ Application Architecture​

📱 Screen Map​

🧭 Navigation Structure​

📂 Project Structure​

Localisation​

🔧 Key Services​

AuthService​

VideoService​

Other services​

🌍 Localization​

📊 State Management​

🧪 Testing​

🚀 Build & Deploy​

Development​

Production​

☁️ Cloud Functions Integration​

Callable Functions​

Example Usage​

Storage Trigger​

🎯 Next Steps​