Home / Docs

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.