Train Libre: Modular Documentation Suite

Welcome to the technical documentation suite for Train Libre, a highly performant, offline-first, and privacy-centric wellness, sleep, and nutrition tracking application. This suite provides detailed architecture specifications, state management paradigms, and mathematical descriptions of the core algorithmic features of the application.

Project Vision

Train Libre is designed around the core principles of user autonomy, offline capability, and algorithmic transparency. By avoiding any centralized backend, storing all user records in a local SQLite database (via Drift), and utilizing a Bring Your Own Key (BYOK) model for optional AI enhancements, the application guarantees absolute user privacy and data ownership.

---

Documentation Directory Map

This documentation suite is split into highly modular, focused files categorised by audience and purpose. Use the links below to navigate the suite.

1. Developer Documentation (documentation/developer/)

For software engineers, system architects, and technical contributors.

• System Overview & Testing Philosophy: High-level system purpose, tech stack, and automated testing strategy spanning unit, integration, and database migration tests.
• System Architecture & Runtime Wiring: Clean Architecture boundaries (Presentation $\rightarrow$ Domain $\leftarrow$ Data), application startup and Provider wiring in main.dart, Drift SQLite lifecycle at schema version 31, and background tasks.
• Data Flow & State Lifecycle: Detail on our "Reactive Reads / Imperative Writes" paradigm, reactive Drift stream handlers, subscription lifecycles, and edit-mode user interface input blocking.
• Localization Architecture: Offline-first relational localization strategy for catalogs and UI strings across 5 supported locales, schema migration to normalized translation tables, and guide for adding locales.
• Home Screen Widgets (iOS & Android): Cross-platform snapshot architecture and native widget families for both iOS (WidgetKit) and Android (Glance/AppWidgetProvider), their configuration, and deep links.

2. Feature Transparency & Algorithmic Logic (documentation/features/)

For advanced users, mathematical evaluators, and privacy auditors who seek complete transparency into our smart processing engines.

• Capabilities & Privacy Overview: Summary of the app's smart capabilities, local processing model, native secure storage, and opt-in zero-profiling telemetry boundaries.
• Bayesian TDEE Estimator (Kalman Filter): Full mathematical and algorithmic analysis of the Adaptive Diet Recommendation Engine, including Kalman filter equations, variance boundaries, completeness coefficients, and linear ramps.
• Macronutrient Distribution: How the estimator's calorie target becomes protein, carbohydrate, and fat — the per-kilogram anchors, the fat floor, the order in which the distribution gives way on a constrained budget, and worked examples.
• BYOK AI Meal Capture & Validation: Core detail on the local BYOK API integration, system prompts restricting LLM calculations, fuzzy string matching, target-fit verification, and the 3-pass self-repair verification loop.
• Meal Capture Pipeline: The capture paths around the analysis — unified camera with passive barcode detection, voice dictation, meals as logged events, photo storage, and what leaves the device on each path.
• Depth Scale Hint (LiDAR): How measured scale facts and an optional false-colour depth image improve portion estimation on LiDAR devices, including the quality gate and the explicit non-goals.
• Native Health Sync & Export: Technical overview of the Apple HealthKit and Google Health Connect pipelines: passive vitals import (steps, sleep, pulse), outbound export (measurements, nutrition/hydration, workouts), step segment merging, and the SQLite-backed idempotency architecture.
• Sleep Health Score Engine (SHS v3.5): Complete technical specification of our sleep scoring algorithms, including Gaussian, logistic, and quadratic curves for 5 domains and the continuous soft-cap multiplier penalty logic.
• Muscle Recovery & Readiness Model: Log-based muscle readiness using per-set RIR, role-weighted exposure, different muscle decay profiles, and time-decaying residual load.
• Estimated 1-Rep Max Heuristic: The Brzycki-based submaximal strength estimation model behind personal records and strength progression, accounting for effective load across assisted, bodyweight, and loaded sets, and its non-medical scope.
• Workout progression: A first-working-set recommendation for eligible load-and-repetition exercises, with simple double progression and later-set e1RM back-offs.
• Live Activity & Workout Session: The iOS Live Activity and Dynamic Island surface for a running workout, and the state it mirrors.