User Roles

This document defines the MVP role model for MyHoreca Pay multi-tenant operations. Scoped RBAC is based on the Platform / Organization / Outlet model. The navigation and active Syrve connection rules are fixed by ADR: Navigation & Tenancy Information Architecture v1.

MVP role set

Only these roles are active MVP roles:

Role	Primary scope	Payment write in current phase
MegaAdmin	Platform	Oversees production procedure; no routine customer write ownership
MegaManager	Platform / support scope	No payment write approval
OrganizationAdmin	Organization plus inherited child organizations	No direct posting approval
Accountant	Assigned Organization / Outlet scope	Manual posting approval within scope and safety controls
Viewer	Assigned Organization / Outlet scope	None

Production write is not granted to any normal role in the current phase. It requires future per-organization/per-Outlet enablement plus explicit owner approval.

PaymentOperator and LocationAdmin are not MVP roles. They are future-only / legacy-compatible names, receive no MVP permissions, and MVP workflows must not depend on them.

Implementation note for MHPAY-123: MegaAdmin and MegaManager manage platform users via /platform/users (list) and detail routes (/platform/users/new, /platform/users/:userId). Role assignment is on the detail page only; assignable roles are MVP roles (Accountant, Viewer, etc.) and exclude PaymentOperator / LocationAdmin. OrganizationAdmin uses organization-scoped user management under /settings (see MHPAY-124) and must not access the platform user workspace.

Implementation note for MHPAY-124: OrganizationAdmin manages organization-scoped users via /settings/users (list) and /settings/users/:userId (detail). The list page is read/navigation only; role assignment/removal is available only on the detail page and uses organization-scoped role endpoints. /settings/users/new is intentionally not introduced because the current API supports assignments/removals for existing users, not organization-scoped user creation.

Implementation note for MHPAY-126: MegaAdmin and MegaManager with platform.organizations.view can open /platform/organizations to view the platform organization registry and jump into the existing /settings quota/context workflow for a selected organization. The registry does not include organization creation, hierarchy management, or a dedicated detail route in this iteration.

Navigation Visibility

Frontend navigation visibility is a usability layer, not authorization. Direct route access still requires route guards and backend scoped authorization.

MVP role	Platform group	Organization group	Syrve group	Operations / payment workflow
MegaAdmin	Visible: platform organizations, platform users, Workers, bank adapter catalog where permitted	Visible for support/admin settings where permitted	Visible for connection registry/support diagnostics	Not the routine payment workflow owner. Operational outlet routes redirect mega users to /platform/organizations; use an Accountant account for day-to-day bank/payment work.
MegaManager	Visible for platform organizations and support/platform user/admin flows where permitted	Visible for support/onboarding where permitted	Visible for connection setup/diagnostics support	Diagnostics/read support only; no payment write approval. Same outlet-ops redirect behavior as other mega roles when applicable.
OrganizationAdmin	Not visible	Visible: organization settings and user/role/tenant prerequisites	Visible: organization Syrve connection registry/management	Read/manage prerequisites; no direct posting approval
Accountant	Not visible	Not admin-visible unless a separate scoped read path grants it	Connection registry and credential mutation not visible	Visible inside assigned scope; full payment workflow, with test-write approval only when gates allow
Viewer	Not visible	Not admin-visible	Read/status only where scoped permissions allow; no connection mutation	Read-only views only; no upload/match/allocate/approve/retry/reconcile mutations

Payment workflow routes remain Outlet-scoped and outside /syrve/connections/:id. This includes bank statements, matching, allocations, Syrve documents used by the payment workflow, posting queue, reconciliation, and payment anomalies.

syrveConnectionId is UI/navigation context only. It extends the active organization/Outlet context for connection-scoped Syrve screens and does not replace organization/Outlet tenant checks. It is not an RBAC scope and is not stored on UserRoleAssignment.

Role Definitions

MegaAdmin

Purpose: Platform owner. Controls global settings, quotas, pilot admission, diagnostics, and production enablement gates.

Can do:

• Manage platform organizations, quotas, settings, and platform users.
• View platform-wide diagnostics and audit where permitted.
• Support Syrve connection registry and runtime diagnostics.
• Approve platform production procedures after production-write criteria are met.

Cannot do:

• Own routine customer payment operations as the default workflow.
• Bypass anomaly blocks or audit requirements.
• Treat active Syrve connection selection as an authorization override.

MegaManager

Purpose: Customer success / implementation support for pilot rollout and onboarding.

Can do:

• Onboard and support organizations.
• Assist with Syrve connection setup and diagnostics.
• View support diagnostics and import quality across assigned/support scope.

Cannot do:

• Approve payment write.
• Approve or execute a production posting outside the owner-approved procedure.
• Bypass tenant boundaries or critical workflow gates.

OrganizationAdmin

Purpose: Customer organization administrator.

Can do:

• Manage organization, child organizations, Outlets, users, role assignments, and quotas within allowed scope.
• Manage Syrve/RMS connections and credentials within organization scope.
• Manage prerequisite organization settings, counterparty matching rules, and manual counterparty matching.

Cannot do:

• Access another organization.
• Perform direct payment posting approval.
• Change platform-only settings or quotas.

Accountant

Purpose: Financial controller for the operational payment workflow.

Can do within assigned scope:

• Upload and review bank statements where permitted.
• Match counterparties and prepare allocations.
• Confirm/approve allocations and posting queue actions when safety gates allow.
• Retry/reconcile postings and handle anomalies where authorized.
• View evidence, notifications, and audit entries for payment actions.

Cannot do:

• Manage platform users, quotas, platform settings, or credentials.
• Approve production write in the current MVP.
• Bypass critical anomaly, idempotency, preflight, or audit gates.

Viewer

Purpose: Read-only access for managers and auditors.

Can do:

• View allowed dashboards, imports, transactions, documents, allocations, postings, anomalies, notifications, evidence, and audit entries.

Cannot do:

• Upload bank statements.
• Match counterparties.
• Allocate, approve, queue, retry, reconcile, or mutate payment workflow records.
• Mutate Syrve credentials/connections, users, quotas, settings, or rules.

Future / Legacy-Compatible Roles

PaymentOperator

Not an MVP role. It receives no MVP permissions and must not be used as a dependency for current workflows. A future task may reintroduce a prepare-only operator role with explicit ADR and permission updates.

LocationAdmin

Not an MVP role. It receives no MVP permissions and must not be used as an active Outlet administration model in the MVP. Future Outlet admin behavior requires a separate ADR or accepted update to the ownership and permissions docs.

Legacy aliases such as Admin and Operator may exist for compatibility in older data, but the MVP seeded and assignable role set is the five-role model above.

Safety Rules

1. Viewer cannot upload, approve, write, retry, reconcile, or mutate.
2. Accountant owns the MVP payment workflow inside assigned scope, subject to all gates.
3. OrganizationAdmin manages organization prerequisites and Syrve connections, but not direct posting approval.
4. MegaAdmin and MegaManager support platform/onboarding/diagnostics; they are not routine payment workflow owners.
5. PaymentOperator and LocationAdmin have no MVP permissions.
6. syrveConnectionId is UI/navigation context only; backend authorization scope remains Platform / Organization / Outlet.

Current Implementation Notes

As of the Navigation & Tenancy IA epic:

• Active organization/Outlet context is selected after login and preserved in frontend active context.
• Active Syrve connection context is optional and applies only to connection-scoped Syrve screens.
• Legacy active-context keys remain organization/Outlet-only.
• Backend scoped authorization remains the source of truth for data access.
• Payment workflow routes remain outside /syrve/connections/:id.

See also:

• MVP Role Matrix and Permissions
• Scoped RBAC and Tenancy
• ADR: Navigation & Tenancy Information Architecture v1
• Product scope