# 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 service for
products and platforms that need account, profile, preference, membership, and
application-specific user attribute management without coupling those concerns
to a particular identity provider, authorization engine, 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;
- 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, credential lifecycle, and UI experience concerns.

It is intended to integrate through standards-aligned interfaces with identity
providers, provisioning sources, directories, authorization systems, event
sinks, and optional UI surfaces 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 capabilities;
- 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.

It does not aim to be:

- a full identity provider;
- a password, passkey, session, or MFA system;
- a fine-grained authorization engine;
- a directory server;
- a UI application.

It provides the user-domain APIs, catalog metadata, projections, events, 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;
- 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;
- 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 keeping a clear path from
a simple local setup to a governed multi-tenant, multi-application deployment.