EPIC: MFE-POC — Blazor Microfrontend POC (Identity + Cross-Cutting)¶

Build a Blazor-based microfrontend (MFE) POC with a Blazor Shell hosting several MFEs (Identity Self-Service, Identity Admin, Shared Components), using TailwindCSS + Flowbite for UI, and implementing cross-cutting concerns: logging, telemetry (OpenTelemetry), health checks, localization, API/BFF, authentication/authorization (ASP.NET Core Identity), inter-MFE communication, SignalR real-time, and application services. Deliver a runnable multi-project solution demonstrating identity management split into MFEs, consistent UX (Flowbite), edition-ready architecture, and CI basics.

Epic Description (expanded) Deliver a runnable multi-project Blazor microfrontend POC consisting of a Shell (Blazor Server) that hosts two MFEs (Identity Self-Service, Identity Admin), a Shared UI Components library (Tailwind + Flowbite-wrapped components), a Shared Contracts library (DTOs, error models, events), and a BFF/API project (minimal API for identity flows). The POC establishes consistent UX (Tailwind/Flowbite), and baseline cross-cutting scaffolding to enable future cycles: logging/telemetry (OpenTelemetry), health/readiness checks, localization, authentication/authorization (ASP.NET Core Identity), inter-MFE communication (SignalR), and application services. Output includes a solution structure, working shell + routed MFEs, base component kit, and developer scripts to run and iterate quickly.

Solution & Libraries Scaffolding¶

Feature: MFE-POC-F1 — Solution Skeleton & Libraries¶

Feature Description Create the multi-project solution skeleton with correct references, build tooling, and UI foundation:

Shell.BlazorServer (host, layout, routing, MFE loader)
Mfe.Identity.SelfService.Blazor
Mfe.Identity.Admin.Blazor
Shared.UiComponents.Blazor (Flowbite-wrapped components)
Shared.Contracts (DTOs, events)
Bff.Api (web API + auth endpoints scaffold) Add TailwindCSS + Flowbite toolchain and a starter pack of shared components to ensure both MFEs render consistently within the Shell.

1) MFE-POC-F1-T1 — Create multi-project solution structure¶

Description Scaffold a working solution with all projects, references, and a baseline shell that can navigate to each MFE. Include standard solution folders (/src, /tests, /build, /docs). Configure Blazor Server for the Shell, server-hosted Blazor projects for MFEs, and reference Shared.UiComponents.Blazor + Shared.Contracts where appropriate. Add a minimal home page in Shell that lists and routes to MFEs. Add a dev README with run commands.

Implementation Notes

Create solution: dotnet new sln -n ConnectSoft.MFE.Poc
Projects:
- Shell.BlazorServer → dotnet new blazorserver
- Mfe.Identity.SelfService.Blazor → dotnet new blazorserver (server-hosted MFE for POC simplicity)
- Mfe.Identity.Admin.Blazor → same as above
- Shared.UiComponents.Blazor → dotnet new razorclasslib (EnableRazorRuntimeCompilation if needed)
- Shared.Contracts → dotnet new classlib (net9.0)
- Bff.Api → dotnet new web (web API)
References:
- Shell → references both MFEs, Shared.UiComponents.Blazor, Shared.Contracts
- MFEs → reference Shared.UiComponents.Blazor, Shared.Contracts
- BFF → reference Shared.Contracts
Shell routes:
- /identity/self → Mfe.Identity.SelfService.Blazor pages
- /identity/admin → Mfe.Identity.Admin.Blazor pages

Acceptance Criteria

Solution builds locally with dotnet build and runs Shell with dotnet run (or VS F5).
Shell home page lists links to Self-Service and Admin MFEs; navigation works.
Shared.UiComponents.Blazor and Shared.Contracts referenced by both MFEs without build warnings.
A top-level README.md documents how to run Shell and MFEs in dev.

Definition of Done

All projects added to .sln/.slnx and grouped under /src.
Restore/build succeeds CI-locally (no external infra).
Basic routing to MFEs proven in the browser.

2) MFE-POC-F1-T2 — Tailwind & Flowbite toolchain bootstrap¶

Description Integrate TailwindCSS + PostCSS and Flowbite (and/or Flowbite Blazor wrappers) for consistent styling. Add npm scripts to watch/build CSS, wire content purge for Blazor .razor/.cshtml/.html files, and ensure styles load in the Shell and MFEs. Document required Node version and commands.

Implementation Notes

At solution root (or /src/Shell.BlazorServer), add frontend toolchain:
- package.json with scripts: dev, build, watch
- tailwind.config.js with content including **/*.razor, **/*.cshtml, **/*.html, **/*.js
- postcss.config.js with tailwindcss, autoprefixer
Install packages: tailwindcss, postcss, autoprefixer, flowbite
Add @tailwind base; @tailwind components; @tailwind utilities; to a shared stylesheet (e.g., /src/Shell.BlazorServer/wwwroot/css/app.tailwind.css).
Import Flowbite via JS in _Layout/index.html for Shell, ensure MFEs inherit.
Ensure purge keeps Flowbite classes used by components; add safelist if needed.
Optional: add Flowbite.Blazor (wrapper library) and wire sample component in Shell.

Acceptance Criteria

Running npm run dev (or equivalent) produces Tailwind CSS and live reload in dev.
Flowbite components render correctly in a Shell demo page (e.g., buttons, alerts).
Verified purge removes unused CSS (bundle size visibly reduced after build).
README.md updated with Node version and commands (Windows/Linux/macOS examples).

Definition of Done

Tailwind/Flowbite styles load across Shell and MFEs.
No blocking CSP/style errors in browser console.
Purge configuration includes Blazor file patterns.

3) MFE-POC-F1-T3 — Shared UI components starter pack¶

Description Create a starter pack of reusable components in Shared.UiComponents.Blazor to standardize layout and interactions across MFEs. Components include: PageLayout, Toolbar, Breadcrumbs, Alert, BusyOverlay (spinner/overlay), and a Shell demo/Story page showcasing variants. Components should be Tailwind/Flowbite-styled with minimal props for extensibility.

Implementation Notes

PageLayout with header slot, toolbar slot, content section; responsive container.
Toolbar with left/right action areas; supports child content and buttons (Flowbite styles).
Breadcrumbs with items collection; aria attributes for accessibility.
Alert supporting Info|Success|Warning|Error; optional dismiss; icon slot.
BusyOverlay full-page and section-only modes; z-index above content; non-blocking option.
Add a DemoComponents.razor page in Shell consuming all above with varied props.
Keep no direct business logic in UI components; only styling/props/events.

Acceptance Criteria

Both MFEs use at least three shared components in their pages.
Shell demo page renders all components with visible variants.
No duplicate CSS; components follow Tailwind/Flowbite classes and responsive patterns.
Basic accessibility verified (landmark roles, aria labels on breadcrumbs/alerts).

Definition of Done

Shared.UiComponents.Blazor packs and restores cleanly.
Components are documented in the Shell demo page (inline usage notes).
MFEs compile and render with shared components without extra CSS hacking.

Out of Scope for Cycle 1 (tracked for later cycles)¶

ASP.NET Core Identity full flows (only minimal placeholders allowed).
OpenTelemetry/Serilog, health checks, localization, SignalR, and app services (coming in next cycles).
CI pipelines (only local build/run instructions required in this cycle).

Identity Split into MFEs¶

Feature: MFE-POC-F2 — Identity Self-Service MFE¶

Feature Description End-to-end self-service flows using standard .NET 9 Identity API endpoints under /account (via app.MapGroup("/account").MapIdentityApi<TUser>()). Pages: Sign In, Register, Forgot/Reset Password, Profile (view/update). UI lives in the Self-Service MFE, server operations go through the BFF host exposing the Identity endpoints. Use shared UI components and Shell navigation.

Description Implement Blazor pages and Shell navigation for user self-service:

Sign In (email, password, remember me),
Register (email, password + confirm, basic profile fields),
Forgot Password / Reset Password (email → token form),
Profile (view & update; link to change password form).

Use shared components (PageLayout, Alert, BusyOverlay, Breadcrumbs, form inputs) and add basic client-side validation. Logged-in users should be redirected away from login/register to Profile.

Implementation Notes

Pages & routes (under Self-Service MFE):
/identity/self/login, /identity/self/register, /identity/self/forgot, /identity/self/reset, /identity/self/profile.
Call standard Identity endpoints from the UI:
POST /account/register, POST /account/login, POST /account/forgotPassword, POST /account/resetPassword,
GET /account/manage/info (profile read), POST /account/manage/info (update),
(Optionally) GET /account/confirmEmail, POST /account/resendConfirmationEmail.
Wire Shell nav (header/menu) to Self-Service routes; show/hide menu items based on auth state.
Use shared Alert for success/error; show busy overlay during submissions.
Add redirect logic: if authenticated → go to /identity/self/profile; if unauthenticated → show login/register.

Acceptance Criteria

All pages render, validate, and submit; navigation works from Shell.
Success and error messages appear via shared Alert; loading feedback via BusyOverlay.
Authenticated users are redirected away from login/register to profile.
Breadcrumbs correctly reflect page hierarchy.

Definition of Done

No direct Identity model usage in UI; only typed DTOs/requests.
Input fields have client-side validation; password confirmation checks work.
Minimal screenshots or README snippets show each page and flow.

2) MFE-POC-F2-T2 — BFF endpoints for self-service (standard Identity API)¶

Description Adopt the built-in Identity API endpoints (no custom routes) by mapping:

app.MapGroup("/account").MapIdentityApi<AppUser>();

Keep our Shared.Contracts client models for UI binding, but the network calls target /account/*. Support cookie-session mode for Blazor (preferred for POC); token mode is optional.

Implementation Notes

Endpoint set to rely on (no duplication):
Auth: POST /account/register, POST /account/login, POST /account/logout
Password: POST /account/forgotPassword, POST /account/resetPassword
Profile: GET /account/manage/info, POST /account/manage/info
Email: GET /account/confirmEmail, POST /account/resendConfirmationEmail
(Optional) 2FA endpoints under /account/manage/2fa/* for future cycles
Error handling: let Identity endpoints return RFC 7807 ProblemDetails; surface these in UI Alert.
DTOs: UI request/response models live in Shared.Contracts; map as needed for binding (do not change server contracts).
Test helpers: create a small dev utility to dump a sample ProblemDetails to aid UI parsing during development.

Acceptance Criteria

Happy path works: register → login → GET manage/info → POST manage/info.
Errors (duplicate email, invalid credentials, invalid token) appear as ProblemDetails and render in UI.
No custom re-implementation of Identity routes; only standard /account/* used.

Definition of Done

README includes the endpoint list and example curl for register, login, manage/info.
Unit tests for UI service layer (at least: success + invalid credentials).
No Identity internals (e.g., IdentityResult) leaked to MFEs.

3) MFE-POC-F2-T3 — Cookie/session & antiforgery wiring¶

Description Use cookie-based authentication for the browser experience. Configure secure cookies and antiforgery for state-changing forms. Ensure session lifecycle UX (login → profile; logout clears cookie; session-expired redirects to login).

Implementation Notes

Cookie/session:
Configure cookie auth in BFF host with HttpOnly, SecurePolicy=Always, SameSite=Lax, sliding expiration.
For login: call /account/login in cookie mode (if your template provides flags, respect them), otherwise rely on the default cookie issuance behavior of Identity endpoints.
Implement /account/logout call from UI to clear cookies.
Antiforgery:
Enable antiforgery services and add tokens to forms (hidden input) in Blazor; validate on server for mutating endpoints (profile update, password reset).
Ensure AJAX/fetch requests carry the antiforgery header when needed (if you expose non-form JSON posts).
Access control:
Protect Profile route in UI; unauthenticated users redirected to login.
Show session-expired banner and re-login link when 401 encountered.

Acceptance Criteria

Successful login sets an auth cookie observed in browser dev tools; profile is accessible afterward.
CSRF protections verified: missing/invalid token causes 400/403 and never mutates state.
Logout clears cookie and returns the user to a non-auth view; navigating to profile then redirects to login.

Definition of Done

README has a short manual test script (login → profile → update → logout → try profile again).
Security headers don’t block cookie/session (CSP/connect-src compatible with your earlier cycle).
No sensitive fields appear in logs; cookie name/value not logged.

Feature: MFE-POC-F3 — Identity Admin MFE¶

Feature Description Administrator-facing flows to list/search users, create/disable/lock/unlock, and manage roles & claims. UI lives in the Admin MFE; server operations are exposed from the BFF under /api/v1/admin/* and secured by policies/roles (RequireAdmin, ManageUsers, ManageRoles). Use shared UI components and enforce route/view guards so only authorized admins see the module.

1) MFE-POC-F3-T1 — Admin UI & policy-guarded routes¶

Description Build Blazor pages for Users and Roles with server-driven paging/sorting/filtering. Provide CRUD affordances through drawers/modals (create user, edit basics, assign roles/claims, disable/lock). Guard routes and menus with authorization so non-admins cannot access or even see the admin entry points.

Implementation Notes

Routes & Navigation
Admin MFE routes:
- /identity/admin/users (grid + actions)
- /identity/admin/roles (grid + actions)
- Shell menu shows “Admin” only for principals satisfying RequireAdmin (via AuthorizeView).
- Unauthorized direct navigation redirects to an Access Denied page.
Users Page
Grid with columns: Email, Display Name, Roles (comma), Status (Active/Disabled/Locked), Last Sign-In, Actions.
Server paging/sorting/search (email/role/status).
Actions (per row): Edit, Assign Roles, Lock/Unlock, Disable/Enable, Reset Password (token generation flow), Impersonate (stubbed; disabled by default).
Edit drawer: email (read-only), display name, phone (optional), notes; save/cancel.
Assign Roles modal: multiselect of existing roles.
Lock/Unlock modal: lockout end date/time + reason (stored as claim/note).
Roles Page
Grid with Role Name, Users Count, Actions.
Create Role modal, Rename (optional), Delete (guard if users exist; show impact).
Manage Claims per role (simple key/value list).
Shared Components
Use PageLayout, Toolbar, Breadcrumbs, Alert, BusyOverlay, confirmation dialogs, toast service (from previous cycles).
Inline validation with shared form components; show ProblemDetails messages in Alert.
UX Details
Long-running actions show BusyOverlay; on success, show toast and refresh row.
Confirmation dialogs for destructive ops (delete role, disable user, lock user).
A small “Audit” badge linking to a read-only change log (table populated later; for now, log ID/correlation in toast).

Acceptance Criteria

Non-admin users cannot see Admin menu and are blocked (403/Access Denied) from /identity/admin/*.
Users grid supports search, sort, and paging; actions operate via modals/drawers and reflect results without full-page reload.
Roles grid supports create/delete and claim editing with validation & confirmations.
Success/error states surface via shared Alert/toast; busy states visible during operations.

Definition of Done

Authorization is enforced both in UI (guards) and on server (policies).
No Identity internals bound in UI; only Shared.Contracts DTOs used.
README includes short admin UI tour (screenshots optional) and a role/permission matrix.

2) MFE-POC-F3-T2 — Admin BFF endpoints¶

Description Expose policy-protected admin endpoints under /api/v1/admin/* for user and role management. Implement input validation with FluentValidation and return ProblemDetails on errors. Ensure idempotent semantics for enable/disable/lock/unlock. Keep DTOs in Shared.Contracts and do not leak Identity entities.

Implementation Notes

Authorization
AddAuthorization with policies:
- RequireAdmin (Role = Admin),
- ManageUsers, ManageRoles (subset policies if you want finer control).
- Annotate endpoints with [Authorize(Policy="...")].
Users
GET /api/v1/admin/users — paged list (query: page, pageSize, search, role, status, sortBy, sortDir).
GET /api/v1/admin/users/{id} — details.
POST /api/v1/admin/users — create user (email, temp password or invite flow).
PUT /api/v1/admin/users/{id} — update profile basics.
POST /api/v1/admin/users/{id}/roles — set roles (replace or add/remove per payload).
POST /api/v1/admin/users/{id}/lock — lock with optional untilUtc + reason; idempotent.
POST /api/v1/admin/users/{id}/unlock — unlock; idempotent.
POST /api/v1/admin/users/{id}/disable / POST /api/v1/admin/users/{id}/enable — soft disable/enable.
POST /api/v1/admin/users/{id}/reset-password — issue reset token (email step can be stubbed for POC).
Roles
GET /api/v1/admin/roles — list.
POST /api/v1/admin/roles — create.
DELETE /api/v1/admin/roles/{roleName} — delete (guard if in use).
GET /api/v1/admin/roles/{roleName}/claims — list role claims.
POST /api/v1/admin/roles/{roleName}/claims — set/replace role claims.
DTOs (in Shared.Contracts)
UserListItemDto, UserDetailsDto, CreateUserRequest, UpdateUserRequest.
SetUserRolesRequest { List<string> Roles; Mode: Replace|AddRemove }.
LockUserRequest { DateTime? UntilUtc; string? Reason }.
PagedResult<T> { IEnumerable<T> Items; int Total; int Page; int PageSize; }.
RoleDto, CreateRoleRequest, RoleClaimDto, SetRoleClaimsRequest.
Validation & Errors
FluentValidation for create/update/roles/lock requests.
Common error mapping: duplicate email/role → 409; not found → 404; invalid input → 400; forbidden → 403.
Always return RFC 7807 application/problem+json.
Observability & Events
Emit structured logs with correlation IDs.
Publish lightweight events (e.g., UserRoleChanged, UserLockedOut) to the internal bus; SignalR notifies clients (from earlier cycle).

Acceptance Criteria

Admin endpoints return expected results; 403 when caller lacks required policy.
Users endpoint supports server-side paging/sorting/search and returns PagedResult<UserListItemDto>.
Role assignment changes are persisted and reflected in Users grid after refresh.
Lock/Unlock and Disable/Enable endpoints are idempotent (repeated calls keep consistent state).
Errors surface as ProblemDetails with clear titles and validation messages.

Definition of Done

Postman (or .http) examples for each endpoint included in /docs or README.
Unit tests for validators and a couple of controller tests (happy + failure).
No direct EF/Identity types leak to responses; only Shared.Contracts DTOs.

AuthN/AuthZ Integration¶

Feature: MFE-POC-F4 — Authentication & Authorization Backbone¶

Feature Description Integrate ASP.NET Core Identity with proper stores and password/lockout/sign-in options; expose minimal auth endpoints in Bff.Api under /api/auth/*; enable cookie-based sessions for the Shell/MFEs; and enforce role/policy-based authorization with MFE-aware guards (menus/routes/pages reflect permissions).

1) MFE-POC-F4-T1 — ASP.NET Core Identity setup¶

Description Wire Identity services and persistence (Sqlite for POC or Entity Framework), configure secure cookies, and expose minimal auth endpoints. Seed Admin and User accounts for demo. Ensure MFEs recognize the session and can read the current principal via /api/auth/me.

Implementation Notes

Persistence & Identity
AddDbContext<AppDbContext>(Sqlite); AddIdentityCore<AppUser>() or AddIdentity<AppUser, AppRole>().
AddEntityFrameworkStores<AppDbContext>(); add UserManager, SignInManager.
Configure PasswordOptions, LockoutOptions, UserOptions, SignInOptions (lockout on failures).
Cookies & AuthN
AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme).AddCookie(...).
Cookie settings: HttpOnly=true, SecurePolicy=Always, SameSite=Lax, sliding expiration, short dev lifetime.
Path settings (optional): LoginPath, AccessDeniedPath.
Minimal endpoints (keep these)
POST /api/auth/register (email, password, profile basics)
POST /api/auth/login (email, password) → issue auth cookie
POST /api/auth/logout → clear cookie
GET /api/auth/me → principal info (id, email, roles/claims)
Contracts & Seeding
Map to Shared.Contracts: RegisterRequest, LoginRequest, AuthUserDto.
Dev-only seeding for: admin@demo.local (Admin), user@demo.local (User) + baseline roles.
Security & Hygiene
Mask credentials from logs; never log cookies or tokens.
Return RFC 7807 ProblemDetails for validation/auth failures.

Acceptance Criteria

Register → Login works; users persist (Sqlite file) across restarts.
Auth cookie/session is issued and recognized by Shell + MFEs.
/api/auth/me returns principal with roles/claims.
Lockout triggers after configured failed attempts and resets per policy.

Definition of Done

No PII in logs; redaction list covers Authorization, Cookie, Password.
README includes a manual test script (register → login → navigate MFEs).
Basic unit tests for register/login happy-path and invalid-credentials path.

2) MFE-POC-F4-T2 — Role/Policy model & MFE guards¶

Description Define roles and policies and enforce them both server-side (BFF) and client-side (Shell/MFEs). Ensure menus, links, and routes reflect permissions and unauthorized navigation shows Access Denied without leaking data.

Implementation Notes

Roles & Policies
Roles: Admin, Manager, User.
Policies: RequireAdmin (Role=Admin), ManageUsers, ManageRoles (role/claim-based).
services.AddAuthorization(options => { options.AddPolicy("RequireAdmin", p => p.RequireRole("Admin")); ... }).
Server Enforcement (BFF)
Annotate endpoints with [Authorize(Policy="...")].
Public endpoints remain [AllowAnonymous] where needed.
Client Enforcement (Shell/MFEs)
Use CascadingAuthenticationState and AuthorizeView for menu visibility.
Implement route/page guards: check AuthenticationState in OnParametersSetAsync (or wrapper) → redirect to Access Denied or Login.
Add /access-denied page; unify UX for 401/403 from API calls (toast + redirect).
Docs & Matrix
Add a policy matrix to README: Role → Accessible Pages/Endpoints.
Example: Admin (Self-Service + Admin), Manager (subset of Admin pages), User (Self-Service only).

Acceptance Criteria

Admin-only endpoints/pages return 403 for non-admins; admin menu hidden for non-admins.
Manager has access to configured pages but not Admin-only ones.
User accesses only self-service; attempting admin routes shows Access Denied.
Direct navigation to blocked routes never leaks data (no partial renders with sensitive info).

Definition of Done

Policy names centralized; MFEs do not hard-code role strings in multiple places.
Manual test matrix (Admin/Manager/User) documented and passes (UI + API).
At least one integration test confirms 403 for a non-admin calling an admin endpoint.

API/BFF & Contracts¶

Feature: MFE-POC-F5 — BFF/API Gateway for MFEs¶

Feature Description Establish a thin BFF façade that fronts all UI→server calls for MFEs, with centralized contracts, input/output validation, consistent ProblemDetails errors, and API versioning. Group routes by functional area to keep identity/admin concerns clean and discoverable.

1) MFE-POC-F5-T1 — Contract definitions & filters¶

Description Finalize request/response DTOs in Shared.Contracts (e.g., LoginRequest, RegisterRequest, UserDto, RoleDto, ProblemErrorDto). Add FluentValidation validators per input model and wire global filters/middleware to return RFC 7807 ProblemDetails for validation/domain errors. Ensure BFF endpoints only accept/return these DTOs (no entity leakage).

Implementation Notes

Project layout
Namespaces: /Contracts/Auth, /Contracts/Identity, /Contracts/Admin.
Common base types: PagedResult<T>, ProblemErrorDto, SortDirection.
Validation & problem details
Add FluentValidation; services.AddValidatorsFromAssemblyContaining<...>().
Map validation exceptions and known domain errors to RFC 7807 via ProblemDetails middleware.
Normalize error keys to property names used by the DTOs (so UI binds directly).
Endpoint input/output discipline
Controllers/minimal APIs accept only DTOs; return DTOs or ProblemDetails.
Add action filters or minimal-API filters to reject unexpected content types.
Testing
Unit tests for validators (happy/invalid), and one pipeline test confirming a 400 with populated errors.

Acceptance Criteria

All BFF endpoints accept only Shared.Contracts DTOs and return DTOs or ProblemDetails.
Invalid inputs return 400 with errors keyed by DTO property names.
Contracts compile into a single assembly used by Shell + MFEs + BFF.

Definition of Done

No EF/Identity entities appear in any API signature or response.
Validator coverage exists for key inputs (login, register, create-user, assign-role).
README includes a sample 400 ProblemDetails payload and guidance for UI binding.

2) MFE-POC-F5-T2 — BFF routing & versioning¶

Description Introduce API Versioning via URL segments (e.g., /api/v1/...), group endpoints by area—auth, identity, admin—and expose a minimal Swagger (OpenAPI) for discoverability. Include auth endpoints from earlier cycles under /api/v1/auth.

Implementation Notes

Versioning
Add Microsoft API Versioning (Asp.Versioning.Http) with URL segment strategy.
Default version = 1.0; require explicit version in URLs.
Endpoint groups
MapGroup("/api/v{version:apiVersion}/auth") → register/login/logout/me.
MapGroup("/api/v{version:apiVersion}/identity") → self-service/profile operations.
MapGroup("/api/v{version:apiVersion}/admin") → admin users/roles endpoints.
Swagger/OpenAPI
Minimal Swagger with tags per group; try-it-out enabled for Development only.
Include schema examples for common DTOs and ProblemDetails.
Client usage & docs
Update MFEs’ API clients to call only versioned routes.
README “breaking changes” note for future v2 evolution (route table and deprecation guidance).
Testing
One test asserting /api/v1/... resolves while /api/... (no version) fails per chosen strategy.

Acceptance Criteria

Swagger available at /swagger; endpoints appear under grouped tags with version v1.
Requests without a version are rejected or redirected per documented strategy.
MFEs call only /api/v1/... routes in service classes.

Definition of Done

Endpoint grouping is visible in Swagger tags.
README contains sample curl for auth, identity, admin calls (with /api/v1/...).
Versioning middleware covered by a test asserting correct routing for v1.

Observability (Logging & Telemetry)¶

Feature: MFE-POC-F6 — Logging & OpenTelemetry¶

Feature Description Add structured logging (Serilog) and OpenTelemetry traces/metrics/logs with OTLP exporters across Shell, MFEs, and BFF. Ensure end-to-end correlation (W3C Trace Context + baggage), consistent redaction, and a minimal verification guide (dashboards/readme).

1) MFE-POC-F6-T1 — Serilog + correlation IDs¶

Description Configure Serilog in Shell and BFF with JSON console + rolling-file sinks for dev, consistent message templates, and enrichers that include trace_id, span_id, user_id (if authenticated), mfe_name, and environment. Add structured request/response logging with header/body limits and a strict redaction list (cookies, auth headers, passwords, tokens). Map Microsoft logs to Serilog and tune noisy namespaces.

Implementation Notes

Serilog bootstrap
Add UseSerilog() in Program; JSON console sink + rolling file sink under ./logs in Dev.
Enrichers: FromLogContext, custom middleware to push UserId, MfeName, Environment.
Populate trace_id / span_id from Activity.Current.
Request/response logging
ASP.NET Core request logging with size caps; redact Authorization, Cookie, and any fields like password, refresh_token.
Log schema: timestamp, level, message, trace_id, span_id, user_id, mfe_name, source_context, status_code, duration_ms.
Policies & levels
MinimumLevel.Override["Microsoft"] = Warning (tune per need), detailed for our namespaces.
Dev-only file sink; prod-ready pathway documented (e.g., send to collector or external sink later).
Docs & guardrails
Add README section with one sample log line and the redaction list.
Add a lightweight unit test (or analyzer) asserting redaction keys are present.

Acceptance Criteria

Logs consistently include trace_id/span_id; user_id appears after login.
Sensitive headers/fields are never logged; payloads respect size limits.
Changing ASPNETCORE_ENVIRONMENT adjusts levels/sinks as documented.

Definition of Done

README contains a short manual script: “login → navigate MFEs → view logs → verify correlation fields/redaction”.
A unit/static test validates the redaction keys are configured (and fails if removed).

2) MFE-POC-F6-T2 — OpenTelemetry end-to-end¶

Description Instrument Shell, MFEs, and BFF with OpenTelemetry Traces, Metrics, and Logs. Export via OTLP (HTTP or gRPC) to an OTel Collector, enable W3C Trace Context propagation and baggage (e.g., tenant, edition reserved for future), and add a few semantic spans & meters for core flows. Bridge Serilog with OTel so logs carry correlation IDs.

Implementation Notes

BFF instrumentation
AddOpenTelemetry() with ResourceBuilder (set service.name, service.version, deployment.environment).
Add AspNetCore, HttpClient, SqlClient (if EF used), Runtime, Process, and custom Meters.
OTLP exporter configured via env vars (e.g., OTEL_EXPORTER_OTLP_ENDPOINT).
Shell/MFEs instrumentation
Enable Activities in server-hosted Blazor pipeline so HTTP calls from MFEs to BFF propagate traceparent/tracestate.
Wrap key UI actions with custom spans where useful.
Propagation & baggage
Use TraceContextPropagator + BaggagePropagator; pass through any known baggage keys even if unused now.
Custom spans & metrics
Spans: Identity.Login, Admin.AssignRole with status/tags (userId masked/hashed).
Metrics: counter identity.logins.count, histogram api.request.duration (ms), counter api.request.errors.
Logs correlation
Enable OTel logs bridge to ensure Serilog entries include trace_id/span_id.
Collector & docs
Provide a minimal Collector config (local dev): receives OTLP, prints traces/metrics/logs to console.
README: env vars, how to run the Collector, and how to view data; add a troubleshooting section (certs, proxies, WebSockets).

Acceptance Criteria

End-to-end traces visible for at least two flows: login and admin role change (UI → BFF → DB if present).
Metrics emitted (requests, latency, error rate) and visible via the Collector or local view.
At least one log record correlates to a trace (trace_id matches).
If Collector is down, apps keep running and exporters back off (no crashes).

Definition of Done

README includes: env vars, Collector run instructions, how to verify headers (traceparent), and example commands/screenshots.
Troubleshooting notes exist (exporter errors, SSL, proxy, header not present).
A small .http/Postman file or script to generate sample traces (login, role change) is included under /docs or /tools.

Health Checks & Readiness¶

Feature: MFE-POC-F7 — Health, Liveness, Readiness¶

Feature Description Expose /health (overall), /ready (readiness), and /live (liveness) endpoints with targeted checks for Identity store, BFF, and SignalR. Add a Shell UI status badge and details modal. Gate readiness until startup work (migrations, caches, SignalR hub) completes.

1) MFE-POC-F7-T1 — Health endpoints & UI indicator¶

Description Add ASP.NET Core HealthChecks to Shell and BFF with endpoint segmentation:

/live — process liveness (light checks: process, thread pool, GC).
/ready — readiness for traffic (DB connectivity, BFF loopback, SignalR hub).
/health — combined overview (dashboard-friendly JSON).

Return JSON with status, entries, and duration. Implement a Shell status badge (shared component) that polls /health and shows green/amber/red; clicking opens a modal with per-check details and timestamps. Provide an optional fail-fast flag to terminate on critical missing deps at boot.

Implementation Notes

Registration
services.AddHealthChecks()
- Identity store: EF DbContext health check (or raw connection check).
- BFF loopback: HTTP probe to /api/v1/auth/me (anonymous or special probe header).
- SignalR: hub handshake/negotiate probe or internal hub state check.
- Optional: ProcessHealthCheck, WorkingSet, ThreadPoolQueueLength.
- Endpoints
app.MapHealthChecks("/live", new HealthCheckOptions { Predicate = r => r.Name == "liveness" ... })
app.MapHealthChecks("/ready", new HealthCheckOptions { Predicate = IsReadinessCheck ... })
app.MapHealthChecks("/health", new HealthCheckOptions { ResponseWriter = WriteJson ... })
Ensure JSON includes status, entries[name].status, entries[name].duration, entries[name].description.
UI
Shared HealthStatusBadge component: polls /health (configurable interval), colors: Healthy=green, Degraded=amber, Unhealthy=red.
Details modal lists checks with status icons, duration, last updated; link to raw JSON.
Security / Ops
No secrets in responses; optionally require auth for /health (but allow LB/monitor allowlist).
Fail-fast: if FailFastOnCritical=true, stop app when DB unavailable at startup.

Acceptance Criteria

/live, /ready, /health return 200/503 appropriately with JSON payloads showing individual check statuses.
Status badge in Shell header/footer reflects current /health and opens details modal.
Disabling DB or BFF causes /ready to return 503 while /live stays 200.
With fail-fast enabled, critical dependency failure during startup stops the app.

Definition of Done

Health endpoints follow best practices (no secrets; allowlist/optional auth).
README includes endpoint docs, sample curl outputs, badge wiring notes, and guidance for Kubernetes probes / Azure App Service health checks.

2) MFE-POC-F7-T2 — Startup warmup & gated health¶

Description Introduce a startup warmup gate so readiness flips to Healthy only after:

DB migrations (if enabled) complete,
critical caches (e.g., roles/permissions map) are primed,
SignalR hub is ready to accept connections.

Add an IHostedService to run warmup steps and set an internal readiness flag; add a custom readiness health check that reports Unhealthy until the flag is set. Ensure /live is independent of warmup while /ready depends on it. Log the warmup sequence with timings; on failure, keep /ready Unhealthy and (optionally) stop the app.

Implementation Notes

Warmup service
StartupWarmupService (background hosted service):
- Run EF migrations (feature-flagged).
- Prime caches (e.g., roles/policy maps).
- Ping/initialize SignalR hub or internal hub services.
- Set WarmupState.Ready = true when complete.
- Gated readiness
WarmupGateHealthCheck returns Unhealthy until WarmupState.Ready is true.
Add this check to the /ready pipeline.
Logging & failure
Log milestones with durations: “Migrations complete”, “Caches primed”, “SignalR ready”, “Readiness gate opened”.
On failures: log root cause; if FailFastOnWarmupFailure=true, stop the app.
Separation of concerns
/live must not depend on warmup gate; only /ready should.

Acceptance Criteria

Immediately after start, /ready is Unhealthy; after warmup, it flips to Healthy without restart.
Logs show ordered milestones with timings.
On any warmup step failure, /ready remains Unhealthy; optional fail-fast terminates the process if configured.

Definition of Done

Warmup is idempotent across restarts and respects config flags (e.g., RunMigrations=false).
README documents flags, expected timings, and troubleshooting (migration timeout, SignalR negotiation failures).

Localization & UX¶

Feature: MFE-POC-F8 — Localization & Theming¶

Feature Description Enable i18n for MFEs and Shared UI components; add a culture switcher that persists user preference; verify RTL layout; ensure Flowbite/Tailwind theming and dark mode across Shell + MFEs.

1) MFE-POC-F8-T1 — Localization infrastructure¶

Description Add ASP.NET Core localization with IStringLocalizer and .resx resources for Shell, Mfe.Identity.SelfService.Blazor, Mfe.Identity.Admin.Blazor, and Shared.UiComponents.Blazor. Wire culture providers (querystring, cookie, Accept-Language), and add a culture switcher UI (header dropdown). Persist selection to a cookie so subsequent visits load the chosen culture. Localize shared components (Alert labels, Breadcrumb aria text, etc.) and key Identity pages (Sign in/up, Profile).

Implementation Notes

services.AddLocalization(options => options.ResourcesPath = "Resources");
app.UseRequestLocalization() with supported cultures (e.g., en-US, he-IL); order providers: CookieRequestCultureProvider first, then QueryStringRequestCultureProvider, then Accept-Language.
Create per-project resource folders; use strongly-typed localizers where helpful for shared component strings.
Header culture dropdown: updates the request-culture cookie (and optionally querystring for deep links).
Ensure date/number formatting and validation messages respect the active culture.
Add sample localized content for: buttons, alerts, breadcrumbs, form labels/placeholders, validation messages.

Acceptance Criteria

UI strings localize for at least two languages across Shell and both MFEs.
Changing culture from the header persists across reloads/new tabs and is reflected in routes/pages immediately.
Validation messages and date/number formats reflect the selected culture.

Definition of Done

README lists supported cultures, fallbacks, resource file layout, and how to add a new language.
Basic a11y covered: aria labels/roles localized in shared components; language attribute/culture metadata set on <html>.

2) MFE-POC-F8-T2 — Theming & dark mode¶

Description Implement Tailwind dark mode with a theme toggle that persists preference (localStorage or cookie). Verify Flowbite components render correctly in both modes. Validate RTL support for at least one meaningful page (e.g., Login or Users list) by switching dir="rtl" when an RTL culture is active; ensure spacing, icon directionality, and breadcrumbs align correctly.

Implementation Notes

Tailwind: set darkMode: 'class' in tailwind.config.js; apply/remove class="dark" on <html>/<body> from a shared theme service.
Theme toggle component in Shell header persists preference; initializes early (before first paint) to avoid flicker.
Flowbite: verify contrast states and dynamic classes; safelist dark variants if purge strips them.
RTL: set dir="rtl" when culture is RTL; prefer logical utility classes (ps-, pe-, text-start/end, float-start/end) over left/right; ensure breadcrumb chevrons and icons mirror.
Add a simple Theme & RTL demo page showcasing common components in light/dark and LTR/RTL.

Acceptance Criteria

Dark/light toggle flips entire Shell + MFEs without layout glitches; preference persists across reloads.
Flowbite components (buttons, alerts, dropdowns, modals) display correctly in light and dark modes.
An RTL page renders without broken alignment/overflow; toolbar/breadcrumb alignment and icon direction are correct.

Definition of Done

README documents theme persistence strategy, how to extend theme tokens, and RTL considerations.
“Theme & RTL demo” page exists and demonstrates components across light/dark and LTR/RTL.

Real-Time & Inter-MFE Communication¶

Feature: MFE-POC-F9 — SignalR & MFE Communication¶

Feature Description Use SignalR for real-time notifications (e.g., user lockout changes, role updates) and define patterns for inter-MFE pub/sub via the BFF. Provide a consistent client wiring package for Shell + MFEs, plus event contracts in Shared.Contracts.

1) MFE-POC-F9-T1 — SignalR hub & client wiring¶

Description Create a notifications hub at /hubs/notifications in the Shell/BFF host, wire authenticated clients from Shell and both MFEs, and surface a shared toast component when events are received. Support user-scoped and role-scoped notifications with resilient reconnection.

Implementation Notes

Hub & Auth
Add NotificationsHub : Hub and secure with [Authorize].
Implement IUserIdProvider using ClaimTypes.NameIdentifier.
In OnConnectedAsync, add connections to:
- user group: $"user:{userId}"
- role groups: $"role:{roleName}" for each role.
Client wiring
Create SignalRClient helper (shared) with:
- automatic reconnect + backoff,
- handshake logging,
- cookie-auth flow for same-origin,
- event subscription registry (On<TEvent>(handler)).
- Add ToastService + Toast component in Shared.UiComponents.Blazor and register in Shell + MFEs.
Server methods
Hub methods (invoked by server only):
- NotifyUser(userId, payload),
- NotifyUsers(userIds, payload),
- NotifyRole(role, payload),
- Broadcast(payload).
- Keep payloads as DTOs from Shared.Contracts (no PII; include correlation id).
Resilience & Backplane
Optional feature flag to enable Redis/SQL backplane later (interface stable).
Log connect/disconnect, retries, and negotiated transports for troubleshooting.

Acceptance Criteria

Performing an admin action (e.g., change a user’s role) as Admin triggers a real-time toast in Self-Service MFE.
Client reconnects transparently after network hiccups (no page refresh).
Unauthorized clients fail to connect (401/403) and see a friendly UI message.

Definition of Done

README explains client setup, sending a test message, and common issues (WebSockets disabled, proxy, CORS).
No PII in messages; payloads are Shared.Contracts DTOs with correlation ids.

2) MFE-POC-F9-T2 — Inter-MFE event contracts¶

Description Define a minimal event model in Shared.Contracts (e.g., UserRoleChanged, UserLockedOut, ProfileUpdated). Publish events from BFF application services and subscribe in MFEs via a lightweight in-process event bus that forwards to SignalR. Provide per-MFE opt-in handlers.

Implementation Notes

Contracts
Base:
```
interface IAppEvent { 
  string Name; 
  DateTime OccurredUtc; 
  string CorrelationId; 
}
```
* Concrete DTOs (minimal fields):
- UserRoleChanged { string UserId; string[] Roles; }
- UserLockedOut { string UserId; DateTime? UntilUtc; string? Reason; }
- ProfileUpdated { string UserId; string[] ChangedFields; }
Publishing
In BFF app-services, publish events after successful operations (respect transaction boundary).
Event bus (IEventBus) dispatches to registered handlers, including SignalRNotificationsHandler.
Subscribing
MFEs register interest (e.g., Self-Service subscribes to UserLockedOut, Admin subscribes to UserRoleChanged).
Provide a per-MFE subscription map to avoid cross-UI noise.
UI handlers format user-friendly toast text from DTOs (no secrets).
Versioning & Observability
Version event payloads if fields may evolve.
Log publish/dispatch with correlation id; include span/trace ids when available.

Acceptance Criteria

Changing a user’s role in Admin MFE produces UserRoleChanged: BFF publishes → SignalR hub → Self-Service MFE receives → toast shows human-readable message.
MFEs can opt out; unsubscribed MFEs do not receive the event.
Event payloads are DTOs (no entity leakage) and include CorrelationId.

Definition of Done

README contains an Event Catalog (event name, payload fields, producers, subscribers) and example payloads.
Basic tests: publisher raises event → handler invoked → SignalR dispatcher called with correct DTO.

Application Services & Security Hardening¶

Feature: MFE-POC-F10 — Application Services & Security Baseline¶

Feature Description Introduce a clean application service layer that mediates MFEs → BFF → Identity (ASP.NET Core Identity), centralizing business rules, validation, and transaction boundaries. Establish a security baseline: strict headers, HSTS, and a CSP compatible with Tailwind/Flowbite and SignalR—avoiding unsafe-inline when possible (nonce/hash if needed). Document decisions and provide tests.

1) MFE-POC-F10-T1 — Application services abstraction¶

Description Create IIdentityAppService (and implementation) in the BFF’s application layer to encapsulate identity use-cases: register, login, logout, get current user, change/reset password, manage roles/claims, lock/unlock user. Use Shared.Contracts DTOs, perform FluentValidation + business checks, map errors to ProblemDetails, and keep controllers/endpoints thin. Include unit tests (happy/error) and one minimal end-to-end integration path.

Implementation Notes

Project layout
Add Application/ (or separate class library) with Services, Validators, Mappers, Errors.
Interfaces: IIdentityAppService with async methods returning DTOs or a Result<T> type.
Policies & validation
Centralize role/permission checks in the service (in addition to [Authorize] on controllers).
FluentValidation for all public requests (register, login, change password, assign role).
Transactions & mapping
Wrap multi-step writes in a unit-of-work/transaction scope.
Keep EF/Identity entities internal; map strictly to Shared.Contracts.
Error handling
Normalize Identity error codes → stable error keys/messages; return RFC 7807 ProblemDetails.
Tests
Unit: register (ok/duplicate email), login (ok/invalid password), change password (ok/invalid current).
Integration: /api/v1/auth/register → /api/v1/auth/login → /api/v1/auth/me happy path.

Acceptance Criteria

MFEs call BFF → IIdentityAppService → Identity successfully for register, login, change password, assign role.
Controllers contain orchestration only; no business rules.
Errors return ProblemDetails with stable codes; no Identity internals leaked.
Tests pass; README documents service surface and error code mapping.

Definition of Done

Clear layering: Controllers → AppService → Identity (stores/managers).
No EF/Identity types exposed to controllers/MFEs.
Validation and policy checks live in the app layer (not duplicated in endpoints).

2) MFE-POC-F10-T2 — Security headers & CSP¶

Description Apply a hardened HTTP security baseline to Shell and BFF: HSTS (prod), X-Content-Type-Options, X-Frame-Options/frame-ancestors, Referrer-Policy, Permissions-Policy, and a Content-Security-Policy that works with Tailwind/Flowbite and SignalR. Prefer nonces/hashes over unsafe-inline. Ensure SignalR WebSockets/long-polling are allowed by CSP/CORS as needed. Add troubleshooting notes for reverse proxies and local dev.

Implementation Notes

Headers
Strict-Transport-Security: max-age=31536000; includeSubDomains (prod only).
X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer.
X-Frame-Options: DENY or CSP frame-ancestors 'none'.
Permissions-Policy to restrict camera/mic/geolocation/etc.
CSP (tune per app)
default-src 'self';
script-src 'self' 'nonce-{RANDOM}' (add nonce to scripts in layout; Flowbite init runs with nonce).
style-src 'self' 'nonce-{RANDOM}' (or 'sha256-...' for built CSS); avoid unsafe-inline.
img-src 'self' data:; font-src 'self' data:.
connect-src 'self' https://localhost:* wss://localhost:* (BFF fetch/XHR + SignalR WebSocket).
frame-ancestors 'none'; base-uri 'self'; object-src 'none';
SignalR & CORS
Allow wss: and https: to /hubs/notifications; verify cookie SameSite and CSP don’t block negotiation.
If future cross-origin MFEs are required, add a dev-only CORS policy (keep POC same-origin).
Tooling & verification
Optional CSP violation report endpoint to log blocked URIs during hardening.
Provide nonce generation helper/tag helper; document how to add nonce to Flowbite/inline bootstrap scripts.

Acceptance Criteria

Responses include intended security headers (verified via devtools or curl).
CSP passes with light/dark themes and Flowbite interactions; no unexpected violations in normal flows.
SignalR connects under CSP and real-time toasts render.
Any unavoidable inline script/style uses nonce/hash (no unsafe-inline).

Definition of Done

README includes final CSP, nonce application steps, and common fixes (e.g., WebSocket blocked, missing connect-src).
Dev vs Prod differences documented (HSTS off in dev; CSP reports optional in dev).
A simple automated check in CI fails if required headers are missing on /health (or another known endpoint).

Packaging, CI, and Demo Scenario¶

Feature: MFE-POC-F11 — CI Basics, Packaging, and Demo Data¶

Feature Description Add a minimal Azure DevOps pipeline to restore, build, test, and pack the shared libraries. Publish build artifacts for quick consumption. Seed demo users/roles and provide a concise walkthrough script that proves login, role change, real-time toast, locale switch, and health page.

1) MFE-POC-F11-T1 — Minimal CI pipeline & packing¶

Description Create an Azure DevOps YAML pipeline that:

Sets up .NET SDK (9.0), Node (for Tailwind build), and caching for NuGet & npm.
Restores, builds, and runs tests for the full solution.
Packs Shared.UiComponents.Blazor and Shared.Contracts as NuGet packages (or zipped artifacts) with SemVer from build number.
Publishes artifacts (drop/, packages/) and (optional) adds build/test badges to the repo README.

Implementation Notes

Stages/Jobs
build: dotnet restore, dotnet build -c Release (includes Node/Tailwind build for web projects).
test: dotnet test --collect:"XPlat Code Coverage"; publish TRX + coverage.
pack: dotnet pack src/Shared.UiComponents.Blazor -c Release -o $(Build.ArtifactStagingDirectory)/packages /p:VersionSuffix=$(Build.BuildNumber) (same for Shared.Contracts).
publish: PublishBuildArtifacts@1 for drop/ (compiled Shell/BFF) and packages/.
Tasks & caching
UseDotNet@2 (SDK 9.x), NodeTool@0 (LTS).
Cache@2 for ~/.nuget/packages and $(Build.SourcesDirectory)/**/node_modules.
DotNetCoreCLI@2 (restore, build, test, pack).
Quality bars
Fail on test failures; ContinueOnError: false.
Optional TreatWarningsAsErrors=true for shared libs.
Variables
BuildConfiguration=Release, VersionSuffix=$(Build.BuildNumber) (or derive from tag).
Repo setup
Pipeline YAML at repo root: /azure-pipelines.yml.
README badges (optional) for build & tests.

Acceptance Criteria

Pipeline passes on a clean repo with a single YAML file at root.
Test results and (if enabled) coverage appear in the run summary.
Artifacts include packages/Shared.UiComponents.Blazor.*.nupkg, packages/Shared.Contracts.*.nupkg (or zipped), and a drop/ containing compiled Shell/BFF.
Optional build/test badges render in README.

Definition of Done

README section “How CI works” shows the local command matrix: dotnet restore, dotnet build -c Release, dotnet test, dotnet pack.
CI fails fast on warnings-as-errors for shared libraries (if enabled).
Node/Tailwind build runs during build and is included where needed.

2) MFE-POC-F11-T2 — Demo data & walkthrough script¶

Description Add a demo seed routine and a short walkthrough showing the end-to-end story:

Seed roles: Admin, Manager, User.
Seed users: admin@demo.local (Admin), manager@demo.local (Manager), user@demo.local (User) with known passwords (documented).
Seed a couple of “sample events” (optional) to replay via SignalR for verification.
Write README_DEMO.md with a 5–7 minute script that covers:
Login as Admin → open Admin MFE (users list).
Change a user’s role → Self-Service MFE receives real-time toast.
Switch language to the second locale → see localized UI & validation.
Toggle dark mode → verify Flowbite/Tailwind styles.
Open /health → verify healthy; optionally kill DB to see /ready fail.

Implementation Notes

Seeding
Implement as an idempotent IHostedService (Development only unless explicitly enabled).
Store demo passwords + seed flag in User Secrets or appsettings.Development.json.
Ensure multiple runs do not duplicate users/roles (check-before-create).
Demo helpers
Add a dev-only “Demo Control” page to trigger a sample SignalR notification.
Provide .http or Postman collection under /docs for quick API checks.
Docs
README_DEMO.md with screenshots (optional), expected outcomes, and cleanup steps.
Troubleshooting: cookies, CSP, CORS, WebSockets, antiforgery, health endpoints.

Acceptance Criteria

Fresh clone + run (Dev config) seeds roles/users; first login succeeds with documented credentials.
Walkthrough steps work verbatim—no manual data prep needed.
On role change, a SignalR toast appears in Self-Service; locale & dark mode toggles persist across reloads.

Definition of Done

README_DEMO.md exists with clear steps, accounts, and notes; links from root README.
Seeding can be disabled via config; re-running does not duplicate data.
Troubleshooting section covers common pitfalls (cookies, CSP, CORS, WebSockets).

Blazor UX Hardening & UI Enhancements¶

Feature: MFE-POC-F12 — Blazor UI/UX Baseline Extensions¶

Feature Description Strengthen the UI layer of the Blazor microfrontend POC with accessibility compliance, density/theming toggles, and a live component gallery. Add adapters validation to ensure Flowbite and design-token-based rendering remain consistent. This cycle focuses solely on Blazor and UI improvements without backend expansion.

1) MFE-POC-F12-T1 — Accessibility & Density Controls¶

Description Augment shared components with first-class a11y: ARIA attributes, semantic roles/landmarks, focus management, and keyboard navigation (Tab/Shift+Tab, Enter/Space to activate, Esc to dismiss). Introduce global density modes (Compact, Comfortable, Spacious) that adjust spacing/line-height via utility classes/tokens and persist the user’s preference.

Implementation Notes

Accessibility
Apply roles/labels: role="dialog" + aria-modal="true" for modals; aria-live="polite" for toasts; aria-current for breadcrumbs.
Focus management: focus first interactive element on open; trap focus within dialogs; return focus to opener on close.
Keyboard maps: buttons/links respond to Enter/Space; Esc closes dialogs, dropdowns, and toasts (when appropriate).
Visible focus rings: Tailwind utilities for strong focus outline (meets WCAG AA contrast).
Density system
Define density design tokens (padding, gap, line-height, min-heights).
Provide a DensityService with Get/SetDensity(); store in localStorage and broadcast via cascading parameter to MFEs.
Update shared components to apply density classes (e.g., data-density="compact|comfortable|spacious" on root with CSS variables or Tailwind variants).
Docs
Add an accessibility checklist and a density usage section to the component README.

Acceptance Criteria

All interactive controls show visible focus rings and pass WCAG AA for focus + contrast.
Toggling density updates shared components immediately and persists across reloads.
Screen readers correctly announce modal/open/close and toasts/alerts with appropriate ARIA attributes.

Definition of Done

Axe or similar a11y scan shows no critical violations on the demo pages.
Keyboard-only navigation can fully operate dialogs, dropdowns, and toasts.
Unit/UI tests (where feasible) assert focus trap and Esc-to-close for dialogs.

2) MFE-POC-F12-T2 — Blazor Gallery & Storybook Mode¶

Description Create a /gallery route inside the Shell that showcases shared components (buttons, alerts, layouts, modals, toolbars, breadcrumbs). Each component has at least one interactive story with controls (props) and live preview. Provide copy-to-clipboard usage snippets and toggles for theme (light/dark), density, and locale.

Implementation Notes

Gallery scaffolding
/gallery page with a left nav of components and a main preview area.
“Knobs” panel: booleans, selects, text inputs that bind to component parameters.
Code tab: renders the minimal usage snippet; copy button provided.
Global toggles
Top bar controls for theme (light/dark), density, and locale (ties into existing services).
Ensure toggles apply to the preview iframe/area and the page chrome consistently.
Coverage
At least one story per: Button, Alert, Modal/Dialog, PageLayout, Toolbar, Breadcrumbs, BusyOverlay.
Perf & dev UX
Lazy-load previews to keep initial load snappy.
Add dotnet run instructions to launch gallery with hot reload.

Acceptance Criteria

Gallery runs via dotnet run and lets users tweak props live.
Each showcased component has at least one story with code snippet copy.
Theme/density/locale toggles apply instantly to previews and persist across reloads.

Definition of Done

README section “Using the Gallery” with screenshots/GIF (optional).
No console errors; hot reload works for gallery pages and components.
Minimal smoke tests ensure gallery route renders and toggles function.

3) MFE-POC-F12-T3 — Adapter QA Kit¶

Description Build a lightweight QA/test harness for UI kit adapters (FlowbiteAdapter, TokensAdapter) to ensure parity for core interactions (modals, dropdowns, toasts, form validation). Integrate tests into CI so adapter regressions block merges.

Implementation Notes

Harness
A dedicated test page (or small test project) that renders the same scenarios twice: once per adapter.
Scenarios: dialog open/close (Esc, backdrop click, primary action), dropdown keyboard nav, toast auto-dismiss timing, form validation messages.
Parity tests
Assert consistent focus behavior, ARIA attributes, and event sequences across adapters.
Validate toast duration and stacking rules; ensure consistent z-index layering.
Automation
Add Playwright (or bUnit + JS interop checks) smoke tests to run in CI.
Report differences clearly (which adapter/scenario failed).
Docs
Add an “Adapter Expectations” table: feature → expected behavior → constraints/notes.

Acceptance Criteria

Adapters pass tests: keyboard handling, Esc-close, focus trap, toast timing/stacking.
Any adapter failure fails CI for shared components.
Documentation updated with parity expectations, known deviations, and how to add tests.

Definition of Done

CI job executes the adapter QA suite headlessly and publishes results.
Local README explains how to run the harness and interpret failures.
No adapter leaks inline styles/scripts that break CSP from the security cycle.

EPIC: MFE-POC — Blazor Microfrontend POC (Identity + Cross-Cutting)¶

Solution & Libraries Scaffolding¶

Feature: MFE-POC-F1 — Solution Skeleton & Libraries¶

1) MFE-POC-F1-T1 — Create multi-project solution structure¶

2) MFE-POC-F1-T2 — Tailwind & Flowbite toolchain bootstrap¶

3) MFE-POC-F1-T3 — Shared UI components starter pack¶

Out of Scope for Cycle 1 (tracked for later cycles)¶

Identity Split into MFEs¶

Feature: MFE-POC-F2 — Identity Self-Service MFE¶

1) MFE-POC-F2-T1 — Self-Service UI & navigation¶

2) MFE-POC-F2-T2 — BFF endpoints for self-service (standard Identity API)¶

3) MFE-POC-F2-T3 — Cookie/session & antiforgery wiring¶

Feature: MFE-POC-F3 — Identity Admin MFE¶

1) MFE-POC-F3-T1 — Admin UI & policy-guarded routes¶

2) MFE-POC-F3-T2 — Admin BFF endpoints¶

AuthN/AuthZ Integration¶

Feature: MFE-POC-F4 — Authentication & Authorization Backbone¶

1) MFE-POC-F4-T1 — ASP.NET Core Identity setup¶

2) MFE-POC-F4-T2 — Role/Policy model & MFE guards¶

API/BFF & Contracts¶

Feature: MFE-POC-F5 — BFF/API Gateway for MFEs¶

1) MFE-POC-F5-T1 — Contract definitions & filters¶

2) MFE-POC-F5-T2 — BFF routing & versioning¶

Observability (Logging & Telemetry)¶

Feature: MFE-POC-F6 — Logging & OpenTelemetry¶

1) MFE-POC-F6-T1 — Serilog + correlation IDs¶

2) MFE-POC-F6-T2 — OpenTelemetry end-to-end¶

Health Checks & Readiness¶

Feature: MFE-POC-F7 — Health, Liveness, Readiness¶

1) MFE-POC-F7-T1 — Health endpoints & UI indicator¶

2) MFE-POC-F7-T2 — Startup warmup & gated health¶

Localization & UX¶

Feature: MFE-POC-F8 — Localization & Theming¶

1) MFE-POC-F8-T1 — Localization infrastructure¶

2) MFE-POC-F8-T2 — Theming & dark mode¶

Real-Time & Inter-MFE Communication¶

Feature: MFE-POC-F9 — SignalR & MFE Communication¶

1) MFE-POC-F9-T1 — SignalR hub & client wiring¶

2) MFE-POC-F9-T2 — Inter-MFE event contracts¶

Application Services & Security Hardening¶

Feature: MFE-POC-F10 — Application Services & Security Baseline¶

1) MFE-POC-F10-T1 — Application services abstraction¶

2) MFE-POC-F10-T2 — Security headers & CSP¶

Packaging, CI, and Demo Scenario¶

Feature: MFE-POC-F11 — CI Basics, Packaging, and Demo Data¶

1) MFE-POC-F11-T1 — Minimal CI pipeline & packing¶

2) MFE-POC-F11-T2 — Demo data & walkthrough script¶

Blazor UX Hardening & UI Enhancements¶

Feature: MFE-POC-F12 — Blazor UI/UX Baseline Extensions¶

1) MFE-POC-F12-T1 — Accessibility & Density Controls¶

2) MFE-POC-F12-T2 — Blazor Gallery & Storybook Mode¶

3) MFE-POC-F12-T3 — Adapter QA Kit¶