Service layer decoupling — guide

Updated: 2026-09-23

TLDR

• Before: three giant classes did everything data-related: DataManager (3,266 lines, 16 ports), RestService (2,323 lines, hand-rolled HTTP + 4 generated clients) and Authentication (1,280 lines, session + tokens + credentials + logout side effects).
• After: each concern has one home. A port in ALPAMobile.Application, an implementation in ALPAMobile.Infrastructure, one shared transport, one shared cache helper, and four narrow auth ports. DataManager and RestService are deleted.
• What did not change: the 16 query ports consumers already inject, every cache key, every persisted JSON shape, and every route. Callers and installed caches are unaffected.
• What is new and load-bearing: a cache generation that stops a request started by one member from writing into the next member's session (logout and account-switch safety).
• Status: delivered in eight phases (0–7) plus a review-remediation pass. It ships as one integration PR, PR 2543 (imp/blazor-hybrid-service-layer-decoupling → imp/blazor-hybrid), whose logged-out Home paint hold was corrected on 2026-09-23 (see Status).

Read top to bottom and stop when you have enough. Each level adds detail; none repeats the level above.

Level 1 — the 2-minute picture

The problem

Every domain (MEC, documents, notifications, …) re-implemented the same block by hand inside DataManager: check connectivity → check auth → call RestService → save to cache → on failure read stale cache. HTTP, retry, bearer-token handling and even UI snackbars lived in RestService. Login, logout and token refresh lived in Authentication, which also reached into the cache and theme/feed on logout.

Consequences: no unit could be tested alone, the head (MAUI app) project owned logic that has no MAUI dependency, and a slow response arriving after logout could repopulate the cache with the previous member's data.

The shape now

Consumers (ViewModels, Razor pages)
   │  inject narrow ports — unchanged names, e.g. IMECQueries, IDocumentsQueries
   ▼
ALPAMobile.Application        ports + orchestration (CacheContentService, prefetch)
   │
   ▼
ALPAMobile.Infrastructure     one focused service per domain (MecService, DocumentQueries, …)
   │                          per-domain API client → one shared transport → CachedRemoteQuery → ICacheStore
   ▼
Head (ALPAMobile)             only what needs MAUI: navigation, native file/viewer, push, connectivity

The five ideas to hold onto

Level 2 — how a request flows

Example: a signed-in member opens the MEC committees list.

1. The ViewModel calls IMECQueries (an Application port). It has never known who implements it.
2. DI resolves it to the Infrastructure MecService singleton (formerly forwarding code in DataManager).
3. MecService asks CachedRemoteQuery for the data, naming the cache key (GetMECCommitteesAsync, unchanged), a codec (legacy Newtonsoft shape) and a policy.
4. CachedRemoteQuery captures the current cache generation, then calls the MEC API client.
5. The API client sends through the authenticated request provider, which adds the bearer token. Its handling of failures:
   • transient failure on a GET → bounded retry;
   • 401 → one forced token refresh, one replay;
   • a write → sent once, never silently replayed.
6. On success, the result is written to the cache only if the generation is still current. The same write updates the Search index, atomically.
7. On a typed transient failure, the persisted copy is returned. Cancellation and session change are never turned into stale data.

Logout, the case this design exists for

1. Logout revokes the session epoch and cache generation synchronously.
2. Any in-flight request from step 4 above finishes later, sees a stale generation, and its result is discarded (a context-invalidated outcome, not a stale fallback).
3. Ordered logout participants then clear token, credentials and caches. A failure in one participant does not stop the rest.
4. The next member's sign-in waits for cleanup, so it starts from an empty, unpolluted context.

Level 3 — the building blocks

Paths are relative to the repository root.

Transport and endpoints

Transport defaults (from the implementation evidence):

Replay-safe exceptions that retry despite being non-GET: notification list reads, push-registration upserts, document download reads, flight-search read POSTs, favorite DELETEs.

Cache

Two named policies replace the old copy-pasted shapes: fallback on transport failure and stale-while-revalidate (documents).

Two hard constraints, both pinned by tests:

• Cache keys are also Search-index keys (SearchContentRegistry.Keys). Changing one silently blanks Search and the on-disk cache after upgrade.
• Raw write and index update are one operation under the coordinator. Otherwise a fetch finishing after logout could recreate security-trimmed Search rows.

Domain services

One focused service per domain, all in ALPAMobile.Infrastructure, resolved through the existing ports:

Prefetch orchestration (CacheContentService) lives in Application (Services/Caching/). It talks to platform concerns only through ports.

Authentication

IAuthentication (24 members) is split into four ports, all aliased to the one Authentication singleton:

IAuthentication survives only as an [Obsolete] composite for legacy fixtures; an architecture guard forbids new production consumers. Authentication no longer depends on a REST aggregate, the cache database, or a service provider. Sign-in captures an epoch; a superseded attempt cannot publish anything.

Guards (tests that keep this from regressing)

Level 4 — phase by phase

Each phase was its own PR into imp/blazor-hybrid-service-layer-decoupling. Detailed criteria and evidence are in SERVICE-LAYER-IMPLEMENTATION.html.

Phase PR numbers come from the implementation evidence and the PR 2527 integration plan; check Azure DevOps for current merge state.

Deliberate refinements (things that are not pure moves)

• Document download transport moved in Phase 4, earlier than planned, to avoid a temporary Infrastructure-to-head bridge.
• Generated-client wrappers were refined: PilotComms and Jumpseat keep their SDK wire types behind raw-to-domain factories while HTTP goes through the shared provider. One owner now handles transport, auth and retries.
• Stale-context results are rejected, not returned. Previously an outgoing member's data could be delivered mid-switch.
• An empty cached file is repaired on the next successful non-empty download; empty remote bytes are rejected.
• Cancellation is not fallback. A caller's cancel or a session change never becomes a stale return. A bare timeout without a cancelled token does fall back.

Level 5 — recipes and guardrails

Add a query to an existing domain

1. Add the method to the domain's existing Application port only if the port genuinely needs it.
2. Add the API client call in the domain's Infrastructure client, sending through the shared provider. Do not create an HttpClient.
3. In the domain service, call CachedRemoteQuery with an existing or newly registered key, a codec, and the policy that matches the legacy behavior for that domain.
4. Map wire data with a RawRepresentationFactory<T>; the factory stays a pure mapper.
5. Add tests: route and payload, key and JSON shape, offline fallback, auth-required behavior, late result after generation change.

Add a new domain

Follow MEC (MecService), the pilot: port in Application, service and API client in Infrastructure, codec beside the other codecs, DI in InfrastructureServiceCollectionExtensions. If the key should be searchable, onboard it per SEARCH-CONTENT-ONBOARDING.md.

Rules that are easy to break

Legacy code you may still meet

• Docs and old branches mention DataManager, IDataManager and RestService. All three are gone at the integration tip; treat references as history.
• IAuthentication remains as [Obsolete], pending migration of the legacy auth test fixtures.
• IRestEndpointProvider may still appear as an options-backed compatibility port; do not add consumers.

Status and open gates

PR 2543 carries the whole refactor into imp/blazor-hybrid. Its own description is the source of truth for the current state; the table below reflects the validation record at code revision 342d355e:

Reference docs