ahmido
03b1beb616
## Summary - add the first multi-app workspace foundation with a new standalone Astro website under `apps/website` - introduce repo-root pnpm workspace orchestration and migrate the platform Node workflow from npm assumptions to pnpm - update root docs, editor or agent guidance, and workspace-focused smoke tests for the new platform plus website command model - add Spec 183 artifacts for spec, plan, research, contracts, quickstart, checklist, and tasks ## Verification - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/WorkspaceFoundation` - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - `corepack pnpm build:website` - integrated-browser smoke: verified `http://localhost/up`, `http://localhost/admin/login`, and `http://localhost:4321/` including website anchor navigation and combined root dev flow ## Notes - branch: `183-website-workspace-foundation` - commit: `6d41618d` - root command model now covers `dev:platform`, `dev:website`, `dev`, `build:platform`, and `build:website` - website port override documentation is included in the command contract, quickstart, and README Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #214
80 lines
6.8 KiB
Markdown
80 lines
6.8 KiB
Markdown
**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.
|
|
- **Workspace model:** repo-root pnpm workspace orchestration, Laravel platform in `apps/platform`, and standalone Astro website in `apps/website`.
|
|
|
|
**Tech Stack & Key Libraries:**
|
|
- **Backend:** Laravel 12 (PHP 8.4)
|
|
- **Admin UI:** Filament v5
|
|
- **Realtime/UI:** Livewire v4
|
|
- **Public website:** Astro v6
|
|
- **Workspace tooling:** pnpm 10 workspaces
|
|
- **Testing:** Pest v4, PHPUnit
|
|
- **Local dev:** Laravel Sail (Docker)
|
|
- **Styling/tooling:** Tailwind v4, Vite
|
|
|
|
**Repository Layout (high level):**
|
|
- `apps/platform/` — Laravel runtime, Filament panels, tests, Vite assets, and app-local PHP or Node manifests
|
|
- `apps/website/` — Astro website source, public assets, and static build output
|
|
- `package.json` + `pnpm-workspace.yaml` — official root workspace command model
|
|
- `scripts/` — root compatibility helpers such as `platform-sail`
|
|
- `specs/` — SpecKit feature specs (feature-by-feature directories, e.g. `011-restore-run-wizard`)
|
|
- `docs/` — architecture, rollout, and handover notes
|
|
- `tests/` — Pest tests (Feature / Unit)
|
|
- `apps/platform/resources/`, `apps/platform/routes/`, `apps/platform/database/` — Laravel application structure
|
|
|
|
**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):**
|
|
- Root workspace entry: `package.json`, `pnpm-workspace.yaml`, and `README.md`
|
|
- Restore flows: `apps/platform/app/Services/Intune/RestoreService.php`, `apps/platform/app/Services/Intune/RestoreRiskChecker.php`, `apps/platform/app/Services/Intune/RestoreDiffGenerator.php`
|
|
- Graph contracts: `apps/platform/config/graph_contracts.php` and `apps/platform/app/Services/Graph/GraphContractRegistry.php`
|
|
- Policy type catalog and UX metadata: `apps/platform/config/tenantpilot.php` and `specs/*` for feature intentions
|
|
- Filament UI: `apps/platform/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.
|