Established intent and ProductRequirementsDocument

2026-05-22 18:01:40 +02:00
parent ba474a3763
commit c4b6b83db5
3 changed files with 919 additions and 3 deletions
--- a/INTENT.md
+++ b/INTENT.md
@@ -0,0 +1,63 @@
+# 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.
+
--- a/README.md
+++ b/README.md
@@ -1,3 +1 @@
-# repo-seed
-
-A git repository template to bootstrap coulomb projects from.
+Headless multi-application, multi-tenant user mangement engine. 
--- a/wiki/ProductRequirementsDocument.md
+++ b/wiki/ProductRequirementsDocument.md
@@ -0,0 +1,855 @@
+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:
+
+1. **Headless service experience**  
+   Applications, services, agents, and repositories consume user-domain APIs without depending on a bundled UI.
+
+2. **Self-service account experience**  
+   A user-facing UI, likely provided by a separate `user-account` package or application, allows an individual user to manage their own account, profile, preferences, and connected identities.
+
+3. **Administrative user-management experience**  
+   An admin/operator UI, likely provided by a separate `user-manager` package 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-engine` if 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:
+
+```text
+user-engine
+```
+
+The repository may contain multiple modules or packages:
+
+```text
+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:
+
+```text
+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.md`
+- `SCOPE.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.
+