Fixiy/AGENTS.md

Fixiy — Agent Guide

Project Overview

Fixiy is a .NET MAUI Blazor Hybrid app that shares its entire UI with a Blazor Server Web App via a Razor Class Library (RCL). All pages and components live in Fixiy.Shared and are consumed by both host projects without modification.

• App ID: it.integry.fixiy
• Solution: Fixiy.sln
• SDK: .NET 10 (global.json — rollForward: latestMajor)
• NuGet source: Private feed — see NuGet.Config (https://nuget.studioml.it/repository/nuget-group/index.json)
• Platforms: Android 26+, iOS 15+, Web (Blazor Server)

Repository Structure

Fixiy.sln
├── Fixiy.Maui/                    # .NET MAUI Blazor Hybrid host (Android + iOS)
│   ├── MauiProgram.cs             # DI root — registers MAUI services + IntegryApiClient
│   ├── Services/FormFactor.cs     # MAUI implementation of IFormFactor (uses DeviceInfo)
│   ├── Platforms/                 # Platform-specific entry points (Android, iOS, …)
│   └── Resources/                 # App icons, splash, fonts, images
├── Fixiy.Shared/                  # Razor Class Library — all shared UI
│   ├── Components/
│   │   ├── Layout/                # MainLayout.razor, NavBar.razor, NavMenu.razor
│   │   ├── Pages/                 # Routable pages (e.g., Home.razor)
│   │   └── SingleElements/        # Reusable components (e.g., NoDataAvailable.razor)
│   ├── Interfaces/IFormFactor.cs  # Platform abstraction interface
│   ├── InteractiveRenderSettings.cs  # Shared render mode constants (nulled in MAUI)
│   └── _Imports.razor             # Global using directives for shared components
└── Fixiy.Web/                     # Blazor Server Web App host
    ├── Program.cs                 # DI root — registers web services + IntegryApiClient
    └── Services/FormFactor.cs     # Web implementation of IFormFactor

Tech Stack

Layer	Technology
Mobile host	.NET MAUI Blazor Hybrid — net10.0-android, net10.0-ios
Web host	Blazor Server (ASP.NET Core, net10.0)
Shared UI	Razor Class Library (Fixiy.Shared, net10.0)
Client SDK	IntegryApiClient — MAUI / Core / Blazor variants (private NuGet)
Fonts	OpenSans via MAUI font registration

Build & Run

Prerequisites: .NET SDK 10, MAUI workload (dotnet workload install maui) for mobile builds.

# Restore (requires private NuGet credentials — see NuGet.Config)
dotnet restore Fixiy.sln

# Run Blazor Web App (no platform SDK required)
dotnet run --project Fixiy.Web/Fixiy.Web.csproj

# Build MAUI for Android (requires MAUI workload)
dotnet build Fixiy.Maui/Fixiy.Maui.csproj -f net10.0-android

# Build MAUI for iOS (requires macOS + Xcode)
dotnet build Fixiy.Maui/Fixiy.Maui.csproj -f net10.0-ios

Key Patterns and Conventions

1. InteractiveRenderSettings pattern

Fixiy.Shared/InteractiveRenderSettings.cs exposes static IComponentRenderMode? properties (InteractiveServer, InteractiveAuto, InteractiveWebAssembly). In Fixiy.Web these remain set to real render modes. In Fixiy.Maui, MauiProgram.ConfigureBlazorHybridRenderModes() sets all three to null — MAUI Blazor Hybrid does not support server or WASM render modes.

Always use the property, not the constant, in shared components:

@* Wrong — hard-coded constant, crashes in MAUI *@
@rendermode="RenderMode.InteractiveServer"

@* Correct — resolves to null in MAUI, InteractiveServer in Web *@
@rendermode="@InteractiveServer"

2. IFormFactor platform abstraction

IFormFactor (in Fixiy.Shared/Interfaces/) provides GetFormFactor() and GetPlatform(). Each host project provides its own implementation registered in DI. Inject IFormFactor in shared components; never call DeviceInfo or other MAUI APIs from Fixiy.Shared.

3. IntegryApiClient registration

Both DI roots register IntegryApiClient with the same appToken and useLoginAzienda: true.

• MAUI: .UseIntegry(appToken, useLoginAzienda: true) on MauiAppBuilder
• Web: builder.Services.UseIntegry(appToken, useLoginAzienda: true)

The app token must match across both registrations. It is currently declared as a const in MauiProgram.cs and a const string in Fixiy.Web/Program.cs.

4. Adding a new page

1. Create Fixiy.Shared/Components/Pages/YourPage.razor with @page "/your-route"
2. No extra registration required — Routes.razor discovers pages via assembly scanning
3. Add a navigation entry to Fixiy.Shared/Components/Layout/NavMenu.razor if user-accessible

5. Adding a platform-specific service

1. Define the interface in Fixiy.Shared/Interfaces/IYourService.cs
2. Implement in Fixiy.Maui/Services/YourService.cs (may use MAUI APIs)
3. Implement in Fixiy.Web/Services/YourService.cs (BCL only)
4. Register in Fixiy.Maui/MauiProgram.cs as AddSingleton<IYourService, YourService>()
5. Register in Fixiy.Web/Program.cs as AddScoped<IYourService, YourService>()

Maintenance Matrix

When you change…	Also update…
Fixiy.Shared/Interfaces/IFormFactor.cs	Fixiy.Maui/Services/FormFactor.cs and Fixiy.Web/Services/FormFactor.cs
Any interface in Fixiy.Shared/Interfaces/	Both platform Services/ implementations + both DI roots
InteractiveRenderSettings.cs (add/remove property)	MauiProgram.ConfigureBlazorHybridRenderModes() — must null all new properties
Fixiy.Shared/_Imports.razor	Verify imports are valid in both MAUI and Web (no platform-only namespaces)
IntegryApiClient package version	Update in all three .csproj files consistently
App token	Update in both Fixiy.Maui/MauiProgram.cs and Fixiy.Web/Program.cs
Fixiy.Shared/Components/Layout/NavMenu.razor	Review navigation works on both platforms

CI/CD

No CI pipeline is currently configured. The project uses a private NuGet feed (NuGet.Config). For CI builds:

• Set NUGET_USERNAME and NUGET_PASSWORD (or PAT) as CI secrets
• Build only Fixiy.Web in standard CI; MAUI builds require platform-specific agents with MAUI workloads
• See .github/workflows/copilot-setup-steps.yml for environment setup reference

Common Pitfalls

• Render mode constants in shared code: Use @InteractiveServer (property from InteractiveRenderSettings) never RenderMode.InteractiveServer. The MAUI host nulls these via ConfigureBlazorHybridRenderModes().
• MAUI APIs in Fixiy.Shared: DeviceInfo, FileSystem, Connectivity, and other Microsoft.Maui.* APIs are not available in the RCL. Define a new IFormFactor-style interface instead.
• Private NuGet feed: All dotnet restore calls require credentials. In CI, add the source credentials via environment secrets — the NuGet.Config <clear/> directive removes all default sources.
• MAUI workload for builds: dotnet workload install maui is required before building Fixiy.Maui. Standard CI runners (Ubuntu) don't have it by default.
• Service lifetimes: MAUI registers platform services as Singleton (long-lived app); Web registers them as Scoped (per request). Interfaces must not assume a specific lifetime.