generated from coulomb/repo-seed
213 lines
9.3 KiB
Markdown
213 lines
9.3 KiB
Markdown
# 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` - NetKingdom-owned user-engine preparation and boundary
|
|
contracts.
|
|
|
|
The implementation-shaped workplans that were first drafted as
|
|
`NK-WP-0015` through `NK-WP-0019` were archived on 2026-05-22 and split into
|
|
the `user-engine` repository as:
|
|
|
|
- `USER-WP-0001` - repo preparation and interface adoption
|
|
- `USER-WP-0002` - isolated MVP implementation
|
|
- `USER-WP-0003` - multi-tenancy support
|
|
- `USER-WP-0004` - multi-application and catalog support
|
|
- `USER-WP-0005` - integrated test scenario expansion
|
|
- `USER-WP-0006` - implementation assessment, finalization, and polish
|