Development

Repository layout

custom_components/apple_health_sync/   Home Assistant integration
ios/                                  SwiftUI app, Xcode project, Swift package
tests/                                pytest + iOS contract tests
docs/                                 this site and screenshots
scripts/                              payload simulator
.github/workflows/                    tests, lint, hassfest, iOS, docs

The integration domain stays apple_health_sync; Health Assist is the product name. The iOS bundle identifier is uk.co.thebillington.applehealthsync, and the app targets iPhone.

Home Assistant tests

python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements_test.txt
pytest
ruff check .
ruff format --check .

The suite covers webhook parsing, history validation, statistics metadata, config/options flows, QR data, dynamic sensors, state updates, diagnostics and contract alignment between the iOS catalog and the HA registry.

iOS build and tests

swift test --package-path ios/AppleHealthSyncCore

xcodebuild \
  -project ios/AppleHealthSync.xcodeproj \
  -scheme AppleHealthSync \
  -sdk iphonesimulator \
  CODE_SIGNING_ALLOWED=NO \
  build

Regenerate the Xcode project after editing ios/project.yml:

brew install xcodegen
cd ios && xcodegen generate

CI

• tests.yml: pytest.
• lint.yml: ruff.
• hassfest.yml: Home Assistant validation.
• ios.yml: Swift package tests and simulator build.
• docs.yml: MkDocs build and GitHub Pages deploy.

Production deployment

The author's Home Assistant instance is deployed through the separate thebillington/homelab repository. The energy Ansible role vendors this component and deploys it with a tagged task. Do not edit the live component directly.

For local development, use a disposable Home Assistant container on a non-production host:

docker run -d --name ha-health-assist-test \
  -p 8124:8123 \
  -v "$PWD/custom_components/apple_health_sync:/config/custom_components/apple_health_sync:ro" \
  ghcr.io/home-assistant/home-assistant:stable

Documentation site

pip install -r requirements-docs.txt
mkdocs serve
mkdocs build --strict

The custom domain is healthassist.thebillington.co.uk; the CNAME lives in docs/CNAME. GitHub Pages serves the site from the Actions workflow. DNS must point the subdomain at GitHub Pages. If you use a proxy/Caddy instead, add the corresponding DNS record and site block in the homelab repo.

Brand assets and screenshots

The app icon is generated by:

python3 ios/scripts/make_icon.py

Marketing screenshots are generated with Open Screenshot Generator (osg) on the homelab dev container. The OSG project/checkouts are environment-specific; the final PNGs can be committed under docs/images/.

Known OSG limitations on the dev container:

• No MP4 preview videos (Chrome for Testing has no proprietary codecs).
• WebGL uses SwiftShader; 3D device frames are not identical to a real GPU.
• The CLI needs the pinned Node 20 under /opt/node20; use /usr/local/bin/osg rather than a system npx.

Release checklist

1. Update manifest.json version and iOS MARKETING_VERSION.
2. Run pytest, ruff, hassfest, Swift tests, simulator/device builds.
3. Update the vendored homelab component and deploy it.
4. Push main, tag a release and publish release notes.
5. Confirm the docs workflow and GitHub Pages deployment.