Skip to content

refactor: clarify google sync ownership#1711

Merged
Uarmagan merged 13 commits intomainfrom
refactor/google-sync-lifecycle
May 4, 2026
Merged

refactor: clarify google sync ownership#1711
Uarmagan merged 13 commits intomainfrom
refactor/google-sync-lifecycle

Conversation

@Uarmagan
Copy link
Copy Markdown
Contributor

@Uarmagan Uarmagan commented May 1, 2026

Summary

This PR continues the Google sync refactor by making the backend ownership easier to read from the file tree and service names. The main goal is to make it obvious which code owns Google auth, Google Calendar sync/import/repair, and Google webhook watches.

  • Renames the former Sync Channel area to Google Watch and moves watch setup, notification handling, refresh, cleanup, and maintenance under packages/backend/src/sync/services/watch.
  • Renames the former lifecycle service to Google Calendar Sync and moves import, incremental sync, initial setup, and repair under packages/backend/src/sync/services/google-calendar-sync.
  • Splits the ambiguous restart path into two explicit flows: repairGoogleCalendarSync for forced recovery and startGoogleCalendarSyncIfNeeded for metadata-aware startup.
  • Moves the Google Calendar API client out of auth-owned code into the sync-owned Google Calendar area, while keeping OAuth client ownership in auth.
  • Updates active docs and file maps so future work points at the new ownership model and uses the Google Watch vocabulary.

The public behavior is intended to stay the same; this is a readability and maintainability pass over the existing split. Google API field names like channelId remain unchanged where they are part of Google's watch protocol.

Why

The branch had already split one large sync service into smaller modules, but the resulting boundaries were still hard to follow: auth owned a Calendar client, "channel" meant a Google watch, and "lifecycle restart" covered both normal startup and forced repair. This PR makes those concepts line up with the domain language we actually use when debugging the system.

Validation

  • bun run type-check
  • Focused backend tests: 9 suites, 92 tests around Google auth, Google Calendar sync, Google Watch handling/maintenance, sync controller, user service, and user metadata service
  • Biome error check on the touched/new sync files
  • git diff --check
  • Stale-reference search for old channel/lifecycle service names in active backend code and docs

Note: full bun run lint is still blocked by the existing repo-wide lint backlog, not by this change.

Review Notes

Suggested review focus:

  • Whether the new service names make the Google sync flow easier to follow.
  • Whether repairGoogleCalendarSync vs. startGoogleCalendarSyncIfNeeded communicates the intended behavior clearly.
  • Whether Google Watch ownership now feels cohesive without adding another abstraction layer.
  • Whether the docs describe the new boundaries clearly enough for the next person working in this area.

@Uarmagan Uarmagan marked this pull request as ready for review May 4, 2026 20:26
@Uarmagan Uarmagan changed the title refactor: deepen google sync lifecycle modules refactor: clarify google sync ownership May 4, 2026
@Uarmagan Uarmagan merged commit 8fa7f60 into main May 4, 2026
9 checks passed
@Uarmagan Uarmagan deleted the refactor/google-sync-lifecycle branch May 4, 2026 22:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant