Architecture

Architecture

PumpSync is split across a frontend-only iOS repository and a backend-only ASP.NET Core repository. The iOS app owns Apple-platform behavior and App Store assets. The backend owns service tokens, Tandem Source integration, sample normalization, subscription verification, self-hosting, demo mode, storage, and deployment.

Repository Boundary

Repository	Owns	Does not own
eslutz/PumpSync	SwiftUI iOS app, HealthKit writes, StoreKit subscription UI, App Store/TestFlight metadata, screenshots, app legal docs, iOS CI.	Backend API projects, Dockerfiles, container publishing, Azure infrastructure, backend deploy workflows, data deletion tooling.
eslutz/PumpSync-Backend / PumpSync.backend	ASP.NET Core API, Docker/Compose self-hosting, Azure Container Apps infrastructure, backend deploy workflows, data deletion tooling, hosted/demo operations.	iOS app UI, App Store screenshots, iOS project generation, iOS signing.

If an iOS change requires backend behavior or URL changes, update the backend repository first, then update project.yml and iOS docs with the resulting base URL.

iOS App

The iOS app is a SwiftUI application generated from project.yml with XcodeGen. The current source layout is:

PumpSync/
  Resources/       Info.plist, asset catalog, generated app metadata
  Sources/App/     App entry point, app services, diagnostics, shortcuts
  Sources/Auth/    Backend session and access-token handling
  Sources/Health/  HealthKit permission and sample writes
  Sources/Networking/
                   API models and PumpSync backend client
  Sources/Storage/ Keychain, sync metadata, imported-sample ledger
  Sources/Sync/    Sync coordinator, initial import range, background scheduling
  Sources/Tandem/  Tandem credential form/store/value types
  Sources/UI/      Onboarding, sync, settings, privacy, developer/support views

The app uses:

• SwiftUI for UI.
• HealthKit for insulin and carbohydrate writes.
• StoreKit for PumpSync subscription purchase and restore.
• Keychain for Tandem credentials.
• BackgroundTasks for daily sync scheduling.
• MetricKit, OSLog, and local diagnostics for support-safe diagnostics.
• App Intents for shortcuts.

Backend API

The backend is a plain ASP.NET Core API packaged as a container image. The current source layout is:

src/
  PumpSync.Api/            HTTP API host
  PumpSync.ApiContracts/   Request/response contracts
  PumpSync.Application/    Use cases, mapping, normalization, validation, security
  PumpSync.Domain/         Domain models for auth, billing, samples, sync, Tandem, users
  PumpSync.Infrastructure/ Storage, Tandem, synthetic demo, App Store, secrets, options
tests/
  PumpSync.Tests/
tools/
  PumpSync.DataDeletionRequest/
infra/
  bicep/
  environments/

Hosted service, self-hosting, and synthetic demo use the same API contracts and normalization pipeline.

Sync Flow

1. The app obtains a PumpSync service token through subscription session creation or self-host session creation.
2. The user saves Tandem credentials in the iOS Keychain.
3. During validate or sync, the app sends Tandem credentials — plus the device's IANA time zone, which the backend uses to anchor Tandem's pump-local timestamps — to the configured backend over HTTPS.
4. The backend authenticates with Tandem Source, or with the synthetic demo authenticator in demo mode.
5. The backend clamps the requested history window to Tandem's ~14-day availability boundary and reports the effective window in the response; the app surfaces a data-gap notice when the clamp discarded part of the requested range.
6. The backend normalizes Tandem pump events into insulin and carbohydrate samples with window-independent external ids (open trailing basal segments are withheld until a later pump event closes them) and returns them to the app.
7. The app writes authorized samples to Apple Health, records only the confirmed writes in its duplicate-prevention ledger, and advances its sync watermark from the server-reported effective window.
8. The app and backend discard raw Tandem events and normalized samples after the response/write path completes.

Hosted Routing

project.yml defines hosted API base URLs. Public documentation should describe the environment split without publishing live hosted endpoint values.

Purpose	Scheme	Configuration	Hosted environment
Local Xcode install	PumpSync	Debug	Nonprod hosted API
TestFlight upload	PumpSync Beta	Beta	Nonprod hosted API
App Store release	PumpSync	Release	Production hosted API

Debug and Beta use Apple's sandbox StoreKit environment. Release uses the production App Store transaction environment.

Storage

Hosted mode uses Azure Table Storage for operational state:

• Subscription entitlements.
• Installations and installation lookups.
• Sync attempts.
• Rate-limit buckets.
• App Store notification idempotency.
• Redacted audit/data-deletion events.

Self-host and demo mode use SQLite by default. Self-host users are responsible for backing up and protecting their SQLite database and TLS/reverse-proxy credentials.