Add user-engine architecture workplans

docs/reviews/2026-05-22T19-19-59+0200-user-engine-architecture-review.md

@@ -0,0 +1,205 @@
+# User Engine Architecture Review
+
+Timestamp: 2026-05-22T19:19:59+0200
+Reviewer: codex
+Subject: `/home/worsch/user-engine/wiki/ArchitectureBlueprint.md`
+Context: user-engine integration with NetKingdom IAM Profile, key-cape,
+Keycloak, flex-auth, Railiance platform services, and future user-account /
+user-manager UI surfaces.
+
+## Executive Assessment
+
+The proposed architecture is directionally sound. `user-engine` fills a real
+gap: a headless user-domain, profile, preference, membership, catalog, and
+projection service that does not try to become an identity provider, MFA
+system, authorization engine, runtime secret store, or UI.
+
+The central improvement area is contract precision at the boundaries. The
+architecture has the right separation in prose, but implementation will create
+duplicate truths unless we explicitly define how identity claims, user-engine
+memberships, flex-auth subject facts, application registrations, OIDC clients,
+protected-system registrations, and profile projections relate to each other.
+
+## Main Findings
+
+### 1. Membership Ownership Is The Hottest Overlap
+
+`user-engine` wants to own tenant, application, team, and membership facts.
+IAM providers expose groups and roles. flex-auth also models subjects, groups,
+teams, and tenants for policy decisions.
+
+This overlap is healthy only if the source of truth is explicit:
+
+- IAM owns authentication-time identity facts and coarse claims.
+- user-engine owns product-domain memberships and profile facts.
+- flex-auth owns policy interpretation and final authorization decisions.
+- exported subject facts are read models or policy inputs, not competing
+  masters.
+
+Recommended action: create a source-of-truth matrix and a membership
+synchronization contract before implementation starts.
+
+### 2. Application Registration Is Overloaded
+
+An "application" can mean several things:
+
+- a user-engine profile consumer;
+- an OIDC client in key-cape or Keycloak;
+- a flex-auth protected system;
+- a catalog namespace owner;
+- a deployed workload in Railiance.
+
+These should not collapse into one record. user-engine should own the profile
+consumer record and hold explicit bindings to OIDC clients, flex-auth protected
+systems, catalog namespaces, and deployment metadata.
+
+Recommended action: define an application onboarding contract that maps these
+records without merging their ownership.
+
+### 3. OIDC-Compatible Projections Need A Strong Boundary
+
+OIDC-compatible profile projections are useful, but user-engine should not
+become part of the token issuance critical path by accident. Token issuance
+belongs to key-cape or Keycloak. If user-engine profile data is needed in
+claims, it should be delivered through an explicit claims-enrichment adapter
+with caching, freshness, and failure-mode rules.
+
+Recommended action: treat claims enrichment as an adapter boundary, not a core
+runtime dependency for login.
+
+### 4. Synchronous Authorization Checks Can Become A Bottleneck
+
+The flow "user-engine calls flex-auth for every protected action" is clean but
+can become expensive for list screens, bulk admin operations, and high-volume
+profile reads.
+
+Recommended mitigations:
+
+- request-scoped memoization;
+- batch authorization checks for list/admin screens;
+- short-lived decision caching only where safe;
+- explicit fail-closed behavior for sensitive writes;
+- local policy fixtures only for standalone development and tests.
+
+### 5. Effective Profile Resolution Can Become The Hidden Performance Center
+
+Layered profiles plus catalog defaults plus tenant, application, team, and
+admin overrides are powerful, but they are also expensive and easy to
+implement as repeated joins or repeated resolver calls.
+
+Recommended action: design versioned effective-profile materialization or
+caching early. Invalidation should be driven by profile, catalog, membership,
+and application outbox events.
+
+### 6. Audit Is Correctly Placed But Needs One Correlation Model
+
+user-engine audit, flex-auth decision audit, and platform audit sinks all have
+valid roles. Without shared correlation IDs, operators will struggle to
+reconstruct one administrative action across systems.
+
+Recommended action: define an audit correlation contract with request ID,
+actor identity, user-engine audit ID, flex-auth decision ID, outbox event ID,
+tenant, application, and sensitivity-aware redaction rules.
+
+## Information Flow Assessment
+
+Good flows:
+
+- IAM Profile -> user-engine actor envelope: correct abstraction.
+- user-engine -> flex-auth authorization check: correct decision boundary.
+- user-engine -> outbox -> platform event/audit sinks: correct durability
+  pattern.
+- catalog metadata -> future UIs: correct headless-first UI support.
+
+Unclear or inefficient flows:
+
+- user-engine membership facts -> flex-auth subject manifests: source of truth
+  and freshness need definition.
+- user-engine profile projection -> OIDC claims: must not make token issuance
+  depend synchronously on user-engine.
+- admin list/search -> per-row flex-auth checks -> profile resolver: likely
+  inefficient unless batched and cached.
+- catalog activation -> profile migration -> projection invalidation: needs a
+  versioning and migration flow.
+
+## Expected Bottlenecks
+
+| Bottleneck | Why it happens | Mitigation |
+| --- | --- | --- |
+| flex-auth checks | Per-action synchronous decisions | Batch checks, memoize per request, cache low-risk decisions, keep writes fail-closed |
+| Effective profile resolution | Layered scopes and catalog defaults | Materialized effective profiles, version stamps, targeted invalidation |
+| Catalog governance | Every app wants custom attributes | Governance tiers, namespace ownership, automated compatibility checks |
+| Audit volume | Profile and membership changes can be frequent | Redacted summaries, outbox compaction where allowed, correlation IDs |
+| Application onboarding | Crosses IAM, user-engine, flex-auth, Railiance | Application onboarding contract and checklist |
+| Claims enrichment | Login path can become dependent on user-engine | Async/cache-backed enrichment and graceful claim omission rules |
+
+## SWOT Digest
+
+### Strengths
+
+- Clear headless product boundary.
+- Good separation from identity provider, MFA, secrets, UI, and PDP concerns.
+- Strong fit with NetKingdom IAM Profile and flex-auth.
+- Catalog-driven profile governance addresses real metadata entropy.
+- Supports standalone adoption without abandoning platform integration.
+
+### Weaknesses
+
+- Membership, group, role, and subject facts can drift across systems.
+- Application registration is currently overloaded.
+- Projection freshness and caching rules are not yet defined.
+- Standalone mode could grow unsafe auth shortcuts unless constrained.
+- Audit correlation is not yet formalized.
+
+### Opportunities
+
+- user-engine can become the reusable user-domain/profile layer for many repos.
+- Catalog metadata can power `user-account` and `user-manager` without
+  separate UI-specific backends.
+- Subject/membership exports can make flex-auth richer without turning
+  flex-auth into a profile store.
+- A clean app onboarding contract can make multi-application integration
+  repeatable.
+- Agent-context projections can give agentic systems governed user context.
+
+### Threats
+
+- Duplicate truth between IAM, user-engine, and flex-auth.
+- Login/token flows becoming dependent on user-engine availability.
+- Profile data leakage through broad admin or agent projections.
+- Catalog approval becoming a central bottleneck.
+- Tenant admins accidentally gaining platform-scale authority.
+
+## Promising Improvements
+
+1. Add a source-of-truth matrix for identity claims, user records, accounts,
+   memberships, groups, roles, app registrations, protected systems, catalogs,
+   profile values, and audit records.
+2. Define an application onboarding contract across IAM OIDC client,
+   user-engine application, flex-auth protected system, catalog namespace, and
+   deployment metadata.
+3. Define a membership synchronization contract with ownership, import,
+   export, conflict handling, and freshness rules.
+4. Split projection definitions into runtime, UI, claims-enrichment, audit,
+   and agent-context projections.
+5. Add an authorization performance model for synchronous checks, batching,
+   caching, fail-closed writes, and standalone development policy fixtures.
+6. Add effective-profile cache/materialization design using catalog/profile
+   version stamps and outbox-driven invalidation.
+7. Define audit correlation across user-engine, flex-auth, and platform audit
+   sinks.
+8. Add catalog governance tiers so low-sensitivity app-owned attributes can
+   move quickly while sensitive or cross-tenant attributes require review.
+9. Make claims enrichment explicitly optional and adapter-owned.
+10. Define tenant/admin scope rules before building `user-manager`.
+
+## Workplan Follow-Up
+
+The review is translated into the following NetKingdom workplans:
+
+- `NK-WP-0014` - user-engine preparation and boundary contracts
+- `NK-WP-0015` - isolated MVP implementation
+- `NK-WP-0016` - multi-tenancy support
+- `NK-WP-0017` - multi-application and catalog support
+- `NK-WP-0018` - integrated test scenario expansion
+- `NK-WP-0019` - implementation assessment, finalization, and polish