Architecture Overview

​

High-Level Architecture

​

Project Structure

src/
  Intune.Commander.Core/    # Business logic (.NET 10 class library)
    Auth/                    # Authentication providers and factory
    Models/                  # Domain models, enums, DTOs
    Services/                # Graph API services, caching, import/export
    Extensions/              # ServiceCollectionExtensions (DI setup)
  
  Intune.Commander.Desktop/  # Avalonia UI
    Views/                   # AXAML UI definitions
    ViewModels/              # MVVM view models
    Services/                # UI-specific services (DebugLogService)
    Converters/              # Value converters for data binding

tests/
  Intune.Commander.Core.Tests/  # xUnit tests mirroring src structure

​

Separation of Concerns

• Platform-agnostic business logic
• Microsoft Graph API integration
• Authentication and multi-cloud support
• Data models and services
• Export/import functionality
• No UI dependencies

• Avalonia-based UI
• MVVM view models
• UI-specific services (logging, dialogs)
• Data binding and converters
• References Core library

​

Key Architecture Decisions

​

1. Azure.Identity over MSAL

• Modern Microsoft-recommended approach
• Built-in multi-cloud support
• TokenCredential abstraction for multiple credential types
• Cleaner API surface
• Automatic credential fallback chains

// From: src/Intune.Commander.Core/Auth/IntuneGraphClientFactory.cs
public async Task<GraphServiceClient> CreateClientAsync(TenantProfile profile)
{
    var endpoints = CloudEndpoints.GetEndpoints(profile.Cloud);
    
    TokenCredential credential = profile.AuthMethod switch
    {
        AuthMethod.Interactive => new InteractiveBrowserCredential(
            new InteractiveBrowserCredentialOptions
            {
                TenantId = profile.TenantId,
                ClientId = profile.ClientId,
                AuthorityHost = endpoints.AuthorityHost
            }),
        AuthMethod.ClientSecret => new ClientSecretCredential(
            profile.TenantId,
            profile.ClientId,
            profile.ClientSecret,
            new TokenCredentialOptions { AuthorityHost = endpoints.AuthorityHost }
        ),
        _ => throw new NotSupportedException($"Auth method {profile.AuthMethod} not supported")
    };
    
    return new GraphServiceClient(credential, scopes, endpoints.GraphBaseUrl);
}

​

2. Direct Use of Microsoft.Graph.Beta SDK Models

• Strongly typed models
• Automatic updates when Graph API changes
• No manual mapping code required
• Built-in serialization
• Reduced maintenance burden

• Export/Import DTOs when SDK models have non-serializable properties
• Custom wrapper models for specific UI binding requirements

​

3. Multi-Cloud Architecture

• GCC-High and DoD require registrations in separate Azure portals
• Environment isolation and security
• Simpler permission management
• Avoids cross-cloud authentication errors

​

4. Graph Services Created Post-Authentication

• Services require an authenticated GraphServiceClient
• User may switch between multiple tenant profiles
• Services are tenant-specific, not application-wide
• Simpler lifecycle management

// From: src/Intune.Commander.Desktop/ViewModels/MainWindowViewModel.cs
private async Task ConnectToProfileAsync(TenantProfile profile)
{
    var graphClient = await _graphClientFactory.CreateClientAsync(profile);
    
    // Services created here, after authentication
    _configurationProfileService = new ConfigurationProfileService(graphClient);
    _compliancePolicyService = new CompliancePolicyService(graphClient);
    _settingsCatalogService = new SettingsCatalogService(graphClient);
    // ... 30+ more services
}

​

5. Profile and Cache Encryption

• Cross-platform encryption using a single consistent API
• DPAPI-protected keys on Windows
• File-system protected keys on macOS/Linux
• Keys persist in user’s local app data directory
• No need to manage encryption keys manually

• Location: %LOCALAPPDATA%\Intune.Commander\profiles.json
• Encrypted with INTUNEMANAGER_ENC: prefix
• ClientSecret stored encrypted in the profile
• Plaintext files automatically migrated on next save

• Location: %LOCALAPPDATA%\Intune.Commander\cache.db (LiteDB)
• AES-encrypted database
• Password generated once and stored encrypted in cache-key.bin
• 24-hour default TTL per cache entry
• Keyed by tenant ID + data type

​

6. Manual Pagination Pattern

• PageIterator silently truncates results on some tenants
• Large tenants require proper page size tuning
• Explicit control over @odata.nextLink handling
• Better error handling and retry logic

// From: src/Intune.Commander.Core/Services/ConfigurationProfileService.cs
public async Task<List<DeviceConfiguration>> ListDeviceConfigurationsAsync(
    CancellationToken cancellationToken = default)
{
    var result = new List<DeviceConfiguration>();

    var response = await _graphClient.DeviceManagement.DeviceConfigurations
        .GetAsync(req => req.QueryParameters.Top = 200, cancellationToken);

    while (response != null)
    {
        if (response.Value != null)
            result.AddRange(response.Value);

        if (!string.IsNullOrEmpty(response.OdataNextLink))
        {
            response = await _graphClient.DeviceManagement.DeviceConfigurations
                .WithUrl(response.OdataNextLink)
                .GetAsync(cancellationToken: cancellationToken);
        }
        else
        {
            break;
        }
    }

    return result;
}

• configurationPolicies (Settings Catalog): $top=100 (Cosmos DB cursor stability)
• windowsQualityUpdateProfiles, windowsDriverUpdateProfiles: $top=200 (hard API cap)
• All other list endpoints: $top=999

​

7. MVVM with CommunityToolkit.Mvvm

• Industry standard for Avalonia/WPF applications
• Source generators eliminate boilerplate code
• Clean separation of UI and business logic
• Testable view models
• Compile-time safety with x:DataType bindings

public partial class LoginViewModel : ObservableObject
{
    [ObservableProperty]
    private string _tenantId = string.Empty;
    
    [ObservableProperty]
    private CloudEnvironment _selectedCloud = CloudEnvironment.Commercial;
    
    [RelayCommand]
    private async Task ConnectAsync()
    {
        // Command implementation
    }
}

​

Error Handling Strategy

​

Graph API Errors

​

Retry Strategy

• Exponential backoff: 1s, 2s, 4s, 8s, 16s
• Respect Retry-After headers
• Maximum 5 retries
• User cancellation support via CancellationToken

​

Export/Import Format

​

Directory Structure

ExportFolder/
├── DeviceConfigurations/
│   ├── Policy1.json
│   └── Policy2.json
├── CompliancePolicies/
│   └── Policy3.json
├── SettingsCatalog/
│   └── Policy4.json
└── migration-table.json

{
  "objectType": "DeviceConfiguration",
  "originalId": "source-tenant-id",
  "newId": "destination-tenant-id",
  "name": "Policy Name",
  "exportedAt": "2025-02-14T10:00:00Z"
}

• Users may have existing PowerShell exports
• Migration path from PowerShell version
• Proven format structure
• .NET version can read PowerShell exports (backward compatibility)
• PowerShell version doesn’t need to read .NET exports (forward compatibility not required)

​

Performance Considerations

​

Graph API Optimization

1. Batch requests where supported (future enhancement)
2. Select queries - only request needed properties
3. Filter queries - reduce payload size
4. Parallel requests with concurrency limits
5. LiteDB cache - 24-hour TTL reduces redundant API calls

​

UI Responsiveness

1. Async/await for all I/O operations
2. Background tasks for bulk operations
3. Progress reporting via IProgress<T>
4. Cancellation tokens for long operations
5. Lazy loading - data loaded only when user navigates to a category
6. Fire-and-forget for non-blocking UI loads: _ = LoadDataAsync();

​

Memory Management

1. Streaming for large exports (future enhancement)
2. Dispose Graph clients properly
3. ObservableCollection size limits (e.g., DebugLogService capped at 2000 entries)

​

Security Considerations

​

Token Storage

• Never log access tokens
• Clear tokens on logout
• Encrypted profile storage
• No secrets in config files or source code

​

Certificate Handling

• Certificate-based auth is deferred (not yet implemented)
• When implemented: store thumbprints only, not private keys
• Use Windows certificate store for private key storage

​

Network Security

• HTTPS only
• Certificate validation enabled
• No proxy credential storage

​

Technology Constraints

​

.NET Version

• Long-term support
• Latest performance improvements
• Required for latest Avalonia versions
• C# 12 language features

​

C# Language Features Used

• Primary constructors: public class MyService(GraphServiceClient client)
• Collection expressions: return response?.Value ?? [];
• Required members: required string TenantId { get; init; }
• File-scoped namespaces: namespace Intune.Commander.Core.Services;
• Nullable reference types: Enabled everywhere

​

Minimum Requirements

​

Logging Strategy

​

DebugLogService

• DebugLogService.Instance singleton
• ObservableCollection<string> Entries (capped at 2000)
• All log dispatches to UI thread via Dispatcher.UIThread.Post
• Exposed in UI via DebugLogWindow

DebugLog.Log("Auth", "Connecting to tenant...");
DebugLog.LogError("Export", $"Failed to export policy: {ex.Message}");

​

Related Documentation

• Technology Stack - Complete list of dependencies and versions
• Services - Service architecture and DI patterns
• Testing - Unit and integration test strategies
• Building - Build commands and development workflow