PROJECT_SUMMARY.md

@@ -0,0 +1,72 @@
+**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.