TenantAtlas/specs/051-entra-group-directory-cache/quickstart.md

Quickstart: Entra Group Directory Cache (Groups v1)

Goal

Populate a tenant-scoped cache of Entra ID groups (metadata only) via background sync runs, enabling safe UI rendering without live directory calls.

Prerequisites

• Graph integration configured (client credentials / app-only)
• Database migrated (feature migrations applied)
• Queue worker running for jobs (required for sync)
• Scheduler/cron running for periodic sync (optional, if enabled)

Local (Sail) quick commands

• Bring containers up: ./vendor/bin/sail up -d
• Run migrations: ./vendor/bin/sail artisan migrate
• Run the queue worker (separate terminal): ./vendor/bin/sail artisan queue:work
• Run the scheduler loop (separate terminal, optional): ./vendor/bin/sail artisan schedule:work

Operator workflow (manual)

1. Switch into a tenant workspace.
2. Go to Directory → Group Sync Runs.
3. Click Sync Groups (creates/reuses a run and dispatches a background job).
4. Open the run and wait for status to complete.
5. Go to Directory → Groups and confirm list/search/detail are populated from the cache.

Notes

• Search is cached-only and typically requires at least 2 characters.
• If the cache is empty, the Groups list will be empty until a sync completes.

Scheduled sync

• Ensure the scheduler is running (cron or schedule:work).
• Verify Directory → Group Sync Runs shows runs with empty Initiator (scheduled).
• The dispatcher command is tenantpilot:directory-groups:dispatch (configured to run every minute).

Verification

• UI pages that show group IDs render using cached data only.
• Unresolved IDs show a clear fallback.
• Groups not seen for >90 days are eventually purged.

Suggested validation checks

• ./vendor/bin/sail artisan migrate:status | grep entra_group
• ./vendor/bin/sail artisan schedule:list | grep directory-groups