From d376d5ee959fd54339dbe4e5f2caada832b5e539 Mon Sep 17 00:00:00 2001 From: Matthias Jacob Date: Thu, 17 Sep 2026 01:38:46 +0200 Subject: [PATCH] Refine project description and architecture section in README.md for clarity and detail --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 8b6e852..ca43755 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,17 @@ # Private Health -This project aims to create the necessary building blocks in order to allow collect and analyze one's personal health data in a privacy-oriented manner. Instead of closed-source apps and dubious clouds, it should use a FLOSS stack. +This project aims to create the necessary building blocks to collect, aggregate, and analyze one's personal health data while maintaining data sovereignty. Instead of closed-source apps and dubious clouds, it should use a FLOSS stack. ## Architecture -This architecture leans on proven, reusable components wherever possible. -Refer to the diagram below for an overview: it highlights mature apps in green, partially solved areas in orange, and gaps that require mostly new development in red. +1. Start with what already works. Projects like Gadgetbridge or OpenScale have lively communities and cover a lot of ground. Lean on them whenever possible instead of reinventing the collector layer. +2. When a FLOSS bridge is missing, accept a constrained compromise—HealthConnect or a similar on-device broker—so long as it keeps data encrypted locally and gives us clear levers for sync frequency, retention, and audit logs. +3. Only build bespoke pieces (Nextcloud health app, dashboards, data science notebooks) where there is a genuine capability gap or user story that no existing FLOSS project covers. -At the moment, the [HealthConnect API](https://developer.android.com/health-and-fitness/health-connect) is remains a pragmatic choice for integration and synchronisation. -It lives on the user’s phone, encrypts data, and speaks schemas for dozens of vendors. That buys time for a gentle migration: you can keep your current wearable, pull data into a local store, and steadily replace proprietary parts as FLOSS apps/adapters mature. +The diagram below mirrors that hierarchy: green blocks are “ready to plug in,” orange blocks still need shaping or configuration, and red blocks mark the blank canvas where we design from scratch. In day-to-day terms, that means we can already sync scales or fitness trackers with minimal effort, but we must design a trustworthy Nextcloud app, decide how dashboards surface trends, and write glue that keeps everything coherent. -However, alternative solutions to the HealthConnect API are more than welcome. +HealthConnect remains the pragmatic bridge for now. It lives on the user’s phone, encrypts data, and speaks schemas for dozens of vendors. That buys time for a gentle migration: you can keep your current wearable, pull data into a local store, and steadily replace proprietary parts as FLOSS collectors mature. We should still document a path away from HealthConnect by pairing it with community-built collectors or writing our own bridge once the ecosystem catches up. Any alternative proposal should show the same benefits—broad device coverage, schema richness, and user-controlled sync rules. ```mermaid flowchart LR