# User Engine INTENT.md

## Purpose

`user-engine` exists to provide a reusable, headless user domain service for applications, platforms, and repositories that need account, profile, preference, membership, and application-specific user attribute management without becoming tightly coupled to a single identity provider or UI.

## Primary Utility

The project provides a canonical user layer that can be embedded in small standalone services and extended into multi-tenant, multi-application, and multi-team environments.

It manages:

- users and account state
- external identity links
- 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 Role

`user-engine` separates user-domain management from authentication, authorization, and application-specific UI concerns.

It is intended to integrate with established identity and access systems such as OIDC providers, SCIM provisioning sources, LDAP-compatible directories, and external authorization engines, while remaining useful in simple standalone deployments.

## Intended Users

- application developers adding user/account functionality to a service
- platform teams managing users across multiple applications
- product teams needing self-service account and preference management
- operators and tenant administrators managing scoped user populations
- agentic systems that need structured access to user preferences and profile context

## Product Boundaries

`user-engine` is the headless backend and domain service.

Related UI surfaces may be provided separately:

- `user-account` for self-service account, profile, and preference management by the individual user
- `user-manager` for administrative and operational management of users in a tenant, application, team, or platform scope

`user-engine` does not aim to be a full identity provider, password/MFA system, or fine-grained authorization engine, though it may integrate with such systems.

## Design Principles

- headless first
- optional UI, not UI-driven
- standalone-friendly
- enterprise-integratable
- identity-provider agnostic
- authorization-engine agnostic
- catalog-driven customization
- explicit ownership, visibility, mutability, and sensitivity of attributes
- layered profiles instead of one global metadata blob
- 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 capabilities with minimal coupling, while still having a clear path from a simple local setup to a governed multi-tenant, multi-application deployment.