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 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.