From fd6ca05ebc91f33c057a27af3866f946a7f5599c Mon Sep 17 00:00:00 2001 From: Oliver Kieselbach Date: Mon, 23 Feb 2026 21:52:11 +0100 Subject: [PATCH] Simplify README and remove outdated docs Replace verbose README with a concise overview and link to the official documentation at autopilotmonitor.com/docs. Remove CONTRIBUTING.md, QUICKSTART.md, docs/architecture.md, and docs/getting-started.md as the website docs supersede them. Co-Authored-By: Claude Sonnet 4.6 --- CONTRIBUTING.md | 251 -------------------------- QUICKSTART.md | 183 ------------------- README.md | 154 +--------------- docs/architecture.md | 389 ---------------------------------------- docs/getting-started.md | 246 ------------------------- 5 files changed, 6 insertions(+), 1217 deletions(-) delete mode 100644 CONTRIBUTING.md delete mode 100644 QUICKSTART.md delete mode 100644 docs/architecture.md delete mode 100644 docs/getting-started.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7de64ecf..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,251 +0,0 @@ -# Contributing to Autopilot Monitor - -Thank you for your interest in contributing to Autopilot Monitor! This document provides guidelines and instructions for contributing. - -## Code of Conduct - -Be respectful, professional, and constructive. We're all here to make Autopilot deployments better. - -## How Can I Contribute? - -### Reporting Bugs - -Before submitting a bug report: -1. Check existing GitHub issues -2. Verify you're using the latest version -3. Collect relevant logs and error messages - -**Good Bug Report Includes**: -- Clear description of the issue -- Steps to reproduce -- Expected vs actual behavior -- Environment details (OS version, .NET version, etc.) -- Relevant log excerpts -- Screenshots if applicable - -### Suggesting Features - -We love feature ideas! Before submitting: -1. Check if it's already been suggested -2. Consider if it fits the project scope -3. Think about implementation complexity - -**Good Feature Request Includes**: -- Clear description of the feature -- Use case / problem it solves -- Proposed solution (if you have one) -- Alternative approaches considered - -### Contributing Code - -#### Development Setup - -1. Fork the repository -2. Clone your fork -3. Follow the [Getting Started Guide](docs/getting-started.md) -4. Create a feature branch: `git checkout -b feature/my-feature` - -#### Coding Standards - -**C# / .NET** -- Follow Microsoft C# coding conventions -- Use meaningful variable and method names -- Add XML documentation comments for public APIs -- Keep methods focused and small (<50 lines preferred) -- Use async/await properly (don't block) - -**TypeScript / React** -- Use TypeScript for type safety -- Follow React best practices (hooks, functional components) -- Use meaningful component and variable names -- Keep components small and focused -- Extract reusable logic into custom hooks - -**PowerShell** -- Use approved verbs (Get-, Set-, New-, etc.) -- Add comment-based help for scripts -- Use meaningful parameter names -- Include error handling - -#### Code Review Process - -1. Ensure all tests pass -2. Update documentation if needed -3. Submit a pull request with: - - Clear title and description - - Reference to related issues - - Screenshots (if UI changes) -4. Address review feedback -5. Squash commits before merge (if requested) - -### Contributing Rules - -The **rule engine** (Phase 2+) is designed to be community-driven. You can contribute rules to help diagnose common issues. - -#### Rule Structure - -Rules are YAML files in the `rules/` directory: - -```yaml -id: NET-001 -title: "Proxy Authentication Required" -severity: high -category: network -version: 1.0 -author: "Your Name" -description: | - Detects when a proxy requires authentication but SYSTEM account cannot authenticate. - -conditions: - - signal: "event_407_detected" - source: "windows_events" - provider: "Microsoft-Windows-WinHttp" - event_id: 407 - minimum_occurrences: 1 - -evidence_selectors: - - type: "log_lines" - source: "ime_log" - pattern: "proxy|407|authentication" - context_lines: 3 - -explanation: | - The device is behind a proxy that requires authentication, but the SYSTEM - account (used during enrollment) cannot authenticate. - -remediation: - - "Configure proxy bypass for *.manage.microsoft.com" - - "Configure proxy bypass for *.microsoftonline.com" - - "Use PAC file with proper exclusions" - -related_docs: - - "https://learn.microsoft.com/en-us/mem/intune/enrollment/enrollment-autopilot" - -confidence_scoring: - base: 50 - factors: - - signal: "winhttp_proxy_configured" - weight: 20 - - signal: "enrollment_stalled_at_mdm" - weight: 30 -``` - -#### Submitting Rules - -1. Create a new YAML file in the appropriate `rules/` subdirectory -2. Follow the schema above -3. Test your rule against sample data -4. Submit a PR with: - - The rule file - - Test data (anonymized) - - Explanation of how to trigger this condition - -## Project Structure - -``` -Autopilot-Monitor/ -├── src/ -│ ├── Agent/ # Windows monitoring agent -│ ├── Backend/ # Azure Functions API -│ ├── Shared/ # Common models/contracts -│ └── Web/ # Next.js web UI -├── scripts/ -│ ├── Bootstrap/ # Intune deployment scripts -│ └── Deployment/ # Azure deployment scripts -├── rules/ # Community rule definitions -├── docs/ # Documentation -└── tests/ # Tests (to be added) -``` - -## Testing Guidelines - -### Unit Tests -- Test core logic in isolation -- Mock external dependencies -- Aim for >80% code coverage on critical paths - -### Integration Tests -- Test API endpoints with real Azure Storage Emulator -- Verify agent can upload to Functions -- Test error handling and retries - -### End-to-End Tests -- Test full enrollment simulation (when feasible) -- Verify UI displays data correctly -- Test troubleshooting workflows - -## Documentation - -When adding features, please update: -- **README.md** - If it affects setup or high-level description -- **docs/getting-started.md** - If it affects the getting started process -- **docs/architecture.md** - If it changes architecture -- **Inline code comments** - For complex logic -- **XML docs** - For public APIs - -## Git Workflow - -We use a simplified Git workflow: - -1. **main** branch - Stable, production-ready code -2. **feature/** branches - New features in development -3. **bugfix/** branches - Bug fixes -4. **hotfix/** branches - Critical production fixes - -### Commit Messages - -Use clear, descriptive commit messages: - -``` -[Component] Short description - -Longer explanation if needed. - -Fixes #123 -``` - -Examples: -- `[Agent] Add support for pre-provisioning scenarios` -- `[Web] Implement session detail page with timeline` -- `[Functions] Fix race condition in event ingestion` -- `[Docs] Update architecture diagram` - -## Release Process - -Releases follow semantic versioning (MAJOR.MINOR.PATCH): - -- **MAJOR**: Breaking changes -- **MINOR**: New features (backwards compatible) -- **PATCH**: Bug fixes - -### Release Checklist - -- [ ] All tests pass -- [ ] Documentation updated -- [ ] CHANGELOG.md updated -- [ ] Version numbers incremented -- [ ] Tag created: `vX.Y.Z` -- [ ] GitHub release published -- [ ] Deployment artifacts published - -## Getting Help - -- **Questions**: Open a GitHub Discussion -- **Bugs**: Open a GitHub Issue -- **Feature Ideas**: Open a GitHub Issue with "enhancement" label -- **Security Issues**: Email security@yourcompany.com (do NOT open public issue) - -## Recognition - -Contributors will be: -- Listed in CONTRIBUTORS.md -- Credited in release notes -- Mentioned in documentation for significant contributions - -## License - -By contributing, you agree that your contributions will be licensed under the MIT License. - -## Thank You! - -Your contributions make Autopilot Monitor better for everyone. Thank you for taking the time to contribute! diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 68eca2c4..00000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,183 +0,0 @@ -# Quick Start Guide - -Get Autopilot Monitor running in 10 minutes! - -## Prerequisites Check - -Before starting, ensure you have: -- [ ] Windows 10/11 -- [ ] .NET Framework 4.8 SDK -- [ ] .NET 8 SDK -- [ ] Node.js 18+ -- [ ] Visual Studio 2022 or VS Code - -Verify installations: -```bash -dotnet --version # Should show 8.x or higher -node --version # Should show v18.x or higher -``` - -## Step 1: Build the .NET Projects (2 minutes) - -```bash -# Open a terminal in the project root -cd C:\Code\GitHubRepos\Autopilot-Monitor - -# Restore all packages -dotnet restore - -# Build everything -dotnet build -``` - -Expected output: `Build succeeded` - -## Step 2: Install Azure Storage Emulator (2 minutes) - -### Option A: Azurite (Recommended) -```bash -npm install -g azurite - -# Start Azurite -azurite --silent --location c:\azurite -``` - -### Option B: Azure Storage Emulator -If you have the legacy Azure Storage Emulator installed, start it: -```bash -AzureStorageEmulator.exe start -``` - -## Step 3: Start the Backend API (2 minutes) - -Open a new terminal: -```bash -cd src\Backend\AutopilotMonitor.Functions - -# Start Azure Functions -func start -``` - -Expected output: -``` -Azure Functions Core Tools -... -Functions: - IngestEvents: [POST] http://localhost:7071/api/events/ingest - RegisterSession: [POST] http://localhost:7071/api/sessions/register -``` - -## Step 4: Start the Web UI (3 minutes) - -Open another terminal: -```bash -cd src\Web\autopilot-monitor-web - -# Install dependencies (first time only) -npm install - -# Copy environment template -copy .env.local.template .env.local - -# Start development server -npm run dev -``` - -Expected output: `Ready on http://localhost:3000` - -## Step 5: Test the Agent (2 minutes) - -Open PowerShell **as Administrator**: -```powershell -cd src\Agent\AutopilotMonitor.Agent\bin\Debug\net48 - -# Run in console mode -.\AutopilotMonitor.Agent.exe --console -``` - -Expected output: -``` -Autopilot Monitor Agent - Console Mode -====================================== - -Session ID: -API URL: http://localhost:7071 -Log Directory: C:\ProgramData\AutopilotMonitor\Logs - -Agent is running. Press Enter to stop... -``` - -## Verify It's Working - -1. **Check the Agent Console** - Should show "Agent started" event -2. **Check the Functions Console** - Should show incoming requests -3. **Open Browser** - Navigate to http://localhost:3000 -4. **View Dashboard** - You should see the Autopilot Monitor homepage - -## What's Next? - -### Explore the Code -- [Agent Code](src/Agent/AutopilotMonitor.Agent.Core/) - Monitoring logic -- [Backend API](src/Backend/AutopilotMonitor.Functions/) - Azure Functions -- [Web UI](src/Web/autopilot-monitor-web/) - Next.js dashboard - -### Read Documentation -- [Getting Started Guide](docs/getting-started.md) - Detailed setup -- [Architecture Overview](docs/architecture.md) - How it all works -- [Contributing Guide](CONTRIBUTING.md) - How to contribute - -### Try It Out -1. Modify the agent to emit custom events -2. Add a new API endpoint -3. Create a new page in the web UI -4. Write a rule for the rule engine (Phase 2) - -## Troubleshooting - -### Agent won't start -- Run as Administrator -- Check .NET Framework 4.8 is installed -- View logs in `C:\ProgramData\AutopilotMonitor\Logs\` - -### Functions won't start -- Ensure Azurite/Storage Emulator is running -- Check `local.settings.json` exists -- Install Azure Functions Core Tools v4 - -### Web UI shows errors -- Run `npm install` again -- Check `.env.local` exists -- Verify Functions are running on port 7071 - -### Can't connect to API -- Check Windows Firewall -- Verify Functions console shows the correct URLs -- Try `curl http://localhost:7071/api/sessions/register` - -## Next Development Steps - -1. **Phase 1 Completion** - - Implement Azure Table Storage integration - - Add real-time session monitoring - - Create session detail page - -2. **Phase 2: Intelligence** - - Build rule engine - - Add diagnosis panel - - Implement troubleshooting bundles - -3. **Phase 3: Production** - - Deploy to Azure - - Configure Intune deployment - - Set up monitoring and alerts - -## Getting Help - -- Check [README.md](README.md) for overview -- Read [docs/getting-started.md](docs/getting-started.md) for details -- Open an issue on GitHub -- Review the code - it's well-commented! - ---- - -**You're ready to go!** Start exploring and building. 🚀 diff --git a/README.md b/README.md index 76faddfd..aaeb2c87 100644 --- a/README.md +++ b/README.md @@ -6,157 +6,15 @@ Advanced monitoring and troubleshooting solution for Windows Autopilot deploymen Autopilot Monitor provides real-time tracking, intelligent diagnostics, and automated troubleshooting for Windows Autopilot enrollment processes. It consists of: -- **Bootstrap Script** - PowerShell script deployed via Intune that starts monitoring early in the enrollment process -- **Monitoring Agent** - Lightweight .NET Windows Service that collects telemetry and evidence -- **Backend API** - Azure Functions-based ingestion and processing pipeline -- **Web Dashboard** - Next.js application for real-time monitoring and fleet analytics - -## Architecture - -``` -Device Side Azure Backend Web UI -┌──────────────┐ ┌──────────────┐ ┌──────────┐ -│ Bootstrap │──deploys──▶ │ │ │ │ -│ Script │ │ Azure │◀───────────▶ │ Next.js │ -└──────┬───────┘ │ Functions │ │ Web App │ - │ │ │ │ │ - ▼ │ • Ingest │ └──────────┘ -┌──────────────┐ │ • Store │ -│ Monitoring │──telemetry──▶ │ • Analyze │ -│ Agent │ (mTLS) │ │ -└──────────────┘ └──────┬───────┘ - │ - ▼ - ┌──────────────┐ - │ Azure Table │ - │ Azure Blob │ - │ Azure SQL │ - └──────────────┘ -``` - -## Project Structure - -``` -Autopilot-Monitor/ -├── src/ -│ ├── Agent/ # .NET monitoring agent -│ │ ├── AutopilotMonitor.Agent/ # Windows Service host -│ │ └── AutopilotMonitor.Agent.Core/ # Core monitoring logic -│ ├── Backend/ # Azure Functions -│ │ └── AutopilotMonitor.Functions/ -│ ├── Shared/ # Shared models/contracts -│ │ └── AutopilotMonitor.Shared/ -│ └── Web/ # Frontend -│ └── autopilot-monitor-web/ -├── scripts/ -│ ├── Bootstrap/ # Intune deployment scripts -│ └── Deployment/ # Azure deployment scripts -├── rules/ # YAML rule definitions -└── docs/ # Documentation -``` - -## Phase 1 Goals (Current) - -- [x] Project structure setup -- [ ] Bootstrap PowerShell script -- [ ] Basic .NET agent with log tailing -- [ ] Azure Functions ingestion API -- [ ] Session registration and event storage -- [ ] Minimal web UI (session list, timeline) - -## Getting Started - -### Prerequisites - -- .NET Framework 4.8 SDK (for Agent) -- .NET 8 SDK (for Azure Functions) -- Node.js 18+ (for Web UI) -- Azure subscription -- Visual Studio 2022 or VS Code - -### Development Setup - -1. **Clone and restore packages** - ```bash - git clone - cd Autopilot-Monitor - dotnet restore - ``` - -2. **Set up local Azure Functions** - ```bash - cd src/Backend/AutopilotMonitor.Functions - cp local.settings.json.template local.settings.json - # Edit local.settings.json with your Azure Storage connection string - ``` - -3. **Set up web frontend** - ```bash - cd src/Web/autopilot-monitor-web - npm install - cp .env.local.template .env.local - # Edit .env.local with your API endpoint - ``` - -4. **Build the agent** - ```bash - cd src/Agent/AutopilotMonitor.Agent - dotnet build - ``` - -### Running Locally - -1. **Start Azure Functions** (in one terminal) - ```bash - cd src/Backend/AutopilotMonitor.Functions - func start - ``` - -2. **Start Web UI** (in another terminal) - ```bash - cd src/Web/autopilot-monitor-web - npm run dev - ``` - -3. **Test agent** (as Administrator) - ```bash - cd src/Agent/AutopilotMonitor.Agent/bin/Debug - .\AutopilotMonitor.Agent.exe --console - ``` +- **Bootstrap Script** — PowerShell script deployed via Intune that starts monitoring early in the enrollment process +- **Monitoring Agent** — Lightweight .NET application that collects telemetry and evidence during enrollment +- **Backend API** — Azure Functions-based ingestion and processing pipeline +- **Web Dashboard** — Next.js application for real-time monitoring and fleet analytics ## Documentation -- [Architecture Overview](docs/architecture.md) -- [Agent Development](docs/agent-development.md) -- [Rule Engine](docs/rule-engine.md) -- [Deployment Guide](docs/deployment.md) - -## Contributing - -We welcome community contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +Full documentation is available at **[autopilotmonitor.com/docs](https://www.autopilotmonitor.com/docs)** ## License -MIT License - see [LICENSE](LICENSE) for details - -## Roadmap - -### Phase 1: Foundation (Current) -- Bootstrap and basic agent -- Simple ingestion pipeline -- Minimal UI - -### Phase 2: Intelligence -- Rule engine -- Diagnosis panel -- Troubleshooting bundles - -### Phase 3: Polish -- Fleet dashboard -- User-facing portal -- Multi-tenant support - -### Phase 4: Advanced -- Pre-provisioning support -- Custom rule authoring -- Integration APIs +MIT License — see [LICENSE](LICENSE) for details diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index f993989c..00000000 --- a/docs/architecture.md +++ /dev/null @@ -1,389 +0,0 @@ -# Architecture Overview - -This document describes the technical architecture of Autopilot Monitor. - -## High-Level Architecture - -Autopilot Monitor consists of four main components: - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ DEVICE SIDE │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────────────┐ ┌──────────────────────────────────────────┐ │ -│ │ Bootstrap.ps1 │────▶│ Monitoring Agent (.NET 4.8 Service) │ │ -│ │ (Intune Script) │ │ │ │ -│ │ │ │ • Log Watchers │ │ -│ │ • Deploy agent │ │ • Event Collectors │ │ -│ │ • Create session │ │ • Performance Monitors │ │ -│ │ • Set correlation│ │ • Upload Manager │ │ -│ └──────────────────┘ └─────────────┬────────────────────────────┘ │ -│ │ │ -└─────────────────────────────────────────┼───────────────────────────────┘ - │ HTTPS (mTLS) - ▼ -┌─────────────────────────────────────────────────────────────────────────┐ -│ AZURE BACKEND │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌────────────────────────────────────────────────────────────────────┐ │ -│ │ Azure Functions (.NET 8 Isolated) │ │ -│ │ │ │ -│ │ /api/sessions/register │ /api/events/ingest │ /api/bundles/* │ │ -│ └────────────────┬────────────────────┬──────────────────┬───────────┘ │ -│ │ │ │ │ -│ ▼ ▼ ▼ │ -│ ┌─────────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ Azure Table │ │ Azure Table │ │ Azure Blob │ │ -│ │ (Sessions) │ │ (Events) │ │ (Bundles/Logs) │ │ -│ └─────────────────────┘ └──────────────────┘ └──────────────────┘ │ -│ │ -│ ┌────────────────────────┐ ┌───────────────────────────┐ │ -│ │ Azure SignalR Service │──────────▶│ Next.js Web App │ │ -│ │ (Real-time updates) │ │ (Static Web App) │ │ -│ └────────────────────────┘ └───────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -## Component Details - -### 1. Bootstrap Script (PowerShell) - -**Purpose**: Deploy and configure the monitoring agent early in Autopilot enrollment. - -**Responsibilities**: -- Generate unique session ID -- Collect device information -- Store configuration in registry -- Install/start monitoring agent -- Register session with backend - -**Deployment**: Intune PowerShell Script (required, runs in Device ESP) - -**Key Files**: -- [Install-AutopilotMonitor.ps1](../scripts/Bootstrap/Install-AutopilotMonitor.ps1) - -### 2. Monitoring Agent (.NET Framework 4.8) - -**Purpose**: Continuously monitor enrollment progress and collect telemetry. - -**Architecture**: - -``` -AutopilotMonitor.Agent (Exe) -├── Program.cs (Entry point, console or service mode) -└── AutopilotMonitorService.cs (Windows Service wrapper) - │ - └── AutopilotMonitor.Agent.Core (Library) - ├── Monitoring/ - │ ├── MonitoringService.cs (Main orchestrator) - │ ├── LogWatcher.cs (Tail IME logs) - │ ├── EventMonitor.cs (Watch Windows Event Log) - │ └── PerformanceMonitor.cs (CPU, memory, disk) - │ - ├── Storage/ - │ └── EventSpool.cs (Offline queue) - │ - ├── Api/ - │ └── BackendApiClient.cs (HTTP client for API calls) - │ - ├── Configuration/ - │ └── AgentConfiguration.cs (Settings) - │ - └── Logging/ - └── AgentLogger.cs (Simple file logger) -``` - -**Key Features**: -- Runs as Windows Service (LocalSystem account) -- Offline spool for resilient upload -- Batched uploads (configurable interval) -- Exponential backoff on failures -- Low memory footprint (<50MB) - -**Data Flow**: -1. Watchers detect events (logs, event log, performance) -2. Events normalized into `EnrollmentEvent` objects -3. Events added to local spool (file-based queue) -4. Periodic upload timer sends batches to backend -5. On success, events removed from spool - -**Key Files**: -- [MonitoringService.cs](../src/Agent/AutopilotMonitor.Agent.Core/Monitoring/MonitoringService.cs) -- [EventSpool.cs](../src/Agent/AutopilotMonitor.Agent.Core/Storage/EventSpool.cs) -- [BackendApiClient.cs](../src/Agent/AutopilotMonitor.Agent.Core/Api/BackendApiClient.cs) - -### 3. Backend API (Azure Functions) - -**Purpose**: Ingest telemetry, store data, and serve web UI. - -**Functions**: - -#### RegisterSession -- **Route**: `POST /api/sessions/register` -- **Purpose**: Register a new enrollment session -- **Input**: `SessionRegistration` (device info, session ID) -- **Output**: `RegisterSessionResponse` (success, registered timestamp) -- **Storage**: Azure Table Storage (`sessions` table) - -#### IngestEvents -- **Route**: `POST /api/events/ingest` -- **Purpose**: Receive batched events from agents -- **Input**: `IngestEventsRequest` (session ID, list of events) -- **Output**: `IngestEventsResponse` (events processed count) -- **Storage**: Azure Table Storage (`events` table) -- **Features**: - - Compression support (gzip) - - Batch processing - - Deduplication (by event ID) - -#### UploadBundle -- **Route**: `POST /api/bundles/upload` -- **Purpose**: Get SAS URL for uploading troubleshooting bundle -- **Input**: `UploadBundleRequest` (session ID, file name) -- **Output**: `UploadBundleResponse` (SAS URL, expiry) -- **Storage**: Azure Blob Storage (`bundles` container) - -**Authentication** (Future): -- Phase 1: Function key authentication -- Phase 2+: Client certificate (mTLS) using Intune MDM cert - -**Key Files**: -- [RegisterSessionFunction.cs](../src/Backend/AutopilotMonitor.Functions/Functions/RegisterSessionFunction.cs) -- [IngestEventsFunction.cs](../src/Backend/AutopilotMonitor.Functions/Functions/IngestEventsFunction.cs) - -### 4. Web Dashboard (Next.js) - -**Purpose**: Real-time monitoring and troubleshooting UI. - -**Technology Stack**: -- Next.js 15 (React 19) -- TypeScript -- Tailwind CSS -- Azure Static Web Apps (deployment) - -**Key Pages** (Planned): - -``` -/ (Dashboard) -├── Active sessions grid -├── Fleet health metrics -└── Recent failures - -/sessions/[id] (Session Detail) -├── Phase timeline -├── Event stream -├── Diagnosis panel -└── Download bundle - -/sessions (Session List) -├── Filterable table -├── Search by serial/device name -└── Status indicators - -/fleet (Fleet Analytics) -├── Success rate trends -├── Failure reason distribution -├── Model/OS breakdown -└── App install leaderboard -``` - -**Key Files**: -- [app/page.tsx](../src/Web/autopilot-monitor-web/app/page.tsx) (Dashboard) -- [app/layout.tsx](../src/Web/autopilot-monitor-web/app/layout.tsx) (Root layout) - -### 5. Shared Library - -**Purpose**: Common models and constants across all .NET projects. - -**Key Models**: -- `EnrollmentEvent` - Single telemetry event -- `EnrollmentPhase` - Enrollment phase enumeration -- `SessionRegistration` - Device and session info -- `SessionSummary` - Session overview for UI -- `ApiModels` - Request/response contracts - -**Key Files**: -- [Models/](../src/Shared/AutopilotMonitor.Shared/Models/) -- [Constants.cs](../src/Shared/AutopilotMonitor.Shared/Constants.cs) - -## Data Models - -### Azure Table Storage Schema - -#### Sessions Table - -| Property | Type | Description | -|----------|------|-------------| -| PartitionKey | string | `{TenantId}` | -| RowKey | string | `{SessionId}` | -| SerialNumber | string | Device serial number | -| Manufacturer | string | Device manufacturer | -| Model | string | Device model | -| DeviceName | string | Computer name | -| StartedAt | DateTime | Enrollment start time (UTC) | -| CompletedAt | DateTime? | Enrollment end time (UTC) | -| CurrentPhase | int | Current enrollment phase | -| Status | string | InProgress, Succeeded, Failed | -| EventCount | int | Total events received | - -#### Events Table - -| Property | Type | Description | -|----------|------|-------------| -| PartitionKey | string | `{TenantId}_{SessionId}` | -| RowKey | string | `{Timestamp}_{Sequence}` | -| EventId | string | Unique event identifier (GUID) | -| EventType | string | Type of event | -| Severity | int | Debug, Info, Warning, Error, Critical | -| Source | string | Where the event originated | -| Phase | int | Phase during which event occurred | -| Message | string | Human-readable message | -| Data | string | JSON-serialized additional data | - -### Azure Blob Storage Structure - -``` -bundles/ - {tenant-id}/ - {session-id}/ - troubleshooting-bundle.zip - logs/ - agent.log - ime.log - events/ - events.json - diagnostics/ - dsregcmd.txt - network.txt - -screenshots/ - {tenant-id}/ - {session-id}/ - {timestamp}.jpg -``` - -## Security Architecture - -### Phase 1 (Current) -- Function key authentication (keys in URL) -- No encryption at rest (using Azure defaults) -- HTTPS for transport - -### Phase 2+ (Planned) -- Client certificate authentication (mTLS) - - Leverage Intune MDM device certificate - - No secrets on device - - Per-device authentication -- Azure AD authentication for web UI -- Multi-tenant isolation -- Encryption at rest (Azure Storage encryption) -- PII redaction policies - -## Scalability Considerations - -### Current Capacity (Phase 1) -- ~1,000 devices/month: ~$15/month Azure cost -- ~10,000 devices/month: ~$50-100/month Azure cost - -### Storage Scaling - -**Azure Table Storage**: -- Massively scalable (billions of entities) -- Auto-sharding by PartitionKey -- PartitionKey strategy: `{TenantId}` for sessions, `{TenantId}_{SessionId}` for events -- Supports 20,000 entities/sec per table - -**Azure Blob Storage**: -- Unlimited storage -- Auto-tiering (Hot → Cool → Archive) -- Lifecycle policies for cost optimization - -### Compute Scaling - -**Azure Functions**: -- Consumption plan: Auto-scale to demand -- Isolated worker process model (better performance) -- Can handle 1000s of concurrent requests - -**Web UI (Static Web Apps)**: -- Global CDN distribution -- Scales automatically -- Near-zero cost for read operations - -## Monitoring and Observability - -### Application Insights Integration - -All components log to Azure Application Insights: - -- **Agent**: Custom telemetry via API -- **Functions**: Built-in integration -- **Web**: Custom events and page views - -### Metrics to Track - -- Event ingestion rate (events/sec) -- API response times (p50, p95, p99) -- Failed uploads (count, reasons) -- Storage utilization (GB, transactions) -- Active sessions (count) -- Session success rate (%) - -## Cost Optimization Strategies - -1. **Use Azure Table Storage** instead of Cosmos DB (99% cheaper) -2. **Batch events** before upload (reduce transactions) -3. **Compress payloads** (reduce bandwidth) -4. **Lifecycle policies** for blob storage (hot → cool → archive) -5. **Summarize aggressively** (don't store every raw log line) -6. **Cache static content** (CDN for web UI) -7. **Use consumption plans** (pay per use, not reserved capacity) - -## Future Architecture Enhancements - -### Phase 2: Intelligence -- Rule engine (YAML-based, server-side evaluation) -- Real-time SignalR for live updates -- Troubleshooting bundle generation - -### Phase 3: Advanced -- Pre-provisioning support -- Custom rule authoring UI -- REST API for integrations -- Webhook notifications -- Teams/Slack integration - -### Phase 4: Enterprise -- Multi-tenant SaaS model -- Tenant-level isolation -- RBAC and permissions -- Audit logging -- Compliance controls (GDPR, etc.) - -## Development Best Practices - -### Code Organization -- Keep shared models in `AutopilotMonitor.Shared` -- Agent logic in `AutopilotMonitor.Agent.Core` (testable) -- Thin wrappers for service/console in `AutopilotMonitor.Agent` -- Stateless Azure Functions (no local state) - -### Error Handling -- Agent: Never crash, always spool locally -- Functions: Return proper HTTP status codes -- Web: Graceful degradation, show cached data - -### Testing -- Unit tests for core logic -- Integration tests for API endpoints -- End-to-end tests for critical flows -- Load testing for scalability validation - -### Deployment -- CI/CD with GitHub Actions -- Separate environments (dev, staging, prod) -- Infrastructure as Code (Bicep/ARM templates) -- Automated rollback on failures diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 68b77933..00000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,246 +0,0 @@ -# Getting Started with Autopilot Monitor - -This guide will help you set up and run Autopilot Monitor locally for development and testing. - -## Prerequisites - -### Required -- Windows 10/11 (for agent development and testing) -- .NET Framework 4.8 SDK -- .NET 8 SDK -- Visual Studio 2022 or VS Code with C# extensions -- Node.js 18+ and npm -- Azure Storage Emulator or Azurite (for local storage) -- Azure Functions Core Tools v4 - -### Optional -- Git -- PowerShell 5.1 or later -- Microsoft Intune tenant (for production deployment) - -## Quick Start (5 Minutes) - -### 1. Clone and Build - -```bash -# Clone the repository -git clone -cd Autopilot-Monitor - -# Restore and build all .NET projects -dotnet restore -dotnet build -``` - -### 2. Start Local Storage - -Install and start Azurite (Azure Storage Emulator): - -```bash -npm install -g azurite -azurite --silent --location c:\azurite --debug c:\azurite\debug.log -``` - -Or use the Azure Storage Emulator if you have it installed. - -### 3. Start Azure Functions Backend - -```bash -cd src/Backend/AutopilotMonitor.Functions -func start -``` - -The API will be available at `http://localhost:7071` - -### 4. Start Web UI - -```bash -cd src/Web/autopilot-monitor-web - -# Install dependencies (first time only) -npm install - -# Copy environment template -cp .env.local.template .env.local - -# Start development server -npm run dev -``` - -The web UI will be available at `http://localhost:3000` - -### 5. Test the Agent - -Open a new PowerShell window **as Administrator**: - -```powershell -cd src/Agent/AutopilotMonitor.Agent/bin/Debug/net48 -.\AutopilotMonitor.Agent.exe --console -``` - -You should see the agent start and begin sending telemetry to the backend. - -## Detailed Setup - -### Backend Configuration - -The Azure Functions use `local.settings.json` for configuration. This file is created from the template: - -```json -{ - "IsEncrypted": false, - "Values": { - "AzureWebJobsStorage": "UseDevelopmentStorage=true", - "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated", - "AzureTableStorageConnectionString": "UseDevelopmentStorage=true", - "AzureBlobStorageConnectionString": "UseDevelopmentStorage=true" - } -} -``` - -For production, replace `UseDevelopmentStorage=true` with your Azure Storage connection strings. - -### Agent Configuration - -The agent reads configuration from the Windows Registry (set by the bootstrap script) or falls back to defaults. For testing, you can modify [Program.cs](../src/Agent/AutopilotMonitor.Agent/Program.cs): - -```csharp -return new AgentConfiguration -{ - ApiBaseUrl = "http://localhost:7071", - SessionId = Guid.NewGuid().ToString(), - TenantId = "test-tenant", - // ... other settings -}; -``` - -### Web UI Configuration - -Create `.env.local` in the web project: - -```env -NEXT_PUBLIC_API_BASE_URL=http://localhost:7071 -``` - -This tells the web UI where to find the backend API. - -## Testing End-to-End - -### 1. Verify Backend is Running - -Open a browser and navigate to: -``` -http://localhost:7071/api/sessions/register -``` - -You should see a response (even if it's an error, it confirms the function is running). - -### 2. Run the Agent - -Start the agent in console mode (as Administrator): - -```powershell -cd src/Agent/AutopilotMonitor.Agent/bin/Debug/net48 -.\AutopilotMonitor.Agent.exe --console -``` - -### 3. Check Logs - -Agent logs are written to: -``` -C:\ProgramData\AutopilotMonitor\Logs\agent_YYYYMMDD.log -``` - -Backend logs appear in the Functions console output. - -### 4. View in Web UI - -Open `http://localhost:3000` and you should see the dashboard (currently shows placeholder data in Phase 1). - -## Common Issues - -### Azure Functions won't start - -**Error**: `Missing value for AzureWebJobsStorage` - -**Solution**: Ensure Azurite or Azure Storage Emulator is running, or update `local.settings.json` with valid connection strings. - -### Agent can't connect to API - -**Error**: `Error uploading events: The remote name could not be resolved` - -**Solution**: -1. Verify Azure Functions is running at `http://localhost:7071` -2. Check Windows Firewall isn't blocking the connection -3. Update agent configuration with correct API URL - -### Web UI shows blank page - -**Solution**: -1. Check browser console for errors -2. Verify `npm run dev` completed without errors -3. Check `.env.local` exists and has correct API URL - -### Permission Errors - -Many agent operations require Administrator privileges: -- Reading certain event logs -- Writing to Program Files -- Installing as a Windows Service - -Always run the agent as Administrator during development. - -## Development Workflow - -### Typical Development Session - -1. **Start infrastructure** (Azurite, Functions) - ```bash - # Terminal 1: Azurite - azurite --silent --location c:\azurite - - # Terminal 2: Functions - cd src/Backend/AutopilotMonitor.Functions - func start - - # Terminal 3: Web UI - cd src/Web/autopilot-monitor-web - npm run dev - ``` - -2. **Make changes** to agent, backend, or web code - -3. **Test changes** - - Agent: Rebuild and run in console mode - - Backend: Hot reload should pick up changes - - Web: Hot reload should pick up changes - -4. **Debug** - - Agent: Attach Visual Studio debugger or use console output - - Backend: Use Functions console logs or attach debugger - - Web: Use browser DevTools - -### Building for Release - -```bash -# Build all projects in Release mode -dotnet build -c Release - -# Build web UI for production -cd src/Web/autopilot-monitor-web -npm run build -``` - -## Next Steps - -- Read the [Architecture Overview](architecture.md) -- Learn about [Deploying to Azure](deployment.md) -- Explore the [API Documentation](api-reference.md) -- Understand the [Rule Engine](rule-engine.md) (Phase 2) - -## Getting Help - -- Check the [README](../README.md) for general information -- Review logs in `C:\ProgramData\AutopilotMonitor\Logs\` -- Check Azure Functions output for backend errors -- Use browser DevTools for web UI issues