30 KiB
i# User Engine Product Requirements Document
Product Requirements Document
1. Definition
user-engine is a reusable, headless user-domain service for software products, internal tools, and multi-application platforms that need structured user account, profile, preference, membership, and application-specific customization management.
The product provides a canonical backend component for managing user-related domain data independently from any single authentication provider, authorization engine, or application user interface. It supports simple standalone deployments while preserving a path toward multi-tenant, multi-application, and multi-team operation.
The product is expected to provide APIs and domain abstractions that can be consumed by separate user-facing and administrator-facing interfaces, tentatively named user-account and user-manager.
2. Context
Many software repositories and product prototypes eventually need user management capabilities. Typical needs include account records, profile attributes, preferences, team memberships, tenant-specific user data, application-specific customization, and administrative views over users.
In small products, this often begins as an ad hoc user table or metadata blob. In larger systems, the same problem expands into identity-provider integration, provisioning, user lifecycle operations, tenant boundaries, application-specific preferences, auditability, privacy controls, and administrative governance.
Existing identity systems such as Keycloak, ZITADEL, Ory Kratos, Authentik, Auth0, Okta, Entra ID, and Google Workspace address important parts of this space, especially authentication, federation, directory integration, provisioning, and identity lifecycle. However, they do not always provide a lightweight, repo-friendly, catalog-driven profile and customization layer that can be embedded into smaller services while scaling toward a multi-application platform landscape.
user-engine exists to fill this product gap: it is not primarily an identity provider, and it is not primarily an authorization engine. It is a user-domain and profile-customization service that integrates with identity and authorization systems through standards-aligned interfaces.
Architecturally, this PRD operates above technical design artifacts and below strategic platform architecture. It defines what the product is expected to achieve without prescribing implementation details.
3. Product Intent
The product shall provide a reusable user-domain engine that allows applications to manage users, accounts, profiles, preferences, memberships, and customization attributes in a structured and standards-aligned way.
The product should enable three primary experiences:
-
Headless service experience
Applications, services, agents, and repositories consume user-domain APIs without depending on a bundled UI. -
Self-service account experience
A user-facing UI, likely provided by a separateuser-accountpackage or application, allows an individual user to manage their own account, profile, preferences, and connected identities. -
Administrative user-management experience
An admin/operator UI, likely provided by a separateuser-managerpackage or application, allows authorized scope administrators to manage users across tenants, applications, teams, or other defined scopes.
The product should be useful in small standalone applications, but should not paint the architecture into a corner when the same user base later needs to span multiple tenants, teams, and applications.
4. Product Goals
4.1 Primary Goals
- Provide a headless canonical service for user-domain data.
- Support standalone setups for small repositories and early-stage products.
- Support multi-tenant, multi-application, and multi-team scenarios.
- Separate the headless user engine from optional user-facing and admin-facing UI components.
- Manage layered user profiles rather than a single unstructured metadata blob.
- Allow applications to register customization catalogs for application-specific profile attributes and preferences.
- Expose APIs that can support generated or catalog-driven profile forms.
- Integrate cleanly with external identity providers instead of requiring all identity concerns to be owned internally.
- Preserve a future extraction path toward a more generic
profile-engineif non-user entities later need similar attribute-profile capabilities.
4.2 Secondary Goals
- Provide schema-governed profile extensibility.
- Support attribute ownership, visibility, mutability, sensitivity, scope, and projection metadata.
- Provide profile projections for different consuming applications and protocol adapters.
- Support auditability of important profile, membership, catalog, and lifecycle changes.
- Enable event-driven integration with other services.
- Make the product useful for both human-driven applications and agentic software systems.
5. Non-Goals
The product shall not initially attempt to become a complete replacement for mature identity providers.
The following are explicitly out of scope for the initial product definition:
- Full identity provider implementation.
- Full OAuth 2.0 / OIDC provider implementation.
- Full SAML identity provider implementation.
- Full MFA, passkey, and credential-management stack.
- Full enterprise directory replacement.
- Full authorization engine or policy decision point.
- Full SCIM provisioning engine in the MVP.
- Full LDAP server implementation.
- General-purpose profile engine for arbitrary entity types.
- Deep CRM-style contact management.
- Social-network-style public profile system as a primary goal.
- Complete privacy/compliance workflow automation as an initial goal.
The product may integrate with systems that provide these capabilities, and may later add adapters, projections, or limited built-in features where product pressure justifies them.
6. Target Users and Stakeholders
6.1 Product Builders
Product builders need a reusable user-domain component that can be integrated into new services or UIs without reinventing user profile, preferences, and account management each time.
6.2 Application Developers
Application developers need APIs and SDKs to read and update user attributes, preferences, memberships, and app-specific customization values.
6.3 Platform Operators
Platform operators need to manage user-domain data across several applications, tenants, teams, or environments.
6.4 Scope Administrators
Scope administrators need a management interface to inspect users, assign memberships, resolve account issues, and manage local profile attributes within their authorized scope.
6.5 End Users
End users need a self-service account interface where they can inspect and manage their own account data, profile, preferences, connected identities, and application-specific settings.
6.6 Agentic Systems
Agentic systems may need structured access to user preferences, application-specific customization state, profile projections, and context-relevant user facts, subject to policy and visibility constraints.
7. Core Concepts
7.1 User
A User is a human or human-representing subject with an account in the system. A user may be linked to one or more external identities.
7.2 Account
An Account represents the user's relationship to the platform or application landscape. It includes account status, lifecycle state, and local account-level properties.
7.3 Identity
An Identity represents an authentication-side representation of the user, usually provided by an external identity provider. A user may have multiple identities.
7.4 Profile
A Profile is structured descriptive and preference-oriented data associated with a user. Profiles may exist at multiple layers.
7.5 Layered Profile
A Layered Profile is a profile model in which values can exist at different scopes such as global, tenant, application, team, or membership level.
7.6 Application Profile
An Application Profile contains application-specific attributes, preferences, and customization data for a user in relation to a registered application.
7.7 Membership
A Membership represents the relationship between a user and a tenant, team, organization, project, application, or other scope.
7.8 Customization Catalog
A Customization Catalog is an application-registered schema and metadata declaration that defines profile attributes, preference attributes, defaults, validation rules, UI hints, sensitivity, ownership, and projection behavior.
7.9 Effective Profile
An Effective Profile is a resolved view of profile attributes for a user in a specific context, such as a tenant, application, team, or session.
7.10 Projection
A Projection is a purpose-specific view of user-domain data exposed to a consuming application, UI, protocol adapter, event stream, or agent.
8. Scope and Non-Scope
8.1 In Scope
- User records and lifecycle status.
- External identity links.
- Basic local account model.
- Global user profile data.
- Tenant-specific user profile data.
- Application-specific user profile data.
- Team or membership-specific user profile data.
- Application registry.
- Customization catalog registry.
- Attribute definitions and validation metadata.
- Effective profile resolution.
- Headless REST or service API.
- SDK/client support for consuming applications.
- Optional self-service account UI.
- Optional administrative user-management UI.
- Event publication for important lifecycle and profile changes.
- Audit trail for security-relevant and administrative changes.
- Standards-aligned mapping toward OIDC profile claims and SCIM-style user concepts.
8.2 Out of Scope
- Detailed technical architecture.
- Specific programming language or framework choice.
- Database schema design.
- Deployment topology.
- Full authentication provider implementation.
- Full authorization policy engine.
- Full enterprise compliance management.
- Detailed backlog or sprint planning.
- Detailed UI visual design.
9. Product Capabilities
9.1 User and Account Management
The product shall support creation, retrieval, update, status changes, and deactivation of user accounts.
It should distinguish between at least the following states:
- invited
- active
- disabled
- suspended
- deleted or deletion-pending
- externally provisioned
- locally managed
9.2 External Identity Linking
The product shall support linking one user account to one or more external identities.
External identity links should support providers such as:
- OIDC providers
- SAML-backed identity providers through an upstream broker
- enterprise directories through provisioning adapters
- local development identity sources
The product should not require external identity linking for simple standalone use.
9.3 Profile Management
The product shall support structured profile data for users.
The profile model should support at least:
- global user profile
- tenant user profile
- application user profile
- membership profile
The product shall avoid treating all profile data as one undifferentiated metadata object.
9.4 Preference Management
The product shall support user preferences as a first-class profile category.
Preferences may include display preferences, locale, timezone, notification settings, default application views, and other user-controlled values.
9.5 Application Registry
The product shall allow applications to register themselves as profile consumers and customization-catalog owners.
Application registration should include:
- application identifier
- display name
- ownership metadata
- allowed profile scopes
- allowed projection types
- catalog registration permissions
9.6 Customization Catalog Registry
The product shall allow applications to register customization catalogs.
A catalog should define:
- namespace
- catalog identifier
- semantic version
- owning application
- attribute definitions
- defaults
- validation rules
- UI hints
- visibility rules
- mutability rules
- sensitivity classification
- lifecycle status
9.7 Attribute Governance
The product shall support governance metadata for profile attributes.
Attribute metadata should cover:
- ownership
- scope
- visibility
- mutability
- sensitivity
- validation
- defaulting
- projection
- inheritance behavior
- lifecycle state
9.8 Effective Profile Resolution
The product shall resolve effective profile values for a user in a given context.
Resolution should be able to consider:
- catalog defaults
- global user profile values
- tenant-specific values
- application-specific values
- team or membership-specific values
- administrative overrides where allowed
- user overrides where allowed
The resolution model should be explicit and inspectable.
9.9 Self-Service Account Support
The product shall expose APIs that allow a self-service UI to show and update data that the current user is allowed to inspect or change.
This supports a separate user-account UI.
Typical self-service areas include:
- personal profile
- preferences
- connected identities
- application-specific settings
- notification settings
- account status
- data export request entry point
- account deletion request entry point, where applicable
9.10 Administrative User Management Support
The product shall expose APIs that allow an administrative UI to inspect and manage users within authorized scopes.
This supports a separate user-manager UI.
Typical administrative areas include:
- user search
- user detail view
- account lifecycle actions
- tenant membership management
- team membership management
- application access-related profile inspection
- externally provisioned attribute inspection
- profile/catalog diagnostics
- audit event inspection
9.11 Projection Support
The product shall expose profile data through context-specific projections.
Initial projection types should include:
- internal API projection
- self-service UI projection
- admin UI projection
- application runtime projection
- OIDC-compatible profile claim projection
Future projection types may include:
- SCIM projection
- LDAP-compatible projection
- vCard or JSContact export
- event payload projection
- agent context projection
9.12 Event Support
The product shall emit events for important state changes.
Relevant events include:
- user created
- user updated
- user activated
- user disabled
- user suspended
- user deleted or deletion requested
- identity linked
- identity unlinked
- profile updated
- app profile updated
- membership changed
- catalog registered
- catalog activated
- catalog deprecated
- projection configuration changed
9.13 Auditability
The product shall retain audit information for important administrative, lifecycle, security-relevant, and profile-governance changes.
Audit records should identify:
- actor
- subject
- action
- affected scope
- timestamp
- source application or API client
- high-level change summary
10. Functional Expectations
10.1 Headless Operation
The product shall be usable without any bundled UI.
Applications must be able to integrate with the product through stable APIs.
10.2 Optional UI Operation
The product shall support separate UI components for different use cases.
The self-service UI and administrative UI should be optional consumers of the same core service rather than separate sources of truth.
10.3 Standalone Operation
The product shall support simple standalone deployments for small applications or development environments.
Standalone mode should not require a full enterprise identity stack.
10.4 Enterprise Integration
The product should support integration with enterprise identity and provisioning systems through standards-aligned interfaces or adapters.
10.5 Multi-Tenant Operation
The product shall support tenant boundaries.
Tenant-specific profile data and memberships must be separable from global user data.
10.6 Multi-Application Operation
The product shall allow multiple registered applications to consume profile data and register application-specific catalogs.
Application-specific attributes must be namespaced and governed to avoid collisions.
10.7 Multi-Team Operation
The product should support team or group membership profiles where user attributes vary by team, project, or scope.
10.8 Catalog-Driven UI Support
The product shall expose enough catalog metadata for a UI to generate profile and preference forms.
UI generation should respect visibility, mutability, validation, grouping, labels, descriptions, defaults, and sensitivity.
10.9 Standards Alignment
The product shall align with established standards where appropriate, especially OIDC-style profile claims, SCIM-style user and group concepts, JSON Schema-style validation, and event interoperability patterns.
11. Non-Functional Expectations
11.1 Modularity
The product should be modular enough to separate core domain logic, API layer, projection logic, catalog logic, and optional UI packages.
11.2 Extensibility
The product must support new profile attributes, catalogs, projections, and integration adapters without requiring invasive changes to the core domain model.
11.3 Security
The product must protect profile and account data according to attribute sensitivity, caller permissions, and scope boundaries.
11.4 Privacy
The product should minimize unnecessary exposure of personal data and support clear visibility rules for each attribute.
11.5 Auditability
The product should provide sufficient audit trails for administrative and security-relevant actions.
11.6 Operability
The product should expose health, diagnostics, and observability signals suitable for production operation.
11.7 Portability
The product should be deployable in small local setups and production-grade service environments.
11.8 Interoperability
The product should avoid unnecessary coupling to a single identity provider, UI framework, database, authorization engine, or deployment platform.
11.9 Evolvability
The product should preserve an architectural seam for extracting a more generic profile-engine later if profile catalogs prove useful beyond users.
12. Assumptions
- Authentication will often be provided by external systems.
- Authorization decisions will often be delegated to application-local policy logic or a dedicated authorization system.
- Many applications need profile and preference management even when they do not need a full identity platform.
- Small standalone deployments are strategically important because they enable reuse in prototypes and smaller repositories.
- Multi-tenant and multi-application readiness is strategically important because successful prototypes may grow into platform landscapes.
- Application-specific customization is a first-class requirement, not merely a metadata afterthought.
- Schema governance is necessary to avoid long-term profile-data entropy.
- The product should remain user-centered before generalizing into arbitrary entity profiles.
13. External Dependencies
Potential external dependencies include:
- Identity providers for authentication and federation.
- Directory or provisioning systems for enterprise lifecycle integration.
- Authorization engines for fine-grained access control.
- Databases for persistent account, profile, catalog, and audit data.
- Event systems for integration with other services.
- UI frameworks for optional account and manager interfaces.
The PRD does not prescribe which specific systems must be used.
14. Constraints
14.1 Conceptual Constraints
The product must maintain a clear distinction between:
- identity
- account
- profile
- preference
- membership
- authorization
- application customization
14.2 Product Boundary Constraints
The product must not become a general-purpose identity provider by accident.
The product must not become a general-purpose authorization platform by accident.
The product must not turn profile extensibility into unmanaged arbitrary metadata without catalog governance.
14.3 Compatibility Constraints
The product should remain compatible with common identity and provisioning ecosystems.
14.4 Usability Constraints
The self-service and administrative use cases must be represented distinctly enough that neither UI becomes confusing.
14.5 Evolution Constraints
The product should support future extraction of a generic profile engine without forcing that abstraction into the initial external product language.
15. Success Criteria
15.1 Product Success Criteria
The product is successful when:
- A new repository can integrate basic user account and profile management with minimal custom code.
- A standalone deployment can be set up without requiring a full enterprise identity platform.
- Multiple applications can register their own customization catalogs without attribute collision.
- A user can manage their own account and preferences through a self-service interface.
- An administrator can manage users in their authorized scope through an admin interface.
- Profile values can be resolved consistently across global, tenant, application, and membership layers.
- Applications can consume profile projections without needing to know the entire internal profile model.
- The system can integrate with external identity providers without becoming tightly coupled to one.
15.2 Quality Success Criteria
The product demonstrates quality when:
- Profile attributes are schema-governed and inspectable.
- Sensitive attributes are not accidentally exposed in inappropriate projections.
- Administrative changes are auditable.
- Catalog changes can be versioned and migrated.
- Tenant and application boundaries are enforced.
- Optional UIs consume the same headless APIs as other clients.
- The product remains understandable to both human developers and agentic coding systems.
15.3 Strategic Success Criteria
The product supports the broader platform strategy when:
- It becomes reusable across several product repositories.
- It establishes common terminology for users, accounts, profiles, preferences, memberships, and customization.
- It provides a foundation for later account, profile, and preference management across a family of applications.
- It can evolve toward enterprise-grade integration without losing its lightweight standalone utility.
- It creates a clean extraction path for a future generic
profile-engine.
16. Product Variants
16.1 Standalone Variant
The standalone variant supports a single application or small product installation.
Expected characteristics:
- local user records
- simple account lifecycle
- local profile and preference management
- optional local authentication integration
- simple catalog support
- bundled or easily attachable self-service UI
- lightweight administrative UI
16.2 Platform Variant
The platform variant supports a family of applications.
Expected characteristics:
- registered applications
- application-specific customization catalogs
- shared user base
- global and application-specific profiles
- profile projections
- catalog governance
- event integration
16.3 Enterprise Variant
The enterprise variant supports integration into organizational identity landscapes.
Expected characteristics:
- external identity provider integration
- SCIM-aligned provisioning concepts
- tenant-aware user management
- stronger auditability
- stronger attribute sensitivity handling
- administrative scopes
- policy-engine integration points
17. Repository and Packaging Recommendation
The initial repository should likely be named:
user-engine
The repository may contain multiple modules or packages:
user-engine-core
user-engine-api
user-engine-client
user-account-ui
user-manager-ui
user-engine-docs
The self-service and administrative UIs may later be extracted into separate repositories if reuse, release cadence, or product ownership makes that beneficial.
Recommended conceptual split:
user-engine
Headless canonical service and domain model.
user-account
Self-service user account and preference experience.
user-manager
Administrative user-management experience.
This split should be treated as a product and packaging boundary, not as an instruction to create multiple backend services prematurely.
18. Risks and Open Questions
18.1 Risk: Over-Generalization
The product may become too abstract if it tries to solve arbitrary entity profile management before validating user-focused use cases.
Mitigation: Keep external product language user-centered and preserve internal seams for later extraction.
18.2 Risk: Identity Provider Creep
The product may gradually absorb authentication, MFA, and identity-provider responsibilities.
Mitigation: Define identity provider integration as a primary strategy and full identity-provider implementation as a non-goal.
18.3 Risk: Metadata Entropy
Application-specific customization attributes may become an unmanaged metadata dump.
Mitigation: Require catalog registration, namespacing, validation, lifecycle state, ownership, and projection metadata.
18.4 Risk: UI Confusion
Self-service and administrative user-management interfaces may become conflated.
Mitigation: Keep user-account and user-manager as distinct use-case surfaces.
18.5 Risk: Authorization Boundary Confusion
Profile data and membership facts may be mistaken for authorization policy.
Mitigation: Provide authorization-relevant facts and integration points, but keep policy decisions outside the core product boundary.
18.6 Open Question: Built-In Authentication
The product needs a decision on whether standalone mode includes minimal local authentication or only integrates with a lightweight external identity provider.
18.7 Open Question: Initial Catalog Format
The product needs a decision on the first version of the customization catalog descriptor and how much it should directly reuse JSON Schema.
18.8 Open Question: SCIM Timing
The product needs a decision on whether SCIM should be implemented in the first production release or treated as a compatibility target for later.
18.9 Open Question: UI Packaging
The product needs a decision on whether optional UI components are shipped as apps, packages, embeddable components, or all of these over time.
19. MVP Definition
The MVP should prove the core product thesis without becoming a full identity platform.
19.1 MVP In Scope
- User account record.
- Account lifecycle status.
- External identity link model.
- Global profile.
- Application registry.
- Application profile.
- Customization catalog registration.
- Attribute validation through a schema mechanism.
- Effective profile resolution for global plus application scope.
- Headless API.
- Minimal client SDK.
- Basic self-service account UI.
- Basic administrative user-management UI.
- Audit trail for administrative and profile changes.
- Basic event emission.
19.2 MVP Out of Scope
- Full SCIM server.
- Full OIDC provider.
- Full SAML integration.
- Full LDAP adapter.
- Full policy engine.
- Complex multi-level inheritance.
- Advanced privacy workflow automation.
- Arbitrary non-user entity profiles.
- Highly polished visual design.
- Marketplace or plugin ecosystem.
19.3 MVP Acceptance Criteria
The MVP is acceptable when:
- A demo application can register itself with
user-engine. - The demo application can register a customization catalog.
- A user can view and edit allowed profile and preference attributes.
- An admin can view and manage users in a defined scope.
- The application can request an effective profile projection for a user.
- Attribute values are validated against catalog definitions.
- Profile changes produce auditable events.
- The system can run in a simple standalone setup.
20. Downstream Artifacts
This PRD should serve as the source for later artifacts, including:
INTENT.mdSCOPE.md- Functional Requirements Specification
- Use Case Catalog
- Capability Boundary Card
- API design specification
- Customization Catalog Descriptor specification
- Architecture Decision Records
- Initial implementation roadmap
Appendix A: Candidate Terminology
| Term | Meaning |
|---|---|
| User Engine | Headless user-domain service |
| User Account | Self-service account and preference experience |
| User Manager | Administrative user-management experience |
| User | Human or human-representing subject |
| Account | User's relationship to the platform/application landscape |
| Identity | Authentication-side representation, often external |
| Profile | Structured descriptive and preference-oriented user data |
| Preference | User-controlled setting or desired default behavior |
| Membership | User relationship to a tenant, team, application, or scope |
| Catalog | Registered schema and governance definition for attributes |
| Effective Profile | Resolved profile view in a concrete context |
| Projection | Purpose-specific exposed view of user-domain data |
Appendix B: Initial Capability Map
| Capability | MVP | Later |
|---|---|---|
| User records | Yes | Enhance |
| Account lifecycle | Yes | Enhance |
| External identity links | Yes | Enhance |
| Global profile | Yes | Enhance |
| Tenant profile | Partial | Yes |
| Application profile | Yes | Enhance |
| Membership profile | Partial | Yes |
| Application registry | Yes | Enhance |
| Customization catalogs | Yes | Enhance |
| Schema validation | Yes | Enhance |
| Effective profile resolution | Yes | Enhance |
| Self-service UI support | Yes | Enhance |
| Admin UI support | Yes | Enhance |
| Audit events | Yes | Enhance |
| Event publishing | Basic | Yes |
| OIDC claim projection | Basic | Yes |
| SCIM support | No | Yes |
| LDAP projection | No | Optional |
| vCard / JSContact export | No | Optional |
| Generic profile-engine extraction | No | Possible |
Appendix C: Guiding Product Principle
The product should remain concrete enough to solve real user-account and user-management problems, while being structured enough that the underlying profile and customization machinery can later be extracted into a more generic profile engine if repeated use across non-user entities justifies it.