google-calendar-sync

Google Calendar Sync is a self-hosted service that keeps a destination calendar synchronized as a projection of a source calendar. Each rule observes exactly one source calendar and manages exactly one destination calendar, and source and destination may belong to different Google identities. The project is explicitly labeled pre-alpha: the architecture, sync engine, authenticated API, Google adapter and Web UI form a working first vertical slice, but live-account endurance testing and a production-readiness review are not complete, so test calendars and backups are advised. Key design points described in the README: - Directional rules: one source, one destination, with source-authoritative behavior. Destination edits, missing projections and source cancellations are repaired during sync and reconciliation. - Privacy defaults: new rules default to a Busy projection; detail copying is opt-in and never copies attendees, organizer identity, conferencing data, attachments or invitations. - Safe activation: a rule must pass a side-effect-free preview before it can be enabled. - Self-contained deployment: SQLite, scheduling, API and Web UI run as one lightweight service, shipped as a Docker image and Compose service for linux/amd64 and linux/arm64. - No telemetry: a functional installation communicates only with the Google APIs needed for synchronization and any notification endpoint the operator configures. Capabilities listed include timed and all-day events, recurring series, single-occurrence changes and cancellations; busy-only or detail-copy policies with per-rule all-day inclusion; incremental polling every five minutes plus manual Sync Now; a daily full reconciliation pass plus Reconcile Now with drift reporting; loop prevention via private managed-origin metadata; stable operation keys, cursor-last persistence, retry backoff and isolated rule failures; an authenticated Activity view with deduplication and optional SMTP or webhook incident delivery; one local administrator password with encrypted Google OAuth credentials; and light/dark themes. Setup requires a Google Cloud project with the Calendar API enabled, an OAuth 2.0 Web application client, and the exact redirect URI http://localhost:8000/api/v1/oauth/google/callback. Local secrets are configured through a .env file, including a 256-bit master key that encrypts stored Google credentials with AES-256-GCM. The README notes that losing the master key makes connected account credentials unreadable, and that LAN-host deployments need special handling because Google rejects plain-HTTP redirect URIs other than localhost. Synchronization behavior: the first run reads source events ending no earlier than 30 days before the run, observes the destination, and records Google's incremental tokens for both endpoints. Later runs consume both change feeds, so destination-only edits or deletions are repaired without full rescans. For each relevant source event the domain chooses Create, Update, Delete, Ignore or Conflict; ambiguous identity or ownership is not guessed. Cursors advance only after a batch fully succeeds, and provider writes carry stable operation keys so retries do not duplicate projections. Privacy and security notes: event titles, descriptions and locations are processed in memory and not stored in SQLite or audit entries; mappings retain provider IDs, revisions and a non-reversible fingerprint; disconnecting an account discards stored credentials without deleting rules, mappings or managed projections; Google writes use sendUpdates=none; the Web UI and operational API require the local administrator session, while /health stays public and minimal. Architecture is a modular monolith with ports-and-adapters boundaries; the synchronization domain has no FastAPI, SQLite, Google SDK, React, OAuth or Docker dependencies. Backend development uses Python 3.12 and FastAPI, frontend uses Node.js 22+, React, TypeScript, Vite and Tailwind CSS. Quality checks include ruff, mypy, pytest with an 80% coverage floor, frontend typecheck/lint/test/build, and multi-platform Docker builds. Google Calendar is the only provider in the initial release; Outlook and CalDAV are described as architectural possibilities, not supported features. The project targets version 0.1.0 under the MIT License.