> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/.net-maui-standards/maui-application-architecture.md).

# MAUI Application Architecture

## Purpose

MAUI applications require deliberate architecture because they span multiple platforms, device capabilities, signing models and lifecycle behaviours.

## Standard Structure

```
Aic.Product.App
  Pages/
  ViewModels/
  Resources/
  Platforms/
Aic.Product.App.Core
  Services/
  Models/
  Navigation/
Aic.Product.Application
Aic.Product.Domain
Aic.Product.Infrastructure
```

## Platform Isolation

Platform-specific code belongs in:

* `Platforms/Android`
* `Platforms/iOS`
* `Platforms/MacCatalyst`
* `Platforms/Windows`
* platform service implementations behind interfaces

Do not scatter platform checks throughout business logic.

## Device Services

Wrap device services:

```csharp
public interface ISecureTokenStore
{
    Task SaveTokenAsync(string token, CancellationToken cancellationToken);
    Task<string?> GetTokenAsync(CancellationToken cancellationToken);
    Task ClearAsync(CancellationToken cancellationToken);
}
```

## Lifecycle

MAUI apps must handle:

* startup
* resume
* suspend
* network changes
* permission changes
* token expiry
* offline state
* sync conflicts
* app updates

## Quality Gate

* Platform builds pass.
* App starts cold within acceptable threshold.
* Offline behaviour tested.
* Secure storage tested.
* Permissions tested.
* Navigation tested.
* API errors tested.
* Crash reporting and diagnostics reviewed.