> 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/tech-stack/cross-platform-app-stack-maui.md).

# Cross-Platform App Stack MAUI

## Purpose

.NET MAUI is AIC's standard option for cross-platform mobile and desktop applications where one shared .NET codebase must target Android, iOS, macOS and/or Windows.

MAUI should be chosen deliberately. It provides shared code and native UI capabilities, but it also introduces platform-specific testing, signing, distribution and dependency constraints.

## When to Use MAUI

Use MAUI when:

* mobile app delivery is required
* shared C# code across platforms creates clear value
* the customer accepts native app distribution requirements
* platform-specific testing is funded and planned
* device permissions and offline behaviour are understood
* support for required OS versions is available

Avoid MAUI when:

* a responsive web app meets the requirement
* the app is Windows-only and WPF is simpler
* customer deployment cannot support app signing or store/private distribution
* platform-specific behaviour cannot be tested

## Architecture Standard

Recommended structure:

```
src/
  Aic.Product.App/
  Aic.Product.App.Core/
  Aic.Product.Application/
  Aic.Product.Domain/
  Aic.Product.Infrastructure/
tests/
  Aic.Product.App.Core.Tests/
  Aic.Product.Application.Tests/
  Aic.Product.IntegrationTests/
```

## Mandatory MAUI Rules

* Keep platform-specific code isolated.
* Keep business logic outside pages and code-behind.
* Use MVVM for presentation logic.
* Abstract device services behind interfaces.
* Validate permissions at runtime.
* Use secure storage for secrets and sensitive tokens.
* Test on real devices or approved device farms before production release.
* Document platform support and minimum OS versions.
* Document signing, packaging and distribution.

## MAUI Quality Gate

Before release:

* build tested for each target platform
* app signing validated
* permissions tested
* offline scenarios tested
* API failure scenarios tested
* secure storage reviewed
* accessibility reviewed
* crash reporting or diagnostics configured where permitted
* versioning and update path validated