TrainHub

AI-powered training management desktop application for personal trainers. Features on-device AI chat with RAG, video analysis, program scheduling, and exercise library management.

Architecture

lib/
├── core/               # Shared constants, extensions, router, theme, utils
├── domain/             # Business entities and repository interfaces
│   ├── entities/       # Freezed immutable models
│   └── repositories/   # Abstract repository contracts
├── data/               # Infrastructure and data access
│   ├── database/       # Drift ORM schema, DAOs
│   ├── mappers/        # Entity <-> DTO conversion
│   ├── repositories/   # Repository implementations
│   └── services/       # External service integrations (AI, embeddings)
└── presentation/       # UI layer
    ├── analysis/       # Video analysis feature
    ├── calendar/       # Program calendar
    ├── chat/           # AI chat with RAG
    ├── common/         # Shared widgets and dialogs
    ├── home/           # Dashboard
    ├── plan_editor/    # Training plan builder
    ├── settings/       # App settings and model management
    ├── shell/          # Main app layout (sidebar + tabs)
    ├── trainings/      # Training list management
    ├── welcome/        # First-launch onboarding
    └── workout_session/ # Active workout tracking

Layers:

• Domain -- Pure Dart. Entities (Freezed), abstract repository interfaces. No framework imports.
• Data -- Drift database, DAOs, mappers, repository implementations, AI services (llama.cpp, Nomic).
• Presentation -- Flutter widgets, Riverpod controllers, Freezed UI states.

Tech Stack

Layer	Technology
UI	Flutter 3.x, Material Design 3, shadcn_ui
State	Riverpod 2.6 with code generation
Routing	AutoRoute 9.2
Database	Drift 2.14 (SQLite)
DI	get_it 8.0
Immutability	Freezed 2.5
Local AI	llama.cpp (Qwen 2.5 7B + Nomic Embed v1.5)
Video	media_kit

Getting Started

Prerequisites

• Flutter SDK (stable channel)
• Dart SDK >= 3.10.7
• Desktop platform toolchain (Visual Studio for Windows, Xcode for macOS)

Setup

# Install dependencies
flutter pub get

# Run code generation
dart run build_runner build --delete-conflicting-outputs

# Launch app
flutter run -d windows   # or macos, linux

AI Models

The app uses local AI inference via llama.cpp. Models are downloaded automatically on first launch or from Settings > AI Models:

• llama-server binary (llama.cpp build b8130)
• Qwen 2.5 7B Instruct Q4_K_M (~4.7 GB) -- chat/reasoning
• Nomic Embed Text v1.5 Q4_K_M (~300 MB) -- text embeddings for RAG

Models are stored in the system documents directory. Total download: ~5 GB.

AI configuration constants are centralized in lib/core/constants/ai_constants.dart.

Code Generation

This project relies on code generation for several packages. After modifying any annotated files, run:

dart run build_runner build --delete-conflicting-outputs

Generated files (do not edit manually):

• *.freezed.dart -- Freezed immutable models
• *.g.dart -- Drift DAOs, Riverpod providers, JSON serialization
• app_router.gr.dart -- AutoRoute generated routes

Key Conventions

State Management

Each feature follows the controller + state pattern:

feature/
├── feature_page.dart           # @RoutePage widget
├── feature_controller.dart     # @riverpod controller
├── feature_state.dart          # @freezed state model
└── widgets/                    # Extracted sub-widgets

Controllers are @riverpod classes that manage async state. States are @freezed classes.

Dependency Injection

Services and repositories are registered in lib/injection.dart using get_it:

• Singletons -- database, DAOs, AI services
• Lazy singletons -- repositories

Controllers access dependencies via getIt<T>().

Naming

• Files/directories: snake_case
• Classes: PascalCase
• Variables/methods: camelCase
• Constants: UPPER_CASE for environment variables, camelCase for class constants
• Booleans: prefix with is, has, can (e.g., isLoading, hasError)
• Functions: start with a verb (e.g., loadSession, createProgram)

Widget Extraction

Keep page files under 200 lines. Extract standalone widget classes into a widgets/ subdirectory within the feature folder.

Project Configuration

File	Purpose
lib/core/constants/app_constants.dart	App name, version, window sizes
lib/core/constants/ai_constants.dart	AI model config, ports, URLs
lib/core/constants/ui_constants.dart	Spacing, border radius, animation duration
lib/core/theme/app_colors.dart	Zinc palette, semantic colors
lib/core/theme/app_theme.dart	Material 3 dark theme