Merge branch 'main' into feat/DC-115

Author: adbergen

.husky/pre-commit

@@ -93,12 +93,20 @@ if [ "$BACKEND_CHANGES" = "true" ]; then
 
   if command -v dotnet &> /dev/null; then
     # Verify code formatting matches .editorconfig (fails if changes needed)
-    dotnet format SEBT.Portal.sln --verify-no-changes --verbosity quiet || {
+    # Exclude sibling repos (state-connector, dc-connector, co-connector) that get
+    # pulled in via conditional ProjectReference but live outside this repository.
+    dotnet format SEBT.Portal.sln --verify-no-changes --verbosity quiet \
+      --exclude ../sebt-self-service-portal-state-connector/ \
+      --exclude ../sebt-self-service-portal-dc-connector/ \
+      --exclude ../sebt-self-service-portal-co-connector/ || {
       log_error ".NET code formatting check failed - run 'dotnet format SEBT.Portal.sln' to fix"
       exit 1
     }
-    
-    dotnet format SEBT.Portal.sln analyzers --verify-no-changes --verbosity quiet || {
+
+    dotnet format SEBT.Portal.sln analyzers --verify-no-changes --verbosity quiet \
+      --exclude ../sebt-self-service-portal-state-connector/ \
+      --exclude ../sebt-self-service-portal-dc-connector/ \
+      --exclude ../sebt-self-service-portal-co-connector/ || {
       log_error ".NET analyzer checks failed - fix the reported issues"
       exit 1
     }

docs/adr/0009-state-backend-health-checks-report-degraded.md

@@ -0,0 +1,29 @@
+# 9. State Backend Health Checks Report Degraded, Not Unhealthy
+
+Date: 2026-03-17
+
+## Status
+
+Accepted
+
+## Context
+
+State connector plugins register health checks that verify connectivity to their backend systems (DC's SQL database, CO's CBMS API). Initially these checks reported `Unhealthy` when the backend was misconfigured or unreachable. In ASP.NET Core's health check framework, the overall `/health` endpoint status is the worst individual check status — so a single `Unhealthy` check makes the entire endpoint report `Unhealthy`, which can cause container orchestrators to kill and replace the container.
+
+The portal can still serve requests (login, static pages, cached data) when a state backend is down. Recycling the container won't fix a downstream outage and can cascade into a worse situation.
+
+## Decision
+
+State connector health checks always report `Degraded` — never `Unhealthy` — regardless of whether the issue is missing configuration or an unreachable backend. The structured JSON response from `/health` includes per-check descriptions and exception details, so monitoring and alerting can still distinguish between misconfiguration and connectivity failures.
+
+### Alternatives considered
+
+- **Report `Unhealthy` for connectivity failures, `Degraded` for missing config.** More semantically precise, but the operational consequence (container recycling) is undesirable in both cases.
+- **Have connectors report `Unhealthy` but remap to `Degraded` at the portal level.** ASP.NET Core's overall status is the worst individual status with no built-in remapping. A portal-side wrapper could intercept results, but adds complexity for the same operational outcome.
+- **Make the failure status configurable via appsettings.** Flexibility for future states, but adds a configuration knob that would likely be set once and forgotten — and increases maintenance burden for state partners. Can revisit if needed as more states onboard.
+
+## Consequences
+
+- The `/health` endpoint never returns `Unhealthy` due to a state backend issue, preventing aggressive container recycling.
+- Monitoring must inspect the per-check details (description, exception) in the JSON response rather than relying solely on the top-level status to detect backend outages.
+- The portal's own health (e.g., its database) can still report `Unhealthy` if needed in the future — this decision applies only to state connector checks.

docs/adr/0009-vendor-agnostic-data-layer.md

@@ -0,0 +1,63 @@
+# 9. Vendor-Agnostic Privacy-Aware Data Layer
+
+Date: 2026-03-16
+
+## Status
+
+Accepted
+
+## Context
+
+The portal needs analytics and observability to understand user behavior, measure feature adoption, and support operational monitoring. Multiple analytics vendors (e.g., Mixpanel, Google Analytics, Adobe Analytics) may be used across different state deployments, and vendor choices may change over time. Directly integrating vendor SDKs throughout the codebase would create tight coupling, make vendor switches expensive, and risk leaking PII to vendors that should not receive it.
+
+We need a single, canonical source of truth for page metadata, user attributes, and tracked events that:
+
+- Decouples application code from any specific analytics vendor.
+- Enforces privacy scoping so PII is only accessible to authorized consumers.
+- Supports multiple concurrent vendor integrations without code changes.
+- Is understandable and maintainable by state partner agencies after handoff.
+
+## Decision
+
+We adopt a **vendor-agnostic data layer** following the [W3C Customer Experience Digital Data Layer (CEDDL)](https://www.w3.org/2013/12/ceddl-201312.pdf) recommendations. The implementation lives in `src/SEBT.Portal.Web/src/lib/data-layer.ts` as a framework-agnostic TypeScript class.
+
+**Canonical data structure** bound to `window.digitalData`:
+
+- `page` — page-level metadata with `category` and `attribute` sub-objects.
+- `user` — user-level data with a `profile` sub-object.
+- `event[]` — append-only event log with `eventName`, `eventData`, `timeStamp`, and `scope`.
+- `privacy.accessCategories` — declared access scopes.
+- `initialized` — boolean flag indicating readiness.
+
+**Privacy-aware scoping:**
+
+- Each data element can be assigned one or more access scopes (e.g., `"default"`, `"analytics"`, `"marketing"`).
+- Page data is publicly readable by default (no scope restriction).
+- User data automatically receives `"default"` scope, restricting access unless explicitly broadened.
+- Scope inheritance walks the path hierarchy from specific to general, so child elements inherit parent scope restrictions.
+- Scope metadata is stored in a private `Map`, not on the data objects themselves.
+
+**Loose coupling via DOM CustomEvents:**
+
+- All mutations emit namespaced `CustomEvent`s on `document` (e.g., `digitalData:PageElementSet`, `digitalData:UserProfileSet`, `digitalData:EventTracked`).
+- Vendor integration bridges subscribe to these events and forward data according to their scope permissions.
+- A global `DataLayer:Initialized` event signals readiness.
+- An `eventTypes` object on the root provides type-safe event name constants for bridge consumers.
+
+**React integration** uses a `DataLayerProvider` component that initializes the data layer once on mount via `useRef`, wrapped as the outermost provider in the app layout.
+
+## Consequences
+
+- **Application code** calls `digitalData.page.set(...)`, `digitalData.user.set(...)`, and `digitalData.trackEvent(...)` without knowing which vendors consume the data.
+- **Adding a new vendor** requires only a new event listener bridge — no changes to application code or the data layer itself.
+- **Removing a vendor** means removing its bridge. No application code changes.
+- **PII protection** is enforced at the data layer boundary. A vendor bridge for `"analytics"` scope cannot read user data that only has `"default"` scope.
+- **State partners** can configure different vendor bridges per deployment without modifying the core portal.
+- **Testing** is straightforward because the class is framework-agnostic and testable with jsdom.
+
+## References
+
+- W3C CEDDL specification: https://www.w3.org/2013/12/ceddl-201312.pdf
+- Implementation: `src/SEBT.Portal.Web/src/lib/data-layer.ts`
+- Tests: `src/SEBT.Portal.Web/src/lib/data-layer.test.ts`
+- Provider: `src/SEBT.Portal.Web/src/providers/DataLayerProvider.tsx`

package.json

@@ -27,8 +27,8 @@
   "devDependencies": {
     "concurrently": "^9.2.1",
     "husky": "^9.1.7",
-    "knip": "^5.71.0",
-    "lint-staged": "^16.2.7",
+    "knip": "^5.87.0",
+    "lint-staged": "^16.4.0",
     "tsx": "^4.21.0"
   },
   "engines": {