user-engine/INTENT.md

INTENT

This file captures why this repository exists, the direction it is moving toward, and the kind of system it is meant to become. It is intentionally aspirational and stable, not a description of current implementation.

Purpose

user-engine exists to provide a reusable, headless user-domain and identity-domain service for products and platforms that need account, profile, preference, membership, identity-context, and application-specific user attribute management without coupling those concerns to a particular identity provider, authorization engine, security stack, or user interface.

Primary Utility

The project provides a canonical user layer that can start small in a standalone service and grow into governed multi-tenant, multi-application, and multi-team environments.

It manages:

• users and account state;
• external identity links;
• actor, principal, subject, and user-context mappings;
• profile and preference data;
• tenant, application, and team memberships;
• application-registered customization attributes;
• catalog-driven profile schemas;
• profile projections for consuming applications;
• lifecycle and profile-change events.

Strategic Direction

user-engine is intended to become the NetKingdom identity-domain integration layer: a headless service that exposes canonical identity, user, account, membership, tenant, team, profile, lifecycle, and evidence-facing concepts to applications without requiring those applications to know the technical IAM, security, authorization, audit, or secret-management implementation details.

NetKingdom infrastructure remains the source of truth for authentication, credential assurance, token issuance, policy decisions, security controls, runtime secrets, and platform audit infrastructure. user-engine consumes those capabilities through explicit adapters and presents a stable domain model aligned with identity-related InfoTechCanon concepts.

In this role, user-engine should make identity-domain questions easy for applications and agents to answer:

• who the current actor is in a domain context;
• which user, account, external identity, principal, or subject references are involved;
• which tenant, team, application, and membership scopes apply;
• which user-domain facts may be projected into runtime, admin, audit, agent, or claims-enrichment contexts;
• which lifecycle, access-review, evidence, or integration gaps need attention.

Strategic Role

user-engine separates user-domain management from authentication, authorization, credential lifecycle, and UI experience concerns.

It is intended to integrate through standards-aligned interfaces with NetKingdom IAM, identity providers, provisioning sources, directories, authorization systems, security controls, event sinks, audit infrastructure, and optional UI surfaces while remaining useful in simple standalone deployments.

It may implement identity-canon entities when they are user-domain facts or identity-context mappings. It should reference, map to, or consume adjacent canon entities when their source of truth belongs to NetKingdom infrastructure, security, access-control, governance, or organization systems.

Intended Users

• application developers adding user/account functionality to a service;
• platform teams integrating NetKingdom identity infrastructure across multiple applications;
• product teams needing self-service account and preference capabilities;
• operators and tenant administrators managing scoped user populations;
• agentic systems that need structured access to user preferences and profile context;
• domain services that need identity-canon aligned user, actor, principal, subject, tenant, team, membership, and evidence references without depending on technical IAM implementation details.

Product Boundaries

user-engine is the headless backend and domain service.

It does not aim to be:

• a full identity provider;
• a password, passkey, session, or MFA system;
• a fine-grained authorization engine;
• the policy decision point for protected resources;
• the owner of NetKingdom security controls or runtime secrets;
• the full organization, HR, or directory authority;
• a directory server;
• a UI application.

It provides the user-domain and identity-domain APIs, mapping records, catalog metadata, projections, events, evidence references, and audit records that those surrounding systems can consume.

Design Principles

• headless first;
• optional UI, not UI-driven;
• standalone-friendly;
• enterprise-integratable;
• identity-provider agnostic;
• authorization-engine agnostic;
• NetKingdom-integrated without hiding source-of-truth boundaries;
• canon-aligned through explicit entity and relationship mappings;
• catalog-driven customization;
• explicit ownership, visibility, mutability, and sensitivity of attributes;
• layered profiles instead of one global metadata blob;
• deterministic and inspectable effective profile resolution;
• evidence and lifecycle awareness for identity-domain changes;
• concrete user-domain focus with a possible future extraction path toward a generic profile engine.

Success Definition

user-engine succeeds when a repository or application can add robust user-domain and identity-domain capabilities with minimal coupling while keeping a clear path from a simple local setup to a governed multi-tenant, multi-application NetKingdom deployment.

It should also succeed as an implementation surface for identity-related canon intent: applications should be able to consume user, account, identity-link, actor, principal, subject, tenant, team, membership, profile, lifecycle, and evidence context through stable APIs and mappings without taking a direct dependency on the technical IAM, authorization, security, or audit substrate.