Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.0.0
Last Updated: 2026-04-28
Spec: PF-101 Google Workspace Integration
Status: Planned
Constitution Reference: Section 1.3 (Integration Patterns), Section 4.2 (PHI/PII Handling), Section 5.7 (RLS)

​
Overview

PF-101 defines the tenant-level Google Workspace connector for Admin SDK Directory, Gmail, Calendar/Meet, Drive, Chat, License Manager, and Reports APIs. It consolidates the existing Gmail and Calendar paths into a governed PF integration layer, while HR, CE, PF-10, PF-11, and PF-86 remain consumers.

​
Integration Points

ConsumerPatternContract
HR-01Eventhr_employee_created and hr_employee_terminated drive Workspace provisioning and offboarding.
HR-01API / event enhancementEmployee update sync uses an HR-01-approved update event or read-only lookup; no direct PF import from HR core code.
CE-07Platform layerCE email flows consume the PF Gmail sender wrapper.
CE-21Platform layerCE scheduling consumes PF Calendar/Meet wrappers.
PF-10Platform layer / edgeApproved notification templates can route to Gmail or Google Chat.
PF-11Platform layerDrive mappings support external links/export/import while PF-11 remains canonical document storage.
PF-86Platform layerEmail signatures render before Gmail send.
PF-35Connector registryGoogle Workspace appears in Integration Hub status and health surfaces.
PF-76Credential referencePF-101 stores only credential IDs for service account, OAuth, and webhook material.

​
Platform Layer Contract

Planned package: src/platform/integrations/google-workspace/
APIPurposeNotes
useGoogleWorkspaceConnection()Load current org connector state.Query key includes organization_id; staleTime 5 minutes, gcTime 10 minutes.
useGoogleWorkspaceConnectionMutation()Create/update connector metadata.All mutations enforce organization_id.
useGoogleWorkspaceCapabilityHealth()Load Directory/Gmail/Calendar/Drive/Chat/Licensing/Reports status.Redacted health details only.
sendGoogleWorkspaceEmail()Shared Gmail send wrapper.Applies sender allowlist, BAA gate, PF-86 signature, and redacted audit.
queryGoogleFreeBusy()Calendar free/busy wrapper.Batches requests and handles partial failures.
createGoogleCalendarEvent()Calendar/Meet event creation.Redacts PHI by default and generates unique Meet request IDs.
previewGoogleGroupSync()Group membership delta preview.Required before bulk apply.

​
Event Contracts

HR-01 publisher status (confirmed 2026-04-28): hr_employee_created, hr_employee_assigned_to_site, and hr_employee_terminated are documented as published by HR-01 in HR-01-employee-directory-INTEGRATION.md §Events. The canonical-name registry rows for hr_employee_created and hr_employee_assigned_to_site are added to EVENT_CONTRACTS.md §HR Core Events alongside the existing hr_employee_terminated row. PF-76 disambiguation: “PF-76” in this document = PF-76 Credential Vault (specs/pf/specs/PF-76-credential-vault.md), not PF-76 React 19 Migration. Cross-core column comment: Migrations creating pf_google_workspace_user_links.employee_id MUST add COMMENT ON COLUMN ... IS 'Cross-core reference to hr_employees.id (HR core); no FK; validated at application layer.' per database-patterns.

​
Consumed: hr_employee_created

Publisher: HR-01
Subscriber: PF-101
Purpose: Provision or link a Google Workspace user when tenant policy enables account provisioning. Minimum payload:
FieldTypeNotes
event_typestringhr_employee_created
event_versionstringStart at 1.0.
organization_iduuidTenant scope.
employee_iduuidHR employee UUID; stored as UUID reference without FK.
profile_iduuidOptional user profile link.
department_iduuidOptional mapping input.
position_iduuidOptional mapping input.
hire_datetimestampProvisioning policy input.
correlation_idstringRequired for audit trace.
timestamptimestamptzEvent time.

​
Consumed: hr_employee_assigned_to_site

Publisher: HR-01
Subscriber: PF-101
Purpose: Reconcile site-based group, org unit, Drive, Calendar resource, or Chat mappings when a tenant explicitly enables site mapping sync. Minimum payload:
FieldTypeNotes
event_typestringhr_employee_assigned_to_site
event_versionstringStart at 1.0.
organization_iduuidTenant scope.
employee_iduuidHR employee UUID.
site_iduuidPF site UUID.
assignment_datetimestampMapping effective date.
rolestringOptional mapping input.
correlation_idstringRequired for audit trace.
timestamptimestamptzEvent time.

​
Consumed: hr_employee_terminated

Publisher: HR-01
Subscriber: PF-101
Purpose: Suspend/offboard linked Workspace user, revoke licenses, remove groups, and queue Drive transfer review. Minimum payload:
FieldTypeNotes
event_typestringhr_employee_terminated
event_versionstringStart at 1.0.
organization_iduuidTenant scope.
employee_iduuidHR employee UUID.
termination_datetimestampOffboarding policy input.
termination_reasonstringOptional; do not log verbatim if sensitive.
correlation_idstringRequired for audit trace.
timestamptimestamptzEvent time.

​
Published: pf_google_workspace_user_provisioned

Publisher: PF-101 Subscribers: PF-10, HR status consumers Purpose: Signal successful Workspace user provisioning without exposing secrets or PHI. Note: Subscribers requiring the email address must perform scoped lookups using google_user_id or profile_id.
FieldTypeNotes
event_typestringpf_google_workspace_user_provisioned
event_versionstring1.0
organization_iduuidTenant scope.
employee_iduuidOptional source reference.
profile_iduuidOptional source reference.
google_user_idstringProvider ID.
correlation_idstringRequired.
timestamptimestamptzEvent time.

​
Published: pf_google_workspace_connector_degraded

Publisher: PF-101
Subscribers: PF-10, PF-36
Purpose: Alert admins when credential, scope, quota, BAA gate, or sync health degrades.
FieldTypeNotes
event_typestringpf_google_workspace_connector_degraded
event_versionstringStart at 1.0.
organization_iduuidTenant scope.
connection_iduuidPF-101 connector.
capabilitystringdirectory, gmail, calendar, drive, chat, licensing, or reports.
reason_codestringSanitized machine code.
correlation_idstringRequired.
timestamptimestamptzEvent time.

​
Edge Function Contracts

FunctionAuthenticationPurpose
google-workspace-test-connectionJWT + pf.google_workspace.testValidate capability scopes and health.
google-workspace-directory-syncservice role / scheduledBatch Directory user/group/org unit sync.
google-workspace-provision-userevent consumer + service roleProvision/link one Workspace user.
google-workspace-offboard-userevent consumer + service roleSuspend user, revoke licenses, remove groups, queue Drive review.
google-workspace-gmail-sendJWT + sender policyShared Gmail sender path.
google-workspace-calendar-syncJWT/service roleCalendar/Meet event sync and CE wrapper support.
google-workspace-drive-syncJWT/service roleDrive metadata and mapping sync.
google-workspace-reports-ingestservice role / scheduledReports API audit ingestion.
google-workspace-chat-notifyservice role / PF-10Send approved notifications to Chat spaces.
All functions must use PF-76 credential retrieval, PF-42 rate limiting where applicable, sanitized errors, and correlation IDs. Tenant-scoping contract: Service-role edge functions (google-workspace-directory-sync, google-workspace-provision-user, google-workspace-offboard-user, google-workspace-calendar-sync, google-workspace-drive-sync, google-workspace-reports-ingest, google-workspace-chat-notify) MUST include explicit tenant-scoping filters on all queries against multi-tenant tables:
  • .eq('organization_id', organizationId) — REQUIRED on all multi-tenant table queries
  • .eq('connection_id', connectionId) — REQUIRED where applicable (connection-scoped resources)
Implementation MUST include validation steps to assert the presence of these filters in all multi-tenant table queries. Detailed API contracts (endpoint, request/response schemas, error cases, tenant-scoping requirements) are documented in API_CONTRACTS.md §PF-101.

​
Security and Compliance

  • No PHI-capable Gmail, Calendar, Drive, Chat, or Meet operation may run unless pf_google_workspace_connections.baa_attested_at is set and tenant policy enables the capability.
  • Raw Google credentials, service account keys, OAuth client secrets, refresh tokens, and Pub/Sub webhook secrets remain in PF-76 only.
  • Domain-wide delegation scopes are versioned, reviewed, and tested per capability.
  • Restricted Google OAuth scopes require verification/security-assessment status tracking before production use.
  • Chat messages, calendar titles, logs, cache keys, and telemetry must not contain PHI/PII.

​
Testing

  • Contract tests for each edge function with mocked Google API 200/401/403/429/5xx responses.
  • RLS tests for all PF-101 tables.
  • Integration tests for HR event consumption, Gmail send, Calendar free/busy/event, group sync preview, and Reports ingestion.
  • Manual setup wizard tests using non-PHI tenant data before production enablement.