Organization Page-by-Page Guide

This inventory is aligned to the current organization console route tree and the latest agent, float, and transaction-contract implementation. Live browser smoke was refreshed on 2026-04-08 and is now part of the repo via pnpm -C emali2-frontend smoke:org.

Evidence and Current Limitation

• Portal: https://org.test.emali2.damplabs.com
• Route tree source: emali2-frontend/apps/org-console/src/App.tsx
• Behavior sources:
• emali2-frontend/apps/org-console/src/pages/FloatManagementPage.tsx
• emali2-frontend/apps/org-console/src/pages/AgentDetailsPage.tsx
• emali2-frontend/apps/org-console/src/pages/AgentChildrenPage.tsx
• emali2-frontend/apps/org-console/src/pages/TransactionsPage.tsx
• emali2-frontend/apps/org-console/src/services/orgApi.ts
• Live note: on 2026-04-08 orgadmin1, org1, and pnpadmin all authenticated successfully, but they currently resolve to the same organization-admin context in test. Treat that as active RBAC/environment drift until corrected.

Public Entry Routes

Route	Access	Current Behavior
/	Public or session-aware	Sends an authenticated organization-linked user into /app; otherwise shows the landing state.
/login	Public	Organization sign-in entry.
/register	Public	Organization onboarding/registration request route.
/forbidden	Public	Used for access denial and missing-context outcomes.

Core Operational Routes

Route	Access	Current Behavior
/app	Org-linked user	Dashboard for the resolved organization context.
/app/transactions	Org-linked user	Uses the backend org-perspective v2 transaction contract by default for unit-scoped transaction search and monitoring, with compatibility fallback only if the v2 endpoint is unavailable.
/app/transactions/:txnId	Org-linked user	Transaction detail for a record already visible in scope.
/app/tills/:tillId/ledger	Org-linked user	Ledger view for a specific till reached from a valid detail page.
/app/float	Org-linked user with relevant unit context	Float workspace that resolves the selected assigned unit, current balance snapshot, journal report, and unit transactions together.
/app/wallet	Org-linked user	Organization wallet route.
/app/settlements	Org-linked user	Settlement list. In the current test environment the page loads but shows a restricted-state banner for the tested org roles.
/app/settlements/:batchId	Org-linked user	Settlement-batch detail. Also restricted when the current org role lacks settlement capability.
/app/reports	Org-linked user	Reporting workspace for the resolved organization context.
/app/performance	Org-linked user	Performance metrics and comparisons. Settlement-specific KPIs degrade into a restricted-state warning when settlement capability is unavailable.
/app/approvals	Org-linked user with approval roles	Approval queue.
/app/team	Org admin, system admin, or service provider	Team-management route.
/app/profile	Org-linked user	Settings/profile surface for the signed-in org-linked account.
/app/settings	Org admin, system admin, or service provider	Administrative settings entry.
/app/security/2fa	Org-linked user	Identity-backed two-factor entry point.

Organization-Only Management Routes

These routes are only mounted when the resolved organization type is organization.

Route	Access	Current Behavior
/app/agents	Organization workspace	Agent directory with filters and direct visibility of till and shortcode identifiers.
/app/agents/:agentId	Organization workspace	Agent detail, including tills, shortcodes, float, and hierarchy actions for eligible tiers.
/app/agents/:agentId/children	Organization workspace	Child-agent hierarchy summary for SUPER and MASTER agents.
/app/merchants	Organization workspace	Merchant directory.
/app/merchants/:merchantId	Organization workspace	Merchant detail and mapped till/shortcode behavior.
/app/bills	Organization workspace	Bills-management route.
/app/bank-simulator	Organization workspace	Non-production banking simulation route.
/app/organizations	Organization workspace	Organization-unit directory.
/app/organizations/:unitId	Organization workspace	Specific organization-unit detail.
/app/branches	Organization workspace	Branch directory.
/app/branches/:branchId	Organization workspace	Branch detail.
/app/branch-comparison	Organization workspace	Branch-comparison analytics.
/app/policies	Organization workspace	Policies and limits.
/app/audit-trail	Organization workspace	Audit log and governance review.
/app/roles	Organization workspace	Role and permission visibility for organization operations.
/app/pos-backoffice	Organization workspace	External handoff into the merchant POS backoffice. This is a launcher, not a native org-console implementation of POS operations.

Shared Business Routes

These routes are shared between merchant and organization contexts when enabled by the resolved org type.

Route	Access	Current Behavior
/app/payouts	Merchant or organization context	Payout initiation and batch handling.
/app/invoices	Merchant or organization context	Invoice review and processing.

Deep Dive: /app/float

What changed

• The page no longer behaves like a generic float dashboard detached from unit context.
• It resolves the selected assigned organization unit, then loads:
• the agent profile tied to that unit,
• the current float balance,
• the journal snapshot for the same unitId,
• the organization-unit transaction history for the same unitId.

What operators should expect

• Changing the selected unit changes the balance and transaction evidence shown on the page.
• Top-up and customer-deposit actions must be interpreted as unit-scoped operations.
• Empty float pages should be troubleshot as missing unit context or missing agent-backed units, not as generic UI failure.

Deep Dive: /app/agents and /app/agents/:agentId

Current behavior

• The agent directory exposes tills and shortcodes directly instead of hiding them behind a separate detail lookup.
• Agent detail pages surface tills and shortcodes and provide ledger drill-down for mapped tills.
• For SUPER and MASTER agents, the detail flow can expose a child-agent navigation path into the dedicated hierarchy page.

Deep Dive: /app/agents/:agentId/children

Current behavior

• This route is the dedicated hierarchy summary for a selected super agent.
• It aggregates child count, total child float, till coverage, and the child agent rows themselves.
• The child table is designed to show till numbers directly and surface shortcode chips without requiring separate navigation for every child row.

Operational note

If the route returns no data for a supposedly super agent, verify the agent tier first. The hierarchy endpoint intentionally rejects agents that are not SUPER or MASTER.