ADR: Navigation & Tenancy Information Architecture v1

Status: Accepted Date: 2026-07-06 Plane: MHPAY-110 / MHPAY-ADR-007 Epic: MHPAY-109 / MHPAY-NAV-000

Context

The current SPA sidebar mixes different ownership levels in one Syrve group:

Outlet operations and payment workflow screens;
Syrve connection-level screens such as sync status and references;
organization settings;
platform administration screens such as bank adapters, platform users, and workers.

The current routes /syrve/document-sync-runs and /syrve/references are global UI routes. They depend on the active organization/outlet context and backend default connection resolution instead of exposing the selected SyrveConnection in the URL.

Variant C from plane-epic-navigation-tenancy-ux-v1.md is accepted as the target information architecture for the navigation and connection context epic. The ADR fixes the target structure before runtime UI/API tasks MHPAY-111..116, so those tasks do not reopen scope.

The user-facing product term is Outlet. Location remains a legacy/runtime entity name only.

Decision

Adopt Variant C navigation and tenancy information architecture:

keep MVP RBAC scopes at Platform / Organization / Outlet;
keep UserRoleAssignment free of ConnectionId;
treat syrveConnectionId as optional navigation/connection context, not as RBAC scope;
move Syrve sync status and references to connection-scoped target routes under /syrve/connections/:id;
keep bank statements, matching, allocations, audit, payment posting, and reconciliation workflows outlet-scoped;
keep platform administration items in a dedicated Platform sidebar group, not in Syrve.

This ADR is documentation-only. Runtime UI/API changes are implemented by follow-up tasks.

Target Information Architecture

text

Platform
  Пользователи платформы           /platform/users
  Workers                          /admin/workers
  Банковские адаптеры              /settings/bank-adapters
  Глобальные настройки платформы   future

Organization
  Настройки организации            /settings
  Подключения Syrve                /syrve/connections
      [выбранное подключение :connectionId]
          Обзор / health / credentials  /syrve/connections/:id
          Статус sync                   /syrve/connections/:id/sync-runs
          Счета и ДДС                   /syrve/connections/:id/references

Outlet
  Операции: dashboard, review queue, bank statements, matching, audit
  Сверка/Распределение/Проведение
  Syrve documents/postings/anomalies filtered through active org/outlet context

SyrveConnection belongs to the organization or to an Outlet-scoped operational context according to the existing RMS/CHAIN model, but connection selection does not change the product workflow ownership of bank and payment operations.

The target sidebar groups are:

Операции

/dashboard
/review-queue
/accountant-workbench
/bank-statements/list
/name-matching
/counterparty-rules
/bank-statements
/manual-corrections
/audit-log

Сверка / Распределение / Проведение

/syrve/documents
/syrve/documents/unpaid
/syrve/documents/partially-paid
/syrve/documents/paid
/payment-allocations
/payment-allocations/preview
/syrve/postings
/payment-anomalies
/syrve/reconciliation

Syrve

/syrve/connections

The Syrve group is for the organization-level Syrve connection registry only. It must not contain platform administration screens. It must not contain /settings, /settings/bank-adapters, /platform/users, or /admin/workers.

Организация

/settings

Платформа

/settings/bank-adapters
/platform/users
/admin/workers

MegaAdmin/MegaManager platform items live in the Platform group, not in Syrve.

Route Ownership Matrix

Current / Target route	Level	Notes
`/dashboard`	Outlet	operational dashboard
`/review-queue`	Outlet	bank/payment workflow
`/accountant-workbench`	Outlet	accountant workflow
`/bank-statements/list`	Outlet	statement list
`/bank-statements`	Outlet	statement upload/import
`/name-matching`	Outlet	counterparty matching
`/counterparty-rules`	Outlet / Organization inherited rules	rules may inherit from organization, workflow remains outlet-facing
`/payment-allocations`	Outlet	allocations remain outlet-scoped
`/payment-allocations/preview`	Outlet	allocation preview
`/syrve/documents`	Outlet	Syrve documents in payment workflow, filtered by org/outlet/default connection
`/syrve/postings`	Outlet	posting queue
`/syrve/reconciliation`	Outlet	reconciliation workflow
`/payment-anomalies`	Outlet	anomaly workflow
`/syrve/connections`	Organization	connection registry
`/syrve/connections/:id`	Connection under Organization	connection overview/health/credentials
`/syrve/connections/:id/sync-runs`	Connection under Organization	target route for sync runs
`/syrve/connections/:id/references`	Connection under Organization	target route for references
`/settings`	Organization	quotas/org users/settings
`/settings/bank-adapters`	Platform	platform bank adapter catalog
`/platform/users`	Platform	platform user management
`/admin/workers`	Platform	worker dashboard

Redirect Matrix

Old route	Target route	Policy
`/syrve/document-sync-runs`	`/syrve/connections/:id/sync-runs`	resolve active/default connection, otherwise require explicit connection selection
`/syrve/references`	`/syrve/connections/:id/references`	resolve active/default connection, otherwise require explicit connection selection
`/syrve/connections`	unchanged	organization-level connection list
`/syrve/connections/:id`	unchanged	connection overview

Runtime redirects were implemented in MHPAY-112 and extended in MHPAY-114 to prefer the remembered frontend syrveConnectionId when it still exists, then the default connection, then the first available connection.

Active Context Stack

MHPAY-118 / ADR: RBAC and tenancy v2 supersedes/extends active context rules for mandatory Outlet context on operational screens.

text

organizationId  required after login/context selection
outletId/locationId  optional for org-wide/platform flows, required for outlet workflows
syrveConnectionId  optional UI/navigation context for connection-scoped Syrve screens

Rules:

syrveConnectionId extends the active context introduced by MHPAY-53; it does not replace organization/outlet context.
syrveConnectionId is not an RBAC scope in the MVP.
syrveConnectionId is persisted only in frontend active-context storage as UI/navigation state.
Legacy active-context keys remain organization/outlet-only; no legacy Syrve connection key is created.
backend code must not trust frontend context blindly; it must validate organization/outlet/connection ownership server-side.
Redis session persistence for active context is out of scope.
frontend/src/shared/activeContext.ts owns the frontend helper functions for setting, clearing, and resolving the active Syrve connection while preserving the current organization/outlet context.

RBAC / Permission Impact

Permission / RBAC Impact: None.

MVP RBAC scopes remain Platform / Organization / Outlet.
UserRoleAssignment does not receive ConnectionId.
Connection-level screens are authorized through existing organization/platform permissions plus scoped access to the selected connection.
Accountant does not gain organization/platform administration access merely by having Syrve workflow permissions.
MegaAdmin/MegaManager platform items live in the Platform group, not in Syrve.

Syrve / iiko Boundary

SyrveConnection is the Pay-owned operational registry.
IikoConnector is low-level transport only.
This ADR does not change IikoConnector.
Runtime route changes belong to MHPAY-112; explicit connection-scoped read APIs belong to MHPAY-113.
MHPAY-114 adds frontend-only active Syrve connection selection and direct-route synchronization.
Bank statements, matching, allocations, and payment workflow routes are not moved under /syrve/connections/:id.

Out of Scope

Runtime frontend changes in AppLayout.tsx or router.tsx.
Backend controller/service/DTO/contract changes.
Adding ConnectionId to RBAC or UserRoleAssignment.
Changing IikoConnector.
Redis session persistence for active context.
Moving bank statements, matching, allocations, or payment workflow under /syrve/connections/:id.
Mobile redesign.

Consequences

Sidebar grouping can be changed in MHPAY-111 without re-deciding IA.
Connection-scoped UI routes and redirects can be added in MHPAY-112 using the redirect matrix above.
Explicit connection IDs in Syrve read APIs can be added in MHPAY-113 without changing RBAC scopes.
Active connection context can extend MHPAY-53 in MHPAY-114 as additive context, not as authorization scope.
Platform administration remains visually and permission-wise separate from Syrve connection operations.
MHPAY-118 / ADR: RBAC and tenancy v2 extends this ADR with mandatory active organization/Outlet context for operational screens, including platform-role gating.

Follow-up Plane Order

Canonical shorthand: ADR -> NAV-001 -> (NAV-002 || API-003) -> RBAC-006 -> FE-003 -> DOC-002.

text

ADR-007
  NAV-001
  (NAV-002 || API-003)
  RBAC-006
  FE-003
  DOC-002

ADR: RBAC and tenancy v2

ADR: Navigation & Tenancy Information Architecture v1 ​

Context ​

Decision ​

Target Information Architecture ​

Sidebar Sections ​

Операции ​

Сверка / Распределение / Проведение ​

Syrve ​

Организация ​

Платформа ​

Route Ownership Matrix ​

Redirect Matrix ​

Active Context Stack ​

RBAC / Permission Impact ​

Syrve / iiko Boundary ​

Out of Scope ​

Consequences ​

Follow-up Plane Order ​

Related documents ​

ADR: Navigation & Tenancy Information Architecture v1

Context

Decision

Target Information Architecture

Sidebar Sections

Операции

Сверка / Распределение / Проведение

Syrve

Организация

Платформа

Route Ownership Matrix

Redirect Matrix

Active Context Stack

RBAC / Permission Impact

Syrve / iiko Boundary

Out of Scope

Consequences

Follow-up Plane Order

Related documents