trails/CONTEXT.md

trails.cool domain glossary

This file names the domain concepts used in the codebase. New terms get added here as decisions crystallize during architecture work; the goal is that one concept has one name everywhere — specs, code, conversations.

If you're naming a new module, a new column, or a new UI surface, look here first. If the term you need isn't here, propose it (don't invent a synonym).

---

Connected Services

The user-facing surface for linking external accounts and devices to a Journal account. Spec: openspec/specs/connected-services/.

ConnectedService

A single linked external account or device, owned by one user. Stored in the connected_services table (renamed from sync_connections). At most one row per (user_id, provider).

provider

String identifier for the external system: wahoo, komoot, apple-health, and future coros, garmin, strava. The provider determines the credential_kind and which capabilities (import / push / webhook) the connection has, via the provider's manifest.

credential kind

Discriminator on connected_services describing the credential shape stored in the credentials JSONB blob. Three kinds today:

• oauth — OAuth2 access token, refresh token, expiry. Wahoo, and the expected shape for Coros / Garmin / Strava.
• web-login — email + encrypted password + session jar. Komoot. No official API; we authenticate against the provider's normal web login and reuse the resulting session cookies. Refresh = re-login. Web-login breakage (form changes, captchas, password rotation) surfaces at the import layer, not at the credential layer.
• device — no remote credential. Apple Health (and future Health Connect on Android). Data arrives via authenticated mobile API uploads, not server-initiated pulls. The credentials blob is empty; the connection exists so the UI can show "Apple Health is paired."

Credential kind is determined by the provider via its manifest, but stored explicitly on the row so queries don't need to join the manifest.

granted_scopes

Column on connected_services, populated only for credential_kind = oauth, NULL otherwise. Lists the OAuth scopes the user actually granted (e.g. routes_write). Feature gates query this column directly; missing a scope triggers re-authorization.

provider_user_id

The external service's identifier for the user. Used to route incoming webhooks to the right local user. Nullable (Apple Health has none in the remote-id sense).

CredentialAdapter

Per-kind module that knows how to maintain credentials of that kind:

• oauth.refresh(creds) → creds | NeedsRelink
• web-login.relogin(creds) → creds | InvalidCredentials
• device — no-op

Adapters do not import data, push routes, or handle webhooks. They only own the credential lifecycle.

ConnectedServiceManager

The deep module callers see. Owns:

• link(userId, provider, credentials) / unlink(serviceId)
• withFreshCredentials(serviceId, fn) — refreshes via the right CredentialAdapter if expired, calls fn(creds), marks the connection needs_relink if refresh fails.
• markNeedsRelink(serviceId, reason) — called by import / push / webhook layers when they observe a credential failure (e.g. Komoot web-login fails, Wahoo returns 401 after a successful refresh).

Per-provider importers / pushers / webhook handlers always go through withFreshCredentials — they never read the credentials JSONB directly.

provider manifest

Per-provider declaration co-located with the provider's code (providers/wahoo/manifest.ts, etc.). Declares:

• the provider's credential_kind
• which capabilities the provider implements (import? push? webhook?)
• references to the per-capability modules

A small providers/registry.ts imports each manifest. Adding a provider is one new directory plus one import line.

Sync Capabilities

Three orthogonal capabilities a provider may implement. Each is its own seam when there are ≥2 adapters; today most are single-adapter and held to a named shape so the second adapter doesn't reshape the interface.

Importer

Pulls workouts / activities from the external service into the Journal. Wahoo (OAuth pull), Komoot (web-login pull), Apple Health (mobile-pushed) all implement this, with very different mechanics. Dedup via sync_imports.

RoutePusher

Pushes a Journal route out to the external service. One adapter today (Wahoo); the seam exists so Coros / Garmin / Strava push won't reshape it.

The public seam is pushRoute(connectedService, route) → {remoteId, version}. Provider-specific concerns — FIT Course conversion, the route:<id> external_id convention, the PUT→POST-on-404 fallback — are handled internally by the adapter, not exposed on the seam. Idempotency is tracked via sync_pushes.

WebhookReceiver

Handles inbound webhooks. Today: Wahoo workout-published. Routes incoming webhooks to the right user via provider_user_id. Unknown provider_user_id returns 200 and is silently dropped (no leak).

Storage tables

• connected_services — user ↔ provider links (renamed from sync_connections).
• sync_imports — dedup cache for imported workouts, keyed by (user_id, provider, workout_id).
• sync_pushes — push state per (user_id, route_id, provider) → remote_id, last_pushed_version.