TenantAtlas/PROJECT_SUMMARY.md

TenantPilot / TenantAtlas — Project Summary

---

Overview:

• Purpose: Intune management tool (backup, restore, policy versioning, safe change management) built with Laravel + Filament.
• Primary goals: policy version control (diff/history/rollback), reliable backup & restore of Microsoft Intune configuration, admin-focused productivity features, auditability and least-privilege operations.

Tech Stack & Key Libraries:

• Backend: Laravel 12 (PHP 8.4)
• Admin UI: Filament v4
• Realtime/UI: Livewire v3
• Testing: Pest v4, PHPUnit
• Local dev: Laravel Sail (Docker)
• Styling/tooling: Tailwind v4, Vite

Repository Layout (high level):

• app/ — application code (Services, Models, Filament resources, Livewire components)
• config/ — runtime configuration (important: tenantpilot.php, graph_contracts.php)
• specs/ — SpecKit feature specs (feature-by-feature directories, e.g. 011-restore-run-wizard)
• tests/ — Pest tests (Feature / Unit)
• resources/, routes/, database/ — standard Laravel layout

Core Features (implemented / status):

• Policy Backup & Versioning: implemented — captures immutable snapshots (JSONB), tracks metadata (tenant, type, created_by, timestamps). (See app/Services/Intune/*, database/migrations.)
• Restore Preview (dry-run) / Restore Wizard: implemented — preview/dry-run mode that validates snapshots and highlights conflicts and risks. Feature tracked in specs/011-restore-run-wizard and Filament UI resources. Recent fixes improved OData @odata.type handling so derived Graph types validate correctly.
• Assignments & Foundation Mappings: implemented — mapping and selective restore of assignments, scope tags, and assignment filters (AssignmentRestoreService, FoundationMappingService).
• Settings Catalog / Configuration Policies: implemented — Settings Catalog and related configuration policy flows (settingsCatalogPolicy, endpointSecurityPolicy, securityBaselinePolicy) with subresource hydration for settings.
• Windows Update Profiles: implemented — Windows Update Rings + Feature/Quality/Driver update profiles (windowsUpdateRing, windowsFeatureUpdateProfile, etc.).
• Endpoint Security + App Management: implemented — Endpoint Security Intents/Policies, App Protection (MAM), Managed App Configurations, mobile app metadata capture.
• Scripts & Autopilot: implemented — device management scripts, proactive remediations, Autopilot profiles.
• Conditional Access & High-risk types: partially supported — conditionalAccessPolicy is backed up but marked preview-only for restore (see tenantpilot.supported_policy_types).

Policy Type Restore/Backup Surface (from config/tenantpilot.php):

• Restore enabled (full backup & restore): many configuration, compliance, endpoint security, scripts, Autopilot, MAM types (examples: deviceConfiguration, groupPolicyConfiguration, settingsCatalogPolicy, deviceCompliancePolicy, appProtectionPolicy, endpointSecurityPolicy, deviceManagementScript, etc.)
• Restore preview-only (backup available but live restore disabled / preview only): conditionalAccessPolicy, deviceEnrollmentLimitConfiguration, deviceEnrollmentPlatformRestrictionsConfiguration, deviceEnrollmentNotificationConfiguration, enrollmentRestriction, securityBaselinePolicy.
• Backup metadata-only: mobileApp (apps captured as metadata only)

Graph Contract Registry & OData handling:

• Centralized contract registry in config/graph_contracts.php defines endpoints, allowed selects/expands, type_family (accepted @odata.type values), subresources, and CRUD paths per policy type.
• OData validation is used during preview/restore (see app/Support/Concerns/InteractsWithODataTypes.php). Recent work broadened type_family entries to accept derived Graph @odata.type values for several policy types to avoid false odata_mismatch failures.

Testing & Quality:

• Unit and feature tests exist (Pest). Recent adjustments ensure unit tests run with the Laravel TestCase/IOC container (fixes issues like Target class [config] does not exist).
• Code formatting via Laravel Pint is used in CI and local flows.

Specs & Process:

• Uses Spec Kit convention: each feature in specs/<NNN>-<slug>/ (spec.md, plan.md, tasks.md). Branching conventions documented in Agents.md/.specify.
• Default integration branch: dev. Feature branches are feat/<NNN>-<slug>.

Recent Notable Work (context):

• Fixed false @odata.type mismatch errors by updating graph_contracts type_family lists and adding unit tests (tests/Unit/ODataTypeValidationTest.php).
• Resolved merge conflicts between feat/011-restore-run-wizard and dev by merging origin/dev into a session branch and reconciling spec/test additions.
• Added Agents.md section for a “Solo + Copilot Workflow” and created a small chore/solo-copilot-workflow branch/PR for that documentation change.

Where to look first (entry points):

• Restore flows: app/Services/Intune/RestoreService.php, app/Services/Intune/RestoreRiskChecker.php, app/Services/Intune/RestoreDiffGenerator.php.
• Graph contracts: config/graph_contracts.php and app/Services/Graph/GraphContractRegistry.php.
• Policy type catalog and UX metadata: config/tenantpilot.php and specs/* for feature intentions.
• Filament UI: app/Filament/Resources/* (PolicyVersionResource, restore wizard pages).

Short list of known limitations / next work items:

• Convert more preview-only types to enabled where safe (requires implementation of restore flows and risk mitigation, e.g., Conditional Access, Enrollment subtypes, Security Baselines).
• Improve app restore for mobileApp beyond metadata-only (complex due to package/artifact handling).
• Add broader OData type families as Microsoft Graph evolves; consider automated discovery/updates to graph_contracts.
• Expand test coverage for edge-case restores (multi-tenant mapping, assignment conflicts, scope tag drift).

---

If you want, I can:

• open a PR that adds this file to dev (I can create a small chore/ branch and push it), or
• expand any section above into a more detailed README or developer onboarding doc.