rl-docs-hub

Home · Apps · rl-bank-mvp

---

Staff account servicing + support workspace slice

Status: Draft, intended to match the next implementation slice after account-detail/history realism.

Why this slice

The fake-bank preview already lets customers see more believable accounts, cards, transfers, and history. The weakest realism gap now is on the staff side: support and operations staff can sign in, but the support workspace is mostly placeholder and cannot actually perform controlled servicing actions.

This slice deepens believable internal-bank operations by adding:

• a staff-facing support account workspace
• permissioned account status servicing for freeze / unfreeze / close actions
• reason capture and audit trail for every staff action
• recent account / transfer / notification context so a support agent has a realistic case-handling view

This is a better next step than shallow breadth because it connects real day-to-day bank operations: customer issue or servicing request → staff reviews account context → staff performs a permissioned action → audit trail is captured.

Product / feature scope

In scope

• staff can open a support workspace and review a list of customer accounts
• each support account row shows:
  • product name
  • masked account number
  • customer id
  • currency
  • current status
  • available/current balances
  • last transaction time
• staff can open an account detail drawer/panel with:
  • recent transactions
  • recent transfers touching the account
  • recent customer notifications tied to the account
  • latest account audit history for servicing actions
• staff with the new servicing permission can perform:
  • ACTIVE -> FROZEN
  • FROZEN -> ACTIVE
  • ACTIVE|FROZEN -> CLOSED
• each servicing action requires an operator-entered reason
• staff UI surfaces the acting staff id and created audit record context after success

Out of scope

• reopening closed accounts
• KYC remediation workflows
• card replacement flows
• customer messaging back to external email/SMS channels
• formal ticket ownership / SLA engine
• bulk servicing actions
• customer-visible dispute/case objects

Product design

Staff experience shape

• Support becomes a real operational workspace instead of static placeholder copy.
• Staff first sees a compact account queue/table with lightweight search by customer id or masked account number.
• Selecting an account opens a detail panel with the context a support agent usually wants before acting:
  • balances
  • recent movement
  • linked operational events
  • current status controls
• Servicing controls are visibly permission-gated and include confirmation text plus a mandatory reason field.

Interaction rules

• support-capable staff may read support account context
• only staff with the new account servicing permission may execute state changes
• close action is deliberately more restrictive in copy and confirmation than freeze/unfreeze
• UI should present this as a fake-bank internal preview, not a production-grade core banking control panel

Business logic and rules

1. Staff must be authenticated and mapped to an active staff identity.
2. Read access to the support workspace requires account.read.
3. Mutating account status requires a new permission: account.manage.
4. Allowed transitions:
   • ACTIVE -> FROZEN
   • FROZEN -> ACTIVE
   • ACTIVE -> CLOSED
   • FROZEN -> CLOSED
5. CLOSED accounts cannot be reopened in this slice.
6. Every servicing mutation requires a non-empty reason string.
7. If the requested target status is already the current status, the API returns success idempotently and still returns the latest account snapshot.
8. Every successful status mutation writes an audit log entry with:
   • actor type STAFF
   • actor id = acting staff user id
   • entity type ACCOUNT
   • action UPDATE
   • metadata including previous status, next status, reason, and support workspace source
9. Customer-owned recent transactions/transfers/notifications shown in the support view are read-only context for staff.
10. Closed accounts remain visible in support history and list results.

Technical design summary

API additions

• extend admin account GraphQL with:
  • adminListAccountsForSupport
  • adminGetAccountSupportDetail
  • adminUpdateAccountStatus
• extend account service with support detail projection and validated status servicing mutation
• reuse audit log service for durable account-servicing audit entries
• reuse existing transactions, transfers, and notifications collections for support context

Merchant portal additions

• replace the placeholder support page with a real support workspace
• add account list/search, detail panel, recent activity sections, and permissioned servicing form
• show controls conditionally based on account.manage

Persistence approach

• no new collection is required
• reuse existing collections:
  • accounts
  • transactions
  • transfers
  • notifications
  • audit_logs

Technical architecture / data flow

flowchart LR
  Staff[Authenticated staff user] --> MP[rl-bank-mp-webapp support workspace]
  MP --> GQL[rl-bank-api GraphQL]
  GQL --> Guard[Staff auth + permission guard]
  GQL --> AccountSvc[Account service]
  AccountSvc --> AccountDB[(accounts)]
  AccountSvc --> TxDB[(transactions)]
  AccountSvc --> TransferDB[(transfers)]
  AccountSvc --> NotificationDB[(notifications)]
  AccountSvc --> AuditSvc[Auditlog service]
  AuditSvc --> AuditDB[(audit_logs)]

Flow: support account review

1. staff opens support workspace
2. merchant portal queries support account list
3. staff selects an account
4. API returns account snapshot, recent transactions, recent transfers, notifications, and latest audit events

Flow: freeze account

1. staff selects Freeze account
2. portal submits target status FROZEN with reason
3. API validates staff permission + allowed transition
4. account status updates
5. audit log entry is recorded
6. updated support detail is returned to the portal

Flow: unfreeze account

Same as freeze, but target status becomes ACTIVE.

Flow: close account

1. staff selects Close account
2. portal requires reason and stronger confirmation copy
3. API validates current status is ACTIVE or FROZEN
4. account status updates to CLOSED
5. audit log entry is recorded
6. updated detail is returned

Permissions / access model

Staff permissions

• account.read
  • may list support accounts
  • may view support account detail and recent read-only context
• account.manage
  • may update support account status
  • implies use of freeze / unfreeze / close actions when already allowed to read

Role mapping recommendation

• ADMIN: include account.manage
• OPERATIONS: include account.manage
• SUPPORT: keep read-only by default in this slice unless explicitly granted
• CARD_OFFICER: no support account servicing permission

Least-privilege impact

• no new AWS IAM permissions are required; this is application-layer authorization inside the existing API
• the new permission is internal app authz only and should not widen infrastructure credentials

Notes / exceptions

• IaC / AWS architecture change: none; this slice is application-layer only.
• PBX impact: none.