AIFACTORY-FEAT-167: Blazor shell template: gateway adapters, filter diagnostics and pinned packages before the Studio¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Ecosystem component extensions · Increment I3 Studio · State elaborated · Route frontend-developer · Phase before development · Build order 31 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I3 are developed. The mark travels with every task (tag phase:before-development).
Factory Studio is a Blazor shell composed of microfrontends behind StudioBff (ADR-0007). The shell template's own runtime backlog (docs/Control Plane) records what the Studio would otherwise inherit: the named ApiGateway client has host adapters for products and entitlements only, while the tenant list, feature flags, notifications and activity still fall back to in-memory or deny-all; a hidden navigation entry cannot be explained (OP-025: a filter result of false does not say whether a flag, an entitlement, a missing tenant or a gateway failure caused it); and the UIKit and Shell.Services pins drift between the shell, the microfrontend library and the sample templates (the integration checklist). Component: Blazor Shell + MFEs + UIKit (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-blazor-shell adrs: ADR-0007, ADR-0015 |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, ConnectSoft.Blazor.ShellTemplate/docs/Control Plane/Index.md, ConnectSoft.Blazor.ShellTemplate/docs/OP-025-Shell-Navigation-Filter-Diagnostics.md, ConnectSoft.Blazor.MicrofrontendLibraryTemplate/docs/INTEGRATION-VALIDATION-CHECKLIST.md |
AIFACTORY-US-319: Blazor shell template: host adapters fill tenants, flags, notifications and activity from a configured gateway, fail closed, and each gateway client holds its own token¶
enabling · persona asset-maintainer
As an asset maintainer, I want the shell template to fill its switchers, flags, notifications and activity from a gateway when authentication is on, so that a shell built from the template shows real scope and real notices without a hand-written adapter per product.
The runtime backlog of the shell template (the Control Plane index of its documentation) records the state the Studio would inherit: the named HTTP client ApiGateway with GatewayAccessTokenHandler and a correlation handler has host adapters for products and entitlements only, while the tenant list, the feature flags, the notifications and the activity have no source and fall back to in-memory data or deny everything. Its locked decisions say where the missing adapters belong: package defaults stay in-memory or null, HTTP adapters are host overrides when authentication is enabled, they live in the host and not in types a microfrontend can reach, the switcher items reuse ShellScopeItem, a gateway failure fails closed, and the template gains no company symbol. This PBI adds the four missing host adapters under those decisions, so the template stays generic and gains no Factory parameter; a product binds them by configuration. Each adapter reads a route the host configures for the gateway client; an adapter without a configured route keeps the in-memory or null default, so the template invents no notification backend. With authentication on, a 401, a 403 or an unreachable gateway yields no extra tenants and denied flags, with the reason logged and never a token or a header value. A 404 for an item means the item belongs to another tenant and is left out without an error; a 403 means the token lacks a scope inside the tenant and denies with that reason. A user token has one audience, the gateway that fronts its scopes: the token handler requests the token for the audience of the gateway its named client fronts, so a host that calls a second gateway registers a second named client with its own token and never sends a token to a gateway it was not issued for. With authentication off the shell keeps its in-memory demo data.
Acceptance criteria
| AC1 | Given a shell generated from the template with authentication on and routes configured for tenants, flags, notifications and activity, when a user opens the shell, then the switchers list the tenant, project and environment items the gateway returns as ShellScopeItem, the flags, notifications and activity come from the gateway, and no adapter type is reachable from a microfrontend assembly (ADR-0007: microfrontends share the auth context of the shell; model/services/factory-studio/StudioBff.yaml is the gateway the Studio configures). |
| AC2 | Given the gateway answers 401 or 403 or is unreachable, when the shell loads its scope and flags, then no extra tenant is listed, flags and entitlements deny, the reason is logged and no log line holds a token or a header value; given 404 for an item, then the item is left out without an error, as the amendment of ADR-0015 on a resource of another tenant prescribes. |
| AC3 | Given a host with two named gateway clients, when both are called in one session, then each request carries a token whose audience is the gateway of its client and no token is sent to the other gateway (ADR-0015 amendment on the token audience: one audience per user token). |
| AC4 | Given a shell with authentication off, or an adapter whose route is not configured, when the shell renders, then it shows the in-memory demo data or the null default of today and calls no gateway (ADR-0007, model/template-parameters/connectsoft-blazor-shell.yaml gains no parameter by this PBI). |
| Traces: adrs | ADR-0007, ADR-0015 |
| Traces: services | StudioBff |
| Sources | model/components.yaml, model/template-parameters/connectsoft-blazor-shell.yaml, model/services/factory-studio/StudioBff.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1375 Route configuration of the four adapters and the audience of a named gateway client |
contract | The configuration section of the gateway client defines one route key each for the tenant list, the feature flags, the notifications and the activity and an audience per named gateway client; the Control Plane index, the gateway route catalog and the Auth and Gateway runbook of the template describe the keys, the fail-closed rule and the meaning of 404 and 403. | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-610 Gateway adapters for tenants, feature flags, notifications and activity (B-F01 to B-F03) |
implementation | The shell populates its tenant, project and environment switchers, flags, entitlements, notifications and activity from the named gateway client when authentication is on, as host overrides that reuse ShellScopeItem; it fails closed on 401, 403 or a gateway outage with the reason logged and never a token or header value, leaves out an item answered 404, requests one token per gateway audience, and keeps the in-memory data of the auth-off demo mode and of an adapter without a route. |
ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-1376 Gateway stub with the success, refusal, foreign-tenant and outage cases |
fixture | The unit test project of the shell holds a gateway stub with the cases 200, 401, 403, 404 for one item and connection failure, a second stub for a second named client that records the audience of every token it receives, and a log capture that fails a test when a token or a header value is written. | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-1377 Verify the adapters, the fail-closed rule and the token per gateway |
verification | Run the adapter tests against the stubs of AIFACTORY-TASK-1376 with authentication on and off; the gateway data is shown, the refusals deny, the 404 item is absent and each stub sees only tokens of its own audience, which proves AC1 to AC4 of AIFACTORY-US-319 (ADR-0015). | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-US-335: Blazor shell service packages: an optional evaluation contract and one evaluation core return the visible entries with their reasons, published to the ConnectSoft feed with a version¶
enabling · persona asset-maintainer
As an asset maintainer, I want the shell service packages to return the reasons of the navigation filter from the same evaluation that yields the visible entries, so that the shell template pins one published version of each package and explains a hidden entry without a copy of the filter.
The repositories ConnectSoft.Blazor.Shell.Services.Abstractions and ConnectSoft.Blazor.Shell.Services belong to this component and are used as packages (D115; model/components.yaml lists both under cmp-blazor-shell). Their pages state the split. The abstractions package holds the interfaces a microfrontend may depend on, among them IShellNavigationFilter, the flag and entitlement filter that does not evaluate RequiredPolicy. The services package holds the host defaults that AddShellServices registers with TryAdd, among them ShellNavigationFilter, NullFeatureFlagService and NullEntitlementContext, and a microfrontend never references it. The diagnostics backlog page of the shell template (OP-025 in its documentation) records what the filter does today: it keeps the entries whose flag and entitlement pass, checks a nonblank feature flag first and returns before the entitlement check when the flag fails, sorts by group order, order and identifier, and returns the visible subset only, so a caller cannot tell why an entry is missing. The second part of that page asks for an optional compatible diagnostic contract, a default filter refactored around one evaluation core, and a proof of parity and of call counts. This PBI delivers that part. The abstractions package gains an optional evaluation contract beside IShellNavigationFilter: one call returns the visible subset and, for every candidate, the outcome of its flag check and of its entitlement check with the explanations of the page, PassesFilter, FeatureFlagNotEnabled, EntitlementNotGranted and NotEvaluated, extended by the causes the page says a result of false hides: the null provider, no selected tenant and a gateway failure. A provider may state why it denied through an optional part of the contract; a provider that states nothing yields the plain flag or entitlement explanation. An entry with a host policy only passes, with host authorization reported as not evaluated. The services package gains the evaluation core: Filter and the evaluation run the same code, so the visible subset, the order, the short circuit and the number of provider calls are those of today, and existing callers of Filter compile unchanged. The null providers state the null provider, and a denial while ITenantContext holds no tenant is reported as no selected tenant. A filter that a host registered before AddShellServices stays the one resolved; when it does not implement the contract, the evaluation says that no explanation is available and replaces nothing. An explanation holds the identifiers of the entry, of the flag and of the entitlement and never a token or a header value. Where an explanation may be shown is a rule of the host and belongs to AIFACTORY-US-320. Publication is part of this PBI, although the backlog page left it out: the pipeline of the abstractions repository publishes first, the services repository pins that version and publishes second, each to the ConnectSoft feed with a version that is not yet on the feed. The pins of the shell template are the reference of the family, so the microfrontend library template follows them under the pin check of AIFACTORY-US-321.
Acceptance criteria
| AC1 | Given the six rows of the explanation matrix of the backlog page (no requirement, flag false, entitlement false, both declared with the flag false, both allowed, host policy only), when one evaluation of the services package runs, then the visible subset equals the result of Filter in content and order and every candidate carries its explanation: PassesFilter, FeatureFlagNotEnabled, EntitlementNotGranted, the entitlement NotEvaluated after a failed flag, and a pass with host authorization not evaluated for the policy row (ADR-0007: the shell composes the modules of the Studio; model/components.yaml names the filter diagnostics as a need of this component). |
| AC2 | Given the null providers of AddShellServices, a tenant context without a tenant, and a provider that states a gateway failure through the optional part of the contract, when the evaluation runs, then the explanation names the null provider, the missing tenant or the gateway failure, a provider that states nothing yields the plain flag or entitlement explanation, and no explanation holds a token or a header value (ADR-0007; model/components.yaml lists both repositories under cmp-blazor-shell). |
| AC3 | Given the existing callers of Filter and a host that registers its own IShellNavigationFilter before AddShellServices, when they build and run against the new versions, then the callers compile unchanged, the order, the short circuit and the number of calls to each provider equal those before the change, RequiredPolicy is not evaluated, the filter of the host stays the one resolved, and an evaluation over a filter without the contract reports that no explanation is available (ADR-0007, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md). |
| AC4 | Given the unit tests of both repositories are green, when their pipelines run, then the abstractions package is pushed to the ConnectSoft feed with a version that is not on the feed, the services package pins that version and is pushed with a version of its own that is not on the feed, a probe project with the ConnectSoft feed as its only source restores both and resolves the evaluation from AddShellServices, and the abstractions package holds no reference to the services package (ADR-0007: the modules share one shell contract that is maintained; model/components.yaml lists both repositories under cmp-blazor-shell). |
| Traces: adrs | ADR-0007 |
| Sources | model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1436 Optional evaluation contract of the navigation filter in the abstractions package |
contract | The abstractions package holds an optional evaluation contract beside the unchanged IShellNavigationFilter: one call that returns the visible subset and, per candidate, the outcome of the flag check and of the entitlement check with the explanations PassesFilter, FeatureFlagNotEnabled, EntitlementNotGranted and NotEvaluated, the causes null provider, no selected tenant and gateway failure, the mark that host authorization was not evaluated, and an optional part by which a flag or entitlement provider states why it denied; the Features page and the README of the repository list the contract. |
ConnectSoft.Blazor.Shell.Services.Abstractions |
AIFACTORY-TASK-1437 Abstractions package with the evaluation contract published to the ConnectSoft feed |
operations | The pipeline of the abstractions repository builds, tests, packs and pushes the package that carries the evaluation contract to the ConnectSoft feed with a version that is not yet on the feed, and the package of that version restores from the feed in a clean project. | ConnectSoft.Blazor.Shell.Services.Abstractions |
AIFACTORY-TASK-1438 Default navigation filter refactored around one evaluation core |
implementation | ShellNavigationFilter implements the evaluation contract around one evaluation core that Filter also runs, so the visible subset, the order, the short circuit and the provider calls are unchanged; NullFeatureFlagService and NullEntitlementContext state the null provider, a denial without a tenant in ITenantContext is reported as no selected tenant, a reason a provider states is passed through, and AddShellServices registers the evaluation with TryAdd so that a filter of the host stays authoritative; the central package file of the repository pins the abstractions version of AIFACTORY-TASK-1437. |
ConnectSoft.Blazor.Shell.Services |
AIFACTORY-TASK-1439 Explanation matrix, parity and call count tests of the evaluation core |
fixture | The unit test project of the services repository holds the six rows of the explanation matrix of the backlog page, extended by the null provider, the missing tenant and a provider that states a gateway failure; parity tests that compare the evaluation with Filter in content and order; counting providers that fail a test when a provider is called more often than before the change; and a host override case with a filter that does not implement the contract. |
ConnectSoft.Blazor.Shell.Services |
AIFACTORY-TASK-1440 Services package with the evaluation core published to the ConnectSoft feed |
operations | The pipeline of the services repository builds, tests, packs and pushes the package that carries the evaluation core to the ConnectSoft feed with a version that is not yet on the feed, after the abstractions version it pins is on the feed; the Features page and the README of the repository describe the evaluation and keep the rule that a microfrontend never references this package. | ConnectSoft.Blazor.Shell.Services |
AIFACTORY-TASK-1441 Verify the evaluation, the parity and the two published versions |
verification | Run the tests of AIFACTORY-TASK-1439 and restore the two published versions in a probe project whose only source is the ConnectSoft feed; every row shows its explanation, the evaluation equals Filter, no provider is called more often and the probe resolves the evaluation from AddShellServices, which proves AC1 to AC4 of AIFACTORY-US-335 (ADR-0007). |
ConnectSoft.Blazor.Shell.Services |
AIFACTORY-US-320: Blazor shell template: a developer can ask why a navigation entry or a command is hidden and gets the cause, in Development and by explicit opt-in only¶
enabling · persona asset-maintainer
As an asset maintainer, I want the shell to explain the decision of its navigation filter to a developer, so that a hidden work area of the Studio is diagnosed from the shell and not from logs.
The navigation filter of the shell keeps an entry when its feature flag and its entitlement both allow it, and the diagnostics backlog page of the template (OP-025 in its documentation) records the gap: a result of false does not say whether an unknown flag, a null provider, a missing grant, a cleared cache, a missing tenant or a gateway failure caused it, and an entry that never entered the candidate sequence cannot be labelled rejected. The page keeps the work behind a decision gate and fixes the contract: Filter stays source-compatible, one evaluation supplies both the visible subset and the reasons, the flag is checked before the entitlement, RequiredPolicy stays a concern of the host and is not evaluated by the filter, and diagnostics need both the Development environment and an explicit opt-in, also when the option is set in Production. The page splits the work in three parts: the adopter decision, the evaluation contract and evaluation core in the shell service packages, and the diagnostic surface in the template. This PBI covers the first and the third; the second is AIFACTORY-US-335 of this feature. The proceed decision is the one the owner took for the Studio (D99). It is recorded with the seven work areas filtered by role, flag and entitlement as the case, and with the plain statement that no observed behaviour exists, because the Studio is built after this feature and the page says that synthetic fixtures do not establish demand. Both surfaces, the navigation menu and the command palette, are recorded as selected. The second part is delivered by AIFACTORY-US-335: the repositories of the shell service abstractions and of the shell services belong to this component and are used as packages (D115), so the optional diagnostic contract and the single evaluation core are published from them to the ConnectSoft feed, each with a version. The template pins those two versions in its central package file and never copies a filter type. It binds the menu and the palette to the evaluation result of the packages, its host adapters state a gateway failure as the reason of a denial through the contract, and it renders the explanation for a developer: the entry passes, its flag is not enabled, its entitlement is not granted, a check was not evaluated because an earlier one failed, the provider is the null provider, no tenant is selected, or the gateway failed. In Production neither the view nor its payload exists.
Acceptance criteria
| AC1 | Given a template whose central package file pins the versions of the shell service packages that AIFACTORY-US-335 publishes, and a shell in Development with the diagnostic option on and entries hidden by a flag, by an entitlement, by a null provider, by a missing tenant and by a gateway failure, when a developer opens the diagnostic view, then every entry shows its own cause, an entry whose flag failed shows its entitlement as not evaluated, and the visible entries equal the result of the filter (ADR-0007: the shell composes the modules of the Studio; model/components.yaml names the filter diagnostics as a need of this component). |
| AC2 | Given a shell in Production with the diagnostic option set to true, or a shell in Development without the option, when it renders, then the diagnostic view is not registered, no response holds an explanation payload, and the names of rejected entries appear in no markup (ADR-0015 amendment on a resource of another tenant: what the scope of a caller does not cover is answered as absent; docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| AC3 | Given an entry that needs a host policy only, when it is evaluated, then the filter reports that it passes and that host authorization was not evaluated, the order and the short circuit of the filter are unchanged, existing callers of Filter compile unchanged and the template source holds no copy of a filter or evaluation type, and the central package file of the template pins the two versions that AIFACTORY-US-335 publishes, which restore from the ConnectSoft feed (ADR-0007, model/template-parameters/connectsoft-blazor-shell.yaml gains no parameter by this PBI). |
| Traces: adrs | ADR-0007, ADR-0015 |
| Depends on | AIFACTORY-US-319, AIFACTORY-US-335 |
| Sources | model/components.yaml, model/template-parameters/connectsoft-blazor-shell.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1378 Proceed decision, selected surfaces and the pinned package versions recorded on the backlog page |
documentation | The diagnostics backlog page of the template records the proceed decision of the owner for the Factory Studio (D99) with the seven work areas filtered by role, flag and entitlement as the case, states that no observed behaviour exists because the Studio is built after this feature, records that both surfaces, the navigation menu and the command palette, are selected, and carries the bounded contract: the causes a developer sees and the two exposure conditions. It names the evaluation contract and the evaluation core of the shell service packages, the two repositories that own them as repositories of this component (D115), and the two published versions of AIFACTORY-US-335 that the template pins. | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-611 Navigation filter diagnostics (OP-025) |
implementation | The central package file of the template pins the versions of the shell service abstractions and of the shell services that AIFACTORY-US-335 publishes, and the navigation menu and the command palette take their visible entries and the reasons from one evaluation of the packages; the host adapters of AIFACTORY-US-319 state a gateway failure as the reason of a denial through the contract; a developer can ask why an entry or command is hidden and gets the cause: the flag, the entitlement, a check not evaluated, the null provider, the missing tenant or a gateway failure; the view is registered only in Development with the explicit option and never in Production; the template source holds no copy of a filter type. | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-1379 Explanation matrix and exposure tests of the shell |
fixture | The unit test project holds the explanation matrix of the backlog page as component tests (open entry, flag false, entitlement false, both declared, both allowed, policy only) extended by the null provider, the missing tenant and the gateway failure, and exposure tests for Production with the option on and Development without it. | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-1380 Verify the explanations and the two exposure conditions |
verification | Run the tests of AIFACTORY-TASK-1379; every row of the matrix shows its cause, the visible entries equal the filter result and neither exposure case renders the view or a payload, which proves AC1 to AC3 of AIFACTORY-US-320 (ADR-0007). | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-US-321: Blazor shell family: a standalone microfrontend composes into the empty shell through its descriptor pair, and the UIKit and shell package pins are the same in every template¶
enabling · persona asset-maintainer
As an asset maintainer, I want one composition contract and one set of package pins across the shell template and the microfrontend library template, so that a microfrontend built from one template composes into a shell built from the other without a version conflict.
The shell template ships an empty microfrontend registry on purpose, and the integration validation checklist of the microfrontend library template describes how a microfrontend joins a shell: a static descriptor with its assembly and its navigation items, and one registration method the shell calls once; the shell aggregates the assemblies and the navigation and passes the assemblies to the router. The same checklist records a known pin drift: the empty shell template pins one version of the UI kit and of the shell services package while the library and the sample templates pin others, and a test locks the pins of the library so that nobody moves them alone. The Studio is a shell from one template composing microfrontends from the other, so a drift between them is a restore conflict in the Studio repository. This PBI verifies the contract and aligns the pins of the two templates the Studio is built from. A fixture microfrontend that follows the descriptor pair is composed into a shell generated from the template, and a test proves that its routes answer and its navigation items appear in order. The pins of the UI kit, of the shell contracts, of the shell service abstractions and of the shell services are made equal in the shell template and in the microfrontend library template. A pin check joins the shared template installer job of ConnectSoft.AzurePipelines as an optional step that is off by default: it compares the UI kit and shell package pins of the consuming template with the pins of the latest published shell template package, which is the one reference of the family, and fails on a difference. The shell template and the microfrontend library template switch it on for all four pins; a consumer may limit the comparison to the shell package pins, which the Studio does. The sample templates the checklist names, the Identity administration and self-service microfrontend templates, are other repositories outside this component: they keep their recorded pins, their pipelines do not run the check, and the checklist says so until their own work aligns them and switches it on. The Tokens, Flowbite and DaisyUI adapter repositories of the UI kit stay outside this component as well: the check compares no adapter pin and their pins stay as recorded. The architecture test that a microfrontend never references the shell services package runs in both templates.
Acceptance criteria
| AC1 | Given a shell generated from the template and a fixture microfrontend with a descriptor and a registration method, when the shell registers it and passes its assembly to the router, then the routes of the microfrontend answer and its navigation items appear in the order of their Order values (ADR-0007: each module of the Studio is a microfrontend composed into the shell; docs/architecture/adr/0007-blazor-mfe-studio-frontend.md). |
| AC2 | Given the central package files of the shell template and of the microfrontend library template, when they are compared, then the pins of the UI kit, the shell contracts, the shell service abstractions and the shell services are equal, and the pin test of the library template asserts the aligned values (ADR-0007: the modules share one design system; model/templates.yaml lists both templates). |
| AC3 | Given the shell template or the microfrontend library template, which switch the optional pin check of the shared installer job on, and a pin that differs from the pins of the latest published shell template package, when the pipeline runs, then the pin check fails with the package and both versions named, and a template pipeline that has not switched the check on, such as that of a sample template, runs as before; given a microfrontend project that references the shell services package, then the architecture test fails in either template (ADR-0007, model/components.yaml names aligned pins as a need of this component). |
| Traces: adrs | ADR-0007 |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-shell.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-612 Composition contract verified and pins aligned across the shell family |
contract | A fixture microfrontend composes into the empty shell through the {X}Mfe and Add{X}Mfe pair and its routes answer; the UIKit and shell package pins of the shell template are the reference of the family; the architecture test that a microfrontend never references the shell services package runs in the shell template. |
ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-1381 Pins of the microfrontend library template moved to the reference |
implementation | The central package file of the microfrontend library template pins the UI kit, the shell contracts, the shell service abstractions and the shell services at the versions of the shell template; the pin test IntegrationContractTests asserts the aligned values; the integration validation checklist states the aligned values of the two templates, names the latest published shell template package as the reference of the pin check, and records that the sample templates keep their own pins and do not run the check until their own work switches it on. |
ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1382 Pin check in the shared template installer job |
operations | The shared installer job template/dotnet-template-installer-job.yaml gains an optional step, off by default, that compares the UI kit and shell package pins of the consuming template with the pins of the latest published shell template package and fails with the package and both versions named; the shell template and the microfrontend library template switch it on for all four pins, a consumer may limit the comparison to the shell package pins, which the Studio does because its single central package file may adopt a newer published kit version, and a consumer that does not switch the step on is unchanged. |
ConnectSoft.AzurePipelines |
AIFACTORY-TASK-1383 Verify the composition, the equal pins and the pin check |
verification | Compose the fixture microfrontend into a generated shell, compare the pins of the two templates and run both pipelines with and without a planted differing pin; the routes answer, the pins are equal and the planted pin fails the check, which proves AC1 to AC3 of AIFACTORY-US-321 (ADR-0007). | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-US-322: Blazor shell template: the packed template is installed, instantiated, restored, built and tested, and a shell with a composed microfrontend answers, before the package publishes¶
evidence · persona asset-maintainer
As an asset maintainer, I want every change of the shell template to be gated by the shell it generates from the packed candidate, so that a package that would scaffold a shell that does not build, pass or start never reaches the feed.
This PBI is the gate of the feature. The installer pipeline file of the shell template (azure-pipelines-template.yml of the template) only calls the shared installer job of ConnectSoft.AzurePipelines, whose steps pack, validate one instantiation and push in one sequence; the template passes a smoke argument that skips the restore, so the generated shell is neither restored nor built there, and a repeated version is governed by the allowPackageConflicts parameter of the shared job. A gate between pack and push and a refusal of a repeated version therefore cannot be written in the file of the template. The smoke validation checklist of the template is a manual list in which the generation without tests is still unchecked. The gate rests on the shared installer steps and on the cases of the template. The gate hook and the version guard of the shared installer steps are delivered by AIFACTORY-TASK-1426 of the feature component-base-template-findings, in the first increment, because the template gates of the increments before this one already rely on the hook. The hook runs the generated cases of a consumer against the installed candidate after the pack and before the push. The version guard is opt-in and off by default: switched on, it refuses a version already on the feed, and allowPackageConflicts stays for a consumer that does not switch it on. The shell template switches the hook and the guard on and defines its cases in its scaffold test project. The default case and the case without the test project are instantiated, restored, built in Release and, where tests exist, tested, and each output is scanned for template placeholders that were not replaced. A composition case generates the shell, adds the fixture microfrontend, starts the host with authentication off and probes the home route and a route of the microfrontend. An adapter case starts the host with authentication on against the gateway stub and asserts the fail-closed behaviour. A case that fails any stage fails the run with the case and the stage named, and the push is not reached. Publication pushes the installer package to the ConnectSoft feed with a version that is not yet on the feed. The template gains no Factory profile, so no additional profile case is declared. This is an evidence PBI: a template feature has no scenario, so the gate names what it proves through traces.adrs and its sources.
Acceptance criteria
| AC1 | Given a change of the shell template, when its installer pipeline runs, then the candidate is packed once and installed, the default case and the case without tests are instantiated, restored, built in Release, tested and scanned, and the composition case starts the generated shell and gets an answer from the home route and from a route of the fixture microfrontend (ADR-0007; model/template-parameters/connectsoft-blazor-shell.yaml lists includeTests and skipRestore). |
| AC2 | Given a case fails any stage, when the pipeline evaluates the run, then the gate hook of the shared installer steps (AIFACTORY-TASK-1426) fails the run with the case and the stage named and the push step is not reached; a fixture with a planted failing case proves the refusal (ADR-0007, model/backlog/epics.yaml states the gate as the completion of the epic). |
| AC3 | Given every case is green, when the push step runs, then the installer package is pushed to the ConnectSoft feed with a version that is not on the feed, and the version guard of the shared installer steps, which the template switches on, refuses a repeated version with the reason (ADR-0007, docs/architecture/catalogs/templates.md keeps the row of the template). |
| Traces: adrs | ADR-0007 |
| Depends on | AIFACTORY-US-319, AIFACTORY-US-320, AIFACTORY-US-321, feature:component-base-template-findings |
| Sources | model/components.yaml, model/backlog/epics.yaml, model/template-parameters/connectsoft-blazor-shell.yaml, docs/architecture/catalogs/templates.md, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1384 Generated cases of the shell template passed to the gate hook of the shared installer steps |
operations | The scaffold test project of the shell template defines the default case, the case without tests, the composition case and the adapter case against the installed candidate, with restore and build instead of the smoke argument that skips the restore; the installer pipeline file of the template switches the gate hook and the version guard of AIFACTORY-TASK-1426 on and passes the hook these cases; the smoke validation checklist points at the cases. | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-1385 Planted failing case fixture for the gate |
fixture | A pipeline fixture generates the composition case with a microfrontend whose route is not registered and asserts that the run fails at the probe stage with the case named and that the publication stage is not reached. | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-1386 Verify the gate on a green run and on the planted run |
verification | One pipeline run with the four cases green reaches publication and one run with the planted case fails before it; both runs prove AC1 to AC3 of AIFACTORY-US-322 (ADR-0007). | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-US-125: Blazor shell template: gateway adapters, filter diagnostics and pinned packages before the Studio is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want Blazor Shell + MFEs + UIKit to carry gateway adapters, filter diagnostics and pinned packages before the Studio, so that it serves Factory Studio and generated product UIs without later rework.
This is the integration PBI of the feature. An asset maintainer packs the shell template with the four gateway adapters, the token per gateway client, the navigation filter diagnostics, the verified composition contract and the aligned pins, installs the package and runs its generated cases in the installer pipeline. Every generated shell restores, builds and passes its tests, and the composed shell answers, before the package is allowed to publish; a case that fails any stage fails the run and blocks publication. The implementation lives in the earlier PBIs of this file; this PBI proves them together on the shell the Studio is built from. From the published package a shell is generated and a standalone microfrontend is composed into it. With authentication on against a gateway stub it lists the scope items the gateway returns, denies on a refusal and leaves out an item of another tenant, and its pins equal those of the microfrontend library template. In Development with the diagnostic option it explains a hidden entry from the evaluation of the shell service packages that AIFACTORY-US-335 publishes and the template pins. The feature is done when that shell is generated from a fresh install of the published package. Repositories of the feature: ConnectSoft.Blazor.ShellTemplate, and ConnectSoft.Blazor.Shell.Services.Abstractions and ConnectSoft.Blazor.Shell.Services for the evaluation contract and the evaluation core; one task changes the microfrontend library template and one the shared pipeline tooling.
Acceptance criteria
| AC1 | Given the template repository ConnectSoft.Blazor.ShellTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution of every case builds and its tests pass before the package publishes with a verified version (ADR-0007, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-610 (gateway adapters for tenants, feature flags, notifications and activity) is done, then the shell populates its tenant, project and environment switchers, flags, entitlements, notifications and activity from the named gateway client when authentication is on, fails closed on 401, 403 or a gateway outage with the reason logged and never a token or header value, and keeps its in-memory data in the auth-off demo mode (ADR-0015 amendments on the token audience and on a resource of another tenant). |
| AC3 | Given the work of AIFACTORY-TASK-611 (navigation filter diagnostics) is done, which pins the versions of the shell service packages that AIFACTORY-US-335 publishes, then a developer can ask the shell why a navigation entry or command is hidden and gets the cause, the flag, the entitlement, the missing tenant, a null provider or a gateway failure, and the diagnostic is behind a development switch and never renders in production (ADR-0007, docs/architecture/ecosystem-composition.md). |
| AC4 | Given the work of AIFACTORY-TASK-612 (composition contract verified and pins aligned across the shell family) is done, then a standalone microfrontend composes into the empty shell through its descriptor pair and its routes answer, the UIKit and shell package pins are the same in the shell template and the microfrontend library template, both of which switch the optional pin check on, and the architecture test that a microfrontend never references the shell services package runs in both (ADR-0007, model/templates.yaml). |
| Traces: adrs | ADR-0007, ADR-0015 |
| Traces: services | StudioBff |
| Depends on | AIFACTORY-US-319, AIFACTORY-US-335, AIFACTORY-US-320, AIFACTORY-US-321, AIFACTORY-US-322 |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-shell.yaml, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1387 Generate a shell from the published package and compose a standalone microfrontend |
verification | A probe installs the published installer package, generates a shell, composes the fixture microfrontend, starts the host against the gateway stub with authentication on and in Development with the diagnostic option, and compares its pins with the microfrontend library template; the run proves AC2 to AC4 of AIFACTORY-US-125 on the published package (ADR-0007, ADR-0015). | ConnectSoft.Blazor.ShellTemplate |
AIFACTORY-TASK-676 Verify blazor-shell-template-studio-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the authoring solution and on every generated case after the published package is installed; they pass and prove AC1 to AC4 of AIFACTORY-US-125. |
ConnectSoft.Blazor.ShellTemplate |