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.