Self-hosted, multi-user nutrition analytics for Apple Health and YAZIO

Quick start | Apple Health | YAZIO sync | Production | Documentation

---

CaloGraph is a self-hosted, multi-user nutrition dashboard for Apple Health and YAZIO data. It combines daily nutrition, versioned budgets and targets, optional activity-calorie credits, trends, achievements, and data-quality views without moral judgment or external telemetry.

Warning

CaloGraph is under active development. Version 0.x releases may contain incomplete features, breaking changes, or migrations that require attention. Features and behavior may change between releases. Keep tested backups and review the changelog before updating.

Highlights

• Multi-user by design: each account has isolated imports, samples, targets, achievements, tokens and personal integrations.
• Versioned nutrition analytics: daily calories and macros, historically effective budgets and targets, trends, calendar and data-quality views.
• Activity-aware budgets: optional imported activity-calorie credits can increase the effective daily calorie budget without turning CaloGraph into a workout tracker.
• Portable data: ZIP export/import and separate CSV archive export are available; CSV import is not currently supported.
• Managed account lifecycle: the first administrator can be created through the browser, then further accounts are invitation-only with password, MFA and passkey options.

Future development

CaloGraph is actively evolving. Planned areas of development include:

• AI-assisted nutrition analysis: use structured nutrition, meal and food data for deeper, opt-in analysis beyond charts and daily aggregates.
• Modernized YAZIO integration: migrate the experimental direct YAZIO sync from the legacy exporter path to a CaloGraph-owned integration based on the newer community API and SDK.
• Richer Apple Health ingestion: explore additional nutrition and meal-level data where the available Apple Health export paths provide reliable metadata.
• Google Health integration: explore the Google Health API as an additional server-side source for health metrics, nutrition logs, meals and food data.

These are planned development directions, not compatibility guarantees or release commitments. External provider APIs and available data may change over time.

Multi-user by design

Run one instance for multiple accounts. Health samples, imports, target history, achievements, import tokens and each personal YAZIO connection are scoped to their owner. Administrators manage account metadata, lifecycle and one-time invitations; the administration UI does not expose another account’s nutrition values. The deployment operator controls the database, secrets and backups. See User management.

Data sources

Recommended: Health Auto Export

For ongoing iPhone transfer, Health Auto Export sends the HealthKit categories you authorize to your CaloGraph endpoint over HTTPS with an account-scoped import token. iOS may delay background exports; CaloGraph cannot bypass those platform restrictions. See Apple Health setup and the import API.

Historical Apple Health

Upload Apple Health’s export.xml or ZIP in CaloGraph. Apple Health often lacks reliable food, recipe and meal names, so CaloGraph analyzes daily nutrient totals rather than inventing meal detail.

Experimental YAZIO integration

File import and direct/scheduled sync use an undocumented provider interface and may stop after provider changes; Health Auto Export remains the recommended default. Scheduled credentials are encrypted and user-scoped. Enabling direct YAZIO sync deliberately communicates with YAZIO. CaloGraph is independent of and not endorsed by YAZIO; yazio-exporter is a separately maintained MIT-licensed dependency. See YAZIO sync and third-party notices.

Quick start (local/private)

Prerequisites: Docker Compose and Git. This example is for a loopback/private development instance, not an Internet-facing deployment.

git clone https://github.com/tarantila/CaloGraph.git
cd CaloGraph
cp .env.example .env
./scripts/init-secrets.sh
# Review .env; keep CALOGRAPH_PUBLIC_URL on the address you use

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
docker compose ps

Open http://localhost:8180. On an empty instance, the sign-in page offers one-time creation of the first administrator. The browser setup creates only the account; sign in to continue through the normal onboarding.

There is a CLI alternative available when needed:

docker compose exec backend python -m app.cli create-user

After initialization, further accounts are created only through Administration → Einladungen. See User management for lifecycle and recovery operations.

Production deployment

.env.example is for local/private development and must not be exposed through an Internet-facing proxy. Start production from .env.production.example, use the final HTTPS origin, keep INITIAL_ADMIN_SETUP_ENABLED=false unless a controlled first-run window is explicitly intended, and follow the production checklist. The reverse-proxy guide covers TLS and upload limits.

Privacy and security

CaloGraph ships no telemetry, analytics or CDN dependencies. Imported data is stored in the operator’s deployment. Direct YAZIO sync is an explicit outbound integration. Sessions, CSRF checks, trusted hosts/origins, password policy, rate limits and security events are part of the application boundary; review SECURITY.md and the security monitoring guide.

Account exports contain only the authenticated user’s data and exclude credentials, token hashes, sessions and other security material. The portable format is documented in Data export. It is not a database dump.

Architecture and data provenance

Adapters normalize source records for analytics while retaining source type, source name and source identifier with per-user deduplication. The same day imported from Apple Health and direct YAZIO is not deduplicated across source boundaries; choose one path for overlapping days. See architecture, data model and analytics definitions.

Apple Health / Health Auto Export / YAZIO
                 │
                 ▼
       account-scoped import adapters
                 │  source provenance + deduplication
                 ▼
       versioned targets and analytics API
                 │
                 ▼
          account-scoped dashboard

Operations and development

• Architecture
• User management
• Production operations
• Reverse proxy and TLS
• Backup and restore
• Security monitoring
• Threat model
• Supply-chain and image retention
• Data export and portable import
• Import API
• YAZIO synchronization

Backend development uses Python 3.14 and the project lockfile; frontend development uses the package lockfile. The repository CI workflow contains the supported checks. Do not use development defaults for a public deployment.

Limitations

• This is 0.x software; review migrations and maintain independent backups.
• There is no native iOS app and no server-side Apple Health/HealthKit iCloud retrieval. An authorized iPhone exporter is required for ongoing data, and iOS can delay background delivery.
• CaloGraph is not medical software and does not provide medical diagnosis or treatment.
• There is no CSV importer yet; CSV is currently an export format only.
• Overlapping Apple Health and YAZIO days are intentionally not cross-source deduplicated; provenance remains distinct.
• The undocumented YAZIO interface is experimental and may break.

Contributing

Before proposing changes, read the relevant architecture, security and data export documentation. Keep account isolation, source provenance and the non-medical boundary intact.

License and provenance

CaloGraph source is available under PolyForm Noncommercial 1.0.0. This is not an OSI-approved open-source license. Third-party components retain their own licenses; see THIRD_PARTY_NOTICES.md.

Brand assets

The wordmark and application logo in frontend/public/branding/ are project brand assets.