# projectsprav/xho architecture

> Architecture diagram of the GitHub repository projectsprav/xho, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/projectsprav/xho
- Repository: https://github.com/projectsprav/xho

## Overview

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.

Main entry points: [`services/api`](https://github.com/projectsprav/xho/tree/main/services/api) (API server), [`docker-compose.yml`](https://github.com/projectsprav/xho/blob/main/docker-compose.yml) (Runtime stack), [`services/api/services`](https://github.com/projectsprav/xho/tree/main/services/api/services) (Domain services), [`services/airflow/dags`](https://github.com/projectsprav/xho/tree/main/services/airflow/dags) (Airflow DAGs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_mobile["Mobile app<br/>expo rn"]
  node_mobile_health["Health sync<br/>native integration"]
  node_web["Admin web<br/>nextjs app"]
  node_physician_web["Physician web<br/>nextjs app"]
end

subgraph group_backend["Core backend"]
  node_api["API server<br/>python service"]
  node_routers["HTTP routers<br/>api boundary"]
  node_domain_services["Domain services<br/>business logic"]
  node_protocol_engine["Protocol engine<br/>clinical rules"]
  node_models["Data models<br/>persistence models"]
  node_migrations["Migrations<br/>schema history"]
  node_kafka["Kafka pipeline<br/>event stream"]
  node_airflow["Airflow DAGs<br/>scheduled workflows"]
  node_storage[("Object storage<br/>file storage<br/>[storage.py]")]
end

subgraph group_ops["Ops & infra"]
  node_observability{{"Observability<br/>otel/metrics"}}
  node_compose["Runtime stack<br/>docker compose<br/>[docker-compose.yml]"]
end

node_mobile -->|"patient API"| node_api
node_mobile -->|"syncs data"| node_mobile_health
node_web -->|"same-origin API"| node_api
node_physician_web -->|"clinical API"| node_api
node_api -->|"exposes"| node_routers
node_routers -->|"delegates"| node_domain_services
node_domain_services -->|"builds plans"| node_protocol_engine
node_domain_services -->|"persists"| node_models
node_models -->|"evolves schema"| node_migrations
node_api -->|"publishes events"| node_kafka
node_kafka -->|"feeds jobs"| node_airflow
node_airflow -->|"materializes insights"| node_api
node_airflow -->|"reads/writes"| node_models
node_api -->|"stores files"| node_storage
node_api -->|"emits telemetry"| node_observability
node_compose -->|"runs"| node_api
node_compose -->|"runs"| node_web
node_compose -->|"runs"| node_physician_web
node_compose -->|"includes"| node_observability

click node_mobile "https://github.com/projectsprav/xho/tree/main/apps/mobile"
click node_mobile_health "https://github.com/projectsprav/xho/tree/main/apps/mobile/src/services/health"
click node_web "https://github.com/projectsprav/xho/tree/main/apps/web"
click node_physician_web "https://github.com/projectsprav/xho/tree/main/apps/physician-web"
click node_api "https://github.com/projectsprav/xho/tree/main/services/api"
click node_routers "https://github.com/projectsprav/xho/tree/main/services/api/routers"
click node_domain_services "https://github.com/projectsprav/xho/tree/main/services/api/services"
click node_protocol_engine "https://github.com/projectsprav/xho/tree/main/services/api/services/protocol_engine"
click node_models "https://github.com/projectsprav/xho/tree/main/services/api/models"
click node_migrations "https://github.com/projectsprav/xho/tree/main/services/api/alembic/versions"
click node_kafka "https://github.com/projectsprav/xho/tree/main/services/api/messaging"
click node_airflow "https://github.com/projectsprav/xho/tree/main/services/airflow/dags"
click node_storage "https://github.com/projectsprav/xho/blob/main/services/api/services/storage.py"
click node_observability "https://github.com/projectsprav/xho/tree/main/services/api/observability"
click node_compose "https://github.com/projectsprav/xho/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mobile,node_mobile_health,node_web,node_physician_web toneBlue
class node_api,node_routers,node_domain_services,node_protocol_engine,node_models,node_migrations,node_kafka,node_airflow,node_storage toneAmber
class node_observability,node_compose toneMint
```

## Components

### Client apps

Patient and clinician-facing surfaces

- [Mobile app](https://github.com/projectsprav/xho/tree/main/apps/mobile): expo rn · Patient-facing onboarding, tracking, and workout experience · `apps/mobile`
- [Health sync](https://github.com/projectsprav/xho/tree/main/apps/mobile/src/services/health): native integration · Apple Health and Google Health device data collection · `apps/mobile/src/services/health`
- [Admin web](https://github.com/projectsprav/xho/tree/main/apps/web): nextjs app · Primary browser dashboard for admin, coach, and physician workflows · `apps/web`
- [Physician web](https://github.com/projectsprav/xho/tree/main/apps/physician-web): nextjs app · Separate physician-focused web surface · `apps/physician-web`

### Core backend

API, domain services, persistence, and async processing

- [API server](https://github.com/projectsprav/xho/tree/main/services/api): python service · Central HTTP application server and integration hub · `services/api`
- [HTTP routers](https://github.com/projectsprav/xho/tree/main/services/api/routers): api boundary · Capability-specific endpoints for auth, biometrics, workouts, diet, meds, and admin · `services/api/routers`
- [Domain services](https://github.com/projectsprav/xho/tree/main/services/api/services): business logic · Core workflows for protocol generation, scoring, meds, periods, and reports · `services/api/services`
- [Protocol engine](https://github.com/projectsprav/xho/tree/main/services/api/services/protocol_engine): clinical rules · Evidence-gated workout and diet plan generation with progression logic · `services/api/services/protocol_engine`
- [Data models](https://github.com/projectsprav/xho/tree/main/services/api/models): persistence models · SQLAlchemy-style entities for longitudinal health and operational data · `services/api/models`
- [Migrations](https://github.com/projectsprav/xho/tree/main/services/api/alembic/versions): schema history · Alembic migration history for feature waves and schema evolution · `services/api/alembic/versions`
- [Kafka pipeline](https://github.com/projectsprav/xho/tree/main/services/api/messaging): event stream · Producers and consumers for biomarker, CGM, wearable, spike, and notification flows · `services/api/messaging`
- [Airflow DAGs](https://github.com/projectsprav/xho/tree/main/services/airflow/dags): scheduled workflows · Recurring analytics, reminders, correlations, and protocol jobs · `services/airflow/dags`
- [Object storage](https://github.com/projectsprav/xho/blob/main/services/api/services/storage.py): file storage · Externalized reports, uploads, and media handling · `services/api/services/storage.py`

### Ops & infra

Container, observability, and deployment support

- [Observability](https://github.com/projectsprav/xho/tree/main/services/api/observability): otel/metrics · Metrics, tracing, logs, and runtime instrumentation · `services/api/observability`
- [Runtime stack](https://github.com/projectsprav/xho/blob/main/docker-compose.yml): docker compose · Containerized local and production-like deployment with nginx, promtail, and signoz · `docker-compose.yml`

## Connections

- Mobile app → API server: patient API · Mobile screens and hooks read/write core health data
- Mobile app → Health sync: syncs data · Mobile collects native health signals for upload and sync
- Admin web → API server: same-origin API · Browser dashboards proxy requests to the backend
- Physician web → API server: clinical API · Physician workflows use the central API
- API server → HTTP routers: exposes · HTTP routes define the public application surface
- HTTP routers → Domain services: delegates · Endpoints hand off business logic to domain services
- Domain services → Protocol engine: builds plans · Clinical rules and evidence gating drive protocol generation
- Domain services → Data models: persists · Business workflows read and write domain entities
- Data models → Migrations: evolves schema · Model changes are tracked through Alembic history
- API server → Kafka pipeline: publishes events · API emits async events for downstream processing
- Kafka pipeline → Airflow DAGs: feeds jobs · Scheduled workflows consume or complement event-driven processing
- Airflow DAGs → API server: materializes insights · Recurring jobs update derived scores, alerts, and reminders
- Airflow DAGs → Data models: reads/writes · DAGs operate on the shared transactional store
- API server → Object storage: stores files · Uploads, reports, and photos are externalized from the database
- API server → Observability: emits telemetry · Middleware and metrics feed tracing and monitoring
- Runtime stack → API server: runs · Container stack launches the backend service
- Runtime stack → Admin web: runs · Container stack supports the main web app
- Runtime stack → Physician web: runs · Container stack supports the physician web app
- Runtime stack → Observability: includes · Deployment stack includes logging and monitoring components