8.6 KiB
Product specification
Purpose
EvolioHealth gives individuals and families control over their health and fitness history on infrastructure they choose. It is a wellness and personal tracking product, not a medical device and not a source of diagnosis or treatment.
Users and roles
There is no arbitrary user limit. Capacity depends on host resources.
Only two roles exist:
administrator: configures the instance, invites users, manages operational settings, creates global backups, restores the instance, reviews security events, and can disable accounts or revoke compromised sessions/devices.user: manages their profile, devices, personal data, sharing, exports, and deletion.
Administrators MUST NOT browse, decrypt, export, impersonate, or otherwise access another user's health records, private notes, measurements, or progress photos. Operational backups may contain encrypted records but do not confer application-level access.
Onboarding
An unconfigured instance exposes a simple /setup workflow. It creates the first administrator, default language, instance timezone, optional SMTP configuration, and initial photo policy. After completion, /setup MUST be permanently closed unless the instance is genuinely reset.
The setup generates a cryptographically random master key at /config/master.key. The final screen MUST state its location and allow the administrator to download a copy after reauthentication. Existing data without a valid key MUST cause startup to fail; the server MUST NOT silently generate a replacement.
Additional accounts are invitation-only, preferably by email. An invitation is random, single-use, revocable, short-lived, role-bound, and does not disclose account existence to unauthorized callers. On first login the user chooses French or English, metric or imperial display, timezone, password and TOTP, and may register passkeys.
The profile MAY include display name, avatar, date of birth, height, biological sex (male or female) when needed for supported calculations and model selection, and a self-declared morphology. Morphology is descriptive and MUST NOT be presented as a diagnosis or deterministic prediction of training response.
Authentication and devices
Password authentication always requires TOTP. Passkeys/WebAuthn are a passwordless alternative and multiple passkeys may be registered, including credentials stored in Bitwarden-compatible managers.
Each user MUST manage their own sessions, passkeys, and paired devices from Web and mobile. A new mobile device can be added through:
- a short-lived, one-time QR pairing code generated by an already authorized device;
- email, password, and TOTP;
- a passkey.
The phone creates a device key pair; its private key remains in Android Keystore and only the public key is registered. Pairing authorization is durable until revoked, while access tokens remain short-lived. Revocation invalidates refresh credentials and the device key immediately when it next contacts the server.
The default Web idle session is two hours. Mobile access tokens should last about ten minutes and use rotating, replay-detecting refresh credentials without prompting every two hours.
Core data
The first product scope includes:
- heart rate and resting heart rate;
- sleep sessions and stages;
- daily activity summaries;
- exercise sessions, with Kinomap assumed to synchronize through Health Connect for subscribed users;
- weight and impedance from direct BLE access to Mi Body Composition Scale 2;
- derived body composition values, explicitly labeled as estimates;
- manual body-measurement sessions;
- dated progress photos and profile avatars;
- charts, history, source attribution, correction, deletion, and export.
Future scope includes strength-training programs, exercise catalogs, nutrition catalogs, and correlation insights. Replaceable reference datasets belong in references.db; private programs and user actions belong in PocketBase.
Measurement sessions
Manual measurements are grouped in a dated session. The timestamp, timezone, notes, and context belong to the session; individual values link to it. A session may contain weight, neck, shoulders, chest, waist, abdomen, hips, left/right arms, forearms, thighs, calves, and associated photos.
Users can create, edit, correct, and delete sessions and their values. The UI provides:
- an anatomically mapped male or female silhouette;
- current values positioned on the silhouette;
- history navigation by session;
- per-metric evolution curves and date-range filters;
- comparison of two sessions;
- an indicative parametric silhouette derived from measurements where feasible.
The generated silhouette MUST be described as indicative, not a faithful 3D reconstruction or medical analysis. Initial morphology may influence only an initial visual template; measured values remain authoritative.
The product should teach consistent measurement conditions: ideally morning, fasted, after using the toilet, before exercise, with consistent posture, tape position and tension. Photo guidance should recommend consistent lighting, distance, framing, and posture. These are consistency tips, not medical advice, and may be dismissed.
Photos
Progress photos form a chronological timeline and may be categorized as front, back, left, right, or custom. Users can compare the first and latest matching view, any two selected dates, side-by-side, and with an before/after slider.
Photos are resized and re-encoded before transfer when possible, stripped of EXIF metadata, validated again by the server, encrypted individually, and stored outside PocketBase. Existing photos are never recompressed when an administrator changes the future-photo policy.
The administrator sets the instance photo policy in the Web administration UI during setup and later. Profiles should include economical, standard, and high-quality choices (for example 1280/80%, 1600/85%, and 2048/90%). The administrator may allow users to choose up to the instance maximum or lock a single policy.
Avatars have a fixed policy: square crop, 512x512 JPEG at approximately 85% quality, a 128x128 thumbnail, no EXIF, encrypted private storage, and authenticated access only.
Offline and synchronization UX
The Companion remains fully useful offline for already synchronized data. Synchronization occurs:
- at application start when connectivity is available;
- manually;
- after local entry, edit, deletion, scale reading, or photo capture when possible;
- periodically for Health Connect according to user choice: manual only, every 6, 12, or 24 hours;
- over Wi-Fi only or Wi-Fi/mobile data according to user choice.
Android scheduling is opportunistic; exact execution times are not promised. No push notifications are required.
Language, units, and time
French and English are supported initially. Metric and imperial display are supported. Changing language or display system MUST NOT rewrite stored measurements.
Values use canonical storage units (for example millimetres and grams) while retaining original imported value and unit. Unknown or ambiguous units are rejected or require confirmation. Instants are stored in UTC and retain source timezone when needed. TZ, such as Europe/Paris, is the instance default, not a replacement for user or record timezone.
Export, sharing, rectification, deletion
User exports are available only from the Web application. A personal export includes human-readable Excel/LibreOffice-compatible CSV files and photos as JPEG. CSV files use explicit ISO dates, unambiguous numeric formatting, named units, and UTF-8.
Users may generate a share image containing only explicitly selected charts, values, periods, text, or photos. Sharing uses the operating-system share sheet; EvolioHealth does not publish directly to social networks. Generated images contain no email, server URL, hidden metadata, or identity by default.
All personal records can be viewed, corrected, and deleted. Account deletion requires recent authentication, a clear irreversible-warning screen, an offer to export first, and explicit confirmation. It revokes devices and sessions, deletes records, media, shares, and user encryption material, and retains only a minimal non-health security event. Backup retention and delayed purge limitations MUST be explained.
Explicit exclusions for the initial release
- iOS application;
- medical diagnosis or treatment recommendations;
- direct simultaneous BLE connection to rowing equipment while Kinomap is active;
- automatic social-network posting;
- push notifications;
- facial or body recognition;
- direct frontend access to PocketBase;
- mandatory certificate pinning for arbitrary self-hosted domains.