projectsprav/xho

1. This is a multi-app health platform monorepo.

The repository combines three client surfaces, a Python API, background workflows, and supporting infrastructure. The product domains are clearly health/wellness: onboarding, biomarker tracking, workouts, diet, period tracking, medications, readiness, and clinician/coach oversight.

2. Client boundary: mobile app.

apps/mobile is an Expo/React Native app organized around route-based screens. It covers patient-facing workflows such as onboarding, auth via OTP, home/dashboard, workouts, biomarkers, body metrics, period tracking, CGM setup/reports, diet, wearables, and medication-related features. It uses local state stores plus hook-based data fetching, and includes native health sync services for Apple Health and Google Health.

3. Client boundary: web dashboards.

apps/web is the main Next.js admin/clinical web app used for browser-based operations. It exposes admin, coach, and physician sections for evidence review, protocol assignment, workout and nutrition builders, client/patient views, and operational dashboards. The README notes browser requests go through same-origin /api/v1, which Next.js proxies to the backend locally or in Docker.

4. Second web surface: physician-web.

apps/physician-web is a separate Next.js app with a similar shape, focused on physician workflows and dashboards. It appears to mirror part of the main web experience but remains a distinct frontend boundary.

5. Backend core: the API service.

services/api is the central application server. Its structure is classic layered backend: routers expose HTTP endpoints, services hold business logic, models define persistence, schemas define request/response contracts, and dependencies enforce cross-cutting concerns like auth, consent, audit, cache, and database access. This is the main integration point for all clients.

6. Domain segmentation in the API.

The API is organized by product capability rather than by technical tier: auth, onboarding, profiles, biomarkers, body metrics, CGM, check-ins, diet/nutrition, recipes, foods, workouts, workout sessions, habits, medications, messaging, period tracking, progress photos, readiness, physician workflows, and coach workflows. That makes the backend the canonical source of truth for user state and longitudinal health data.

7. Persistent data layer.

The primary transactional store is Postgres, managed through SQLAlchemy-style models and Alembic migrations. The migration history shows the system has evolved through multiple feature waves: onboarding/profile expansion, body metrics, wearable support, CGM, biomarkers, workouts, nutrition plans, evidence governance, period tracking, and medications. The database is the shared substrate for the API, web apps, and scheduled analytics jobs.

8. Asynchronous event pipeline.

Kafka is used for event-driven processing. The API includes producers plus consumers for biomarker, CGM, wearable, spike detection, and notification dispatch flows. This separates ingest from downstream processing, enabling delayed computation, alerting, and fan-out to notifications without blocking client requests.

9. Scheduled analytics and automation.

services/airflow hosts a large set of DAGs for recurring jobs: readiness, vitality score, adherence, body metrics, CGM polling and response analysis, protocol generation, progressive overload, medication reminders/renewals, period notifications/correlations, wearable sync, and engagement metrics. These workflows read from the core data store and event streams, then materialize derived insights or trigger operational actions.

10. Protocol/evidence engine is a major business subsystem.

The backend contains dedicated protocol-engine code for clinical rules, diet plan building, workout plan building, evidence-gated generation, and progressive overload logic. The admin web UI surfaces evidence review and content management for recipes, exercises, workout templates/programs, nutrition plans, and protocol assignments. This is the mechanism that turns clinical/content rules into patient-facing plans.

11. Wearable and native health integration boundary.

Mobile-side health services collect device/platform data; the API has dedicated wearable and native-health routers, consumers, and constants for standardized data types. This implies a pipeline from phone/device sensors into the backend, then into derived metrics such as readiness, vitality score, CGM, and period-related insights.

12. Media/file handling and external services.

The repo includes storage and OCR/report-processing services, suggesting lab uploads and progress photos are stored outside the DB, likely in object storage. Appwrite is an external prerequisite for local development, so identity/auth is at least partially anchored in an external platform. MinIO is listed in the runtime stack and is the likely object store.

13. Cross-cutting observability and deployment.

Operationally, the stack is containerized with Docker Compose and includes Nginx, Promtail/Loki, Prometheus/Grafana, and Signoz/OTel collector. The API has explicit observability middleware, metrics, and OTEL wiring. This is a production-oriented setup with centralized logging, tracing, and metrics across apps and services.

14. Seed/test/tooling supports content-heavy workflows.

The repo contains many seed scripts and extensive tests, especially around protocol generation, evidence, admin surfaces, and domain services. That’s a sign the system depends heavily on curated content and rule-based behavior, not just CRUD APIs.

15. High-level data flow to diagram.

User/device data enters through mobile or web → hits the API → persists in Postgres and object storage → emits Kafka events → background consumers and Airflow DAGs compute derived insights and notifications → results are read back by mobile/web dashboards. Admin/clinician workflows feed curated content and protocol rules back into the same API, which then drives patient-facing plans and alerts.