sathish-create/fitcoachai_app

1. System Purpose and Entry Points

FitCoach AI is a cross-platform Flutter fitness-coaching client backed by a Python/FastAPI service. Its central workflow combines on-device pose capture, server-side form analysis, AI coach/diet requests, and Supabase-backed identity/data.

• Mobile bootstrap, dependency initialization, and routing: mobile/lib/main.dart

• Backend HTTP application and endpoint host: backend/main.py

• Combined local launcher: run_all.bat

2. Mobile Application Shell

The Flutter client is the primary user-facing runtime, targeting Android, iOS, desktop, and partial web support. It uses feature-oriented presentation folders, with shared navigation/layout and core services separating UI from external integrations.

• Persistent app layout/navigation boundary: mobile/lib/shared/widgets/main_layout.dart

• App-wide HTTP endpoint configuration: mobile/lib/core/network/api_constants.dart

• Native Android host entry: mobile/android/app/src/main/kotlin/com/gymai/fitcoach/MainActivity.kt

Control flow begins in the app bootstrap, routes users through landing/auth/setup, then presents dashboard and feature screens. Authentication state is managed separately from screens and controls protected versus guest access.

• Authentication state provider: mobile/lib/features/auth/presentation/providers/auth_provider.dart

• Login boundary: mobile/lib/features/auth/presentation/screens/login_screen.dart

• Setup/onboarding flow: mobile/lib/features/setup/presentation/screens/setup_screen.dart

3. Workout and Hybrid Pose-Analysis Pipeline

The workout feature is the core real-time interaction boundary. The mobile client captures camera-based MediaPipe pose landmarks for low-latency feedback, while the backend receives landmarks for exercise validation and rep/form analysis using the same general pose domain.

• Live workout UI and camera/pose integration: mobile/lib/features/workout/presentation/screens/workout_screen.dart

• Warmup and workout completion stages: mobile/lib/features/workout/presentation/screens/warmup_screen.dart, mobile/lib/features/workout/presentation/screens/workout_summary_screen.dart

• Backend request handling: backend/main.py

Backend pose processing is organized as an analyzer plus exercise-family rules. This makes the analyzer responsible for dispatching/common landmark interpretation and rule modules responsible for movement-specific conditions.

• Analysis coordinator: backend/engine/analyzer.py

• Rule abstraction/base: backend/engine/rules/abs.py, backend/engine/rules/base.py

• Representative body-part rule modules: backend/engine/rules/chest.py, backend/engine/rules/legs.py, backend/engine/rules/full_body.py

The packaged MediaPipe task is a deployment dependency of the backend, not a remote ML service.

• Pose model asset: backend/pose_landmarker.task

4. AI Coach and Remote API Boundary

The mobile API service is the client-side boundary for FastAPI calls, including coach chat, diet generation, pose-landmark processing, session reset, and health checks. The backend in turn uses Google Gemini for natural-language coaching and diet-generation behavior, with credentials supplied outside source control.

• HTTP service: mobile/lib/core/services/api_service.dart

• AI/chat interface surfaces: mobile/lib/features/coach/presentation/screens/coach_screen.dart, mobile/lib/features/coach/presentation/widgets/coach_chat_widget.dart

• Backend API/Gemini integration point: backend/main.py

Relevant runtime configuration/dependencies are captured in:

• Backend environment template: backend/.env.template

• Python service/ML dependencies: backend/requirements.txt

5. Identity, Persistence, and Device Services

Supabase is the external authentication and PostgreSQL/data boundary, supporting email/password and Google sign-in flows. Local preferences, notifications, speech, and exercise catalog loading remain client-side service concerns.

• Supabase integration: mobile/lib/core/services/supabase_service.dart

• Local persistence: mobile/lib/core/services/storage_service.dart

• Voice input/output: mobile/lib/core/services/voice_service.dart

Exercise browsing and workout selection consume a bundled asset catalog rather than requiring the backend.

• Catalog loader: mobile/lib/core/services/exercise_data_service.dart

• Exercise data: mobile/assets/exercises.json

• Library/exercise entry screens: mobile/lib/features/library/presentation/screens/library_screen.dart, mobile/lib/features/exercises/presentation/screens/exercises_screen.dart

6. Supporting Fitness Experiences and External Integrations

Feature screens compose the wider coaching journey: dashboard/steps tracking, workout schedules, calculators/diet planning, profile settings, and nearby gym discovery. Gym discovery depends on device location plus TomTom APIs; step tracking depends on device sensors; notifications are local-device scheduling.

• Dashboard and steps: mobile/lib/features/dashboard/presentation/screens/dashboard_screen.dart, mobile/lib/features/dashboard/presentation/screens/steps_screen.dart

• Planning and calculators: mobile/lib/features/schedules/presentation/screens/schedules_screen.dart, mobile/lib/features/calculators/presentation/screens/calculators_screen.dart

• Gym discovery: mobile/lib/features/gyms/presentation/screens/gyms_screen.dart

• Notification service/state: mobile/lib/core/services/notification_service.dart, mobile/lib/shared/providers/notifications_provider.dart