57 lines
1.9 KiB
Markdown
57 lines
1.9 KiB
Markdown
# 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).
|