TenantAtlas/specs/051-entra-group-directory-cache/data-model.md

Data Model: Entra Group Directory Cache (Groups v1)

Entities

EntraGroup

Represents a cached directory group for a single tenant (metadata only).

Fields (conceptual)

• id (internal)
• tenant_id (FK)
• entra_group_id (GUID/string; external stable identifier)
• display_name (string)
• group_type (enum/string, derived; e.g., Security, Microsoft365, Unknown)
• security_enabled (bool, nullable)
• mail_enabled (bool, nullable)
• group_types (array/JSONB, nullable)
• last_seen_at (timestamp)
• last_seen_run_id (FK to sync run, optional)
• created_at, updated_at

Constraints & indexes

• Unique: (tenant_id, entra_group_id)
• Index: (tenant_id, display_name) for search
• Index: (tenant_id, last_seen_at) for stale/retention filtering

EntraGroupSyncRun

Append-only record for one sync attempt.

Fields (conceptual)

• id
• tenant_id (FK)
• initiated_by_user_id (FK nullable for scheduled)
• selection_key (string; deterministic for Groups v1 per tenant)
• status (enum: pending, running, succeeded, failed)
• started_at, finished_at
• counters: observed_count, upserted_count, error_count
• error_category (string/enum; e.g., permission, throttling, transient, unknown)
• error_summary (safe string)
• created_at, updated_at

Constraints & indexes

• Index: (tenant_id, created_at)
• Index: (tenant_id, status)
• Optional unique/idempotency: (tenant_id, selection_key, status in active) in code using locks.

Relationships

• Tenant 1 → N EntraGroup
• Tenant 1 → N EntraGroupSyncRun
• EntraGroupSyncRun 1 → N EntraGroup (via last_seen_run_id, optional)

State transitions

• pending → running → succeeded | failed

Retention

• Purge rule: delete EntraGroup where last_seen_at < now - 90 days.
• Stale classification: stale if last_seen_at < now - N days (default N = 30).