Google Calendar sync for inspectors (Attik inspections & events)

Objective

• Let inspector users see their Attik schedule—confirmed inspections and relevant calendar events—on Google Calendar so they can plan the day in one place alongside personal and other-work calendars.
• Ensure companies can cap how far ahead that mirrored schedule may extend on Google Calendar, because some organizations are stricter than others about how much future booking visibility inspectors should have outside Attik.
• Provide a path that is trustworthy (right times, right timezone, clear titles), maintainable for the team, and understandable for users (how to connect, what syncs, how often it updates, and what the company policy is).
• Preserve the broader product context that users want to connect a calendar account, choose what should sync, and keep updates aligned between Attik and the connected calendar to avoid double entry and stale schedules.

Background

• Inspectors already live in Attik for dispatch and in Google Calendar for everything else; copying or cross-checking between the two is easy to get wrong under load.
• In the May 14 NE Region / RJ discussion, inspectors specifically asked whether they could sync their Attik calendar to Google Calendar, confirming active user demand for this capability.
• The transcript also captured rollout urgency: the request came up in the context of preparing inspectors to adopt Attik and reduce friction during launch.
• Attik already models inspections and calendar-style items (blocks, holds, vacations, recurring patterns, etc.) in the product; Google Calendar is the natural mirror for personal devices.
• Not all companies want the same future visibility. Some are comfortable with inspectors seeing a long lookahead on personal Google calendars; others want to limit “what could be booked” or sensitive future work from appearing off-platform. Google Calendar sync must respect a company-defined visibility window so policy stays consistent across inspectors.
• Users are asking for a simple way to link a calendar account, define what syncs, and trust that appointment and schedule changes stay aligned across systems without manual re-entry.
• This matters not only for inspectors, but also for broader scheduling workflows involving office staff and managers, even if v1 scope stays focused on inspector-facing Google Calendar sync.
• Google API access patterns exist in the codebase (for example Calendar-related OAuth scopes are centralized in attik-backend/src/util/functions/google/googleapiAuth.ts); this work wires product behavior and user-facing connection flows on top of that foundation rather than inventing auth from scratch.
• Spectora and other integrations may expose their own calendar identifiers elsewhere; scope here is Attik-native schedule data for the signed-in inspector unless product explicitly expands.

Scope

Product (capture before build)

• Company policy: Google Calendar lookahead / sync horizon
• Company admins configure a maximum horizon for what may appear on Google Calendar (examples to decide in UX: rolling N days from today, end of current week, end of month, or a fixed N months cap).
• Clarify whether the cap applies to inspections only, all mirrored event types, or different caps per type (if needed later).
• Define behavior when an item starts inside the window but ends outside it (include whole event vs clip vs exclude).
• Define behavior when the company tightens the policy: events already written to Google that now fall outside the new window should be removed or hidden on next sync.
• Which rows count as “on my Google Calendar” beyond the horizon rule: confirmed inspections only, or also tentative holds, office blocks, equipment moves, PTO, and multi-day items?
• What choices users have over what should sync: inspections only, broader schedule items, or other calendar object types.
• Read-only feed vs two-way sync: is Google a display mirror (recommended default to reduce conflict risk) or must edits in Google write back to Attik?
• Per-user vs per-company: connection is per inspector account, with company-level policy (horizon + enable/disable) and audit expectations.
• Privacy: what appears in event titles, locations, and descriptions for addresses and client names on a personal Google account—within the allowed horizon.
• Connection UX should make it clear how to connect an account, what the integration supports in v1, and what controls exist over synced content.

Backend

• Enforce the company horizon server-side when building the inspector agenda for Google (never rely on the client alone). Log or metric when items are filtered by policy for supportability.
• Stable representation of “inspector’s agenda” for a date range: reuse existing inspection and event query patterns rather than duplicating business rules in a one-off exporter—then apply the company visibility window as a final filter.
• If using Google Calendar API: authenticated push or incremental sync, token storage, refresh, revocation, and rate-limit aware batching; if using subscribe-by-URL (ICS): signed secret URLs, rotation, and cache headers.
• Job to refresh or notify on meaningful changes (reschedule, reassignment, cancel, company policy change) so Google does not stay stale or out of policy.

Frontend

• Company settings: admin UI for Google Calendar sync horizon (and related toggles), with clear copy that this limits Google visibility, not necessarily the full Attik calendar (unless product decides otherwise—call out in Open questions).
• Inspector settings: connect Google, status, disconnect, and a short note showing the effective horizon (“Your company shows up to … on Google Calendar”).
• Clear error and re-auth flows when Google tokens expire or scopes are insufficient.
• UI should also clarify what syncs and whether the integration is one-way or two-way.

Mobile

• Decision needed: whether mobile needs a deep link to the same connect flow or relies on web-only setup for v1.

References

• attik-backend/src/util/functions/google/googleapiAuth.ts (existing Google OAuth scope helpers, including Calendar scopes)
• Dispatch and calendar UI patterns under attik-frontend/src/app/tools/dispatch/ and attik-frontend/src/components/calendar/ (source of truth for what users expect to see mirrored)
• Attik Mobile schedule surfaces if “inspectors on phones” must see connection status in-app in v1

Open questions (Decision needed)

• Mechanism: Google Calendar API push vs ICS subscription vs hybrid (ICS for v1, API later).
• Latency: near-real-time vs acceptable delay (e.g. 5–15 minutes) for v1.
• Horizon semantics: default for new companies; min/max bounds Attik allows; whether tightening the window should also affect in-app inspector calendar or only the Google mirror.
• Multi-inspector jobs: how a single inspection appears when several inspectors are assigned.
• Whether this issue should remain explicitly Google-only for implementation while serving as the current home for the broader calendar-connection problem statement.