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.