rl-docs-hub

Home · Apps · rl-bank-mvp

---

Card servicing + activity feed slice

Status: Draft, implementation-aligned for the current feature slice.

Why this slice

The next coherent fake-bank slice is a customer self-service layer on top of the already-live account, card, and transfer/application foundations.

Instead of adding another request workflow, this slice makes existing products feel more bank-like by adding:

• richer card servicing controls for issued cards
• a lightweight activity + notifications experience for customers
• a small, safe hook for per-user debug tracing metadata so support can correlate service actions when needed

Product / feature scope

In scope

• customer can view issued cards with clearer servicing state
• customer can freeze or unfreeze an eligible card
• customer can update a card spending limit within defined rules
• customer can view a lightweight activity feed that combines:
  • card servicing events
  • issued-card milestones
  • recent transfer / transaction milestones
• customer can view lightweight notifications derived from those events
• API returns a debug correlation identifier with servicing mutations and activity items when available
• customer mobile app and customer web app both surface the same core experience

Out of scope

• physical card replacement / reissue logistics
• PIN reveal / PIN set / CVV reveal
• postal-address servicing
• merchant portal servicing workflows
• push/email/SMS delivery orchestration to external providers
• admin case-management tooling
• persistent distributed tracing infrastructure beyond lightweight correlation metadata

Product design

Customer experience shape

• Cards page becomes a servicing surface, not only a card-application surface.
• Each issued card shows:
  • product name
  • masked PAN
  • linked account summary
  • current status
  • servicing actions when allowed
  • spending limit
• A lightweight Activity section shows the most recent customer-relevant events in reverse chronological order.
• A lightweight Notifications section highlights a smaller subset of important events with read/unread state.

Interaction rules

• freeze/unfreeze actions should feel immediate and optimistic only after API success
• servicing actions must be disabled for cards that are not customer-manageable
• activity should be concise, readable, and obviously fake-bank safe
• UI language should avoid implying real money movement finality beyond the fake-bank/demo context already established elsewhere

Business logic and rules

Card servicing rules

1. Only the authenticated customer who owns the card may service it.
2. Card must belong to an active customer-owned account.
3. Card statuses:
   • ACTIVE → can be frozen
   • FROZEN → can be unfrozen
   • PENDING_ISSUANCE → cannot be customer-frozen/unfrozen
   • CLOSED → cannot be serviced
4. Spending-limit updates are allowed only for non-closed cards.
5. Spending limit must be within a safe range for the fake-bank demo:
   • minimum 500
   • maximum 20000
6. If a requested state change is already true, the API should succeed idempotently and return the latest card state.
7. Servicing actions should create an activity event and a lightweight in-app notification record.

Activity / notification rules

1. Activity feed is customer-scoped only.
2. Activity feed is reverse-chronological.
3. Activity combines:
   • card service events
   • card issuance / activation milestones
   • transfer / transaction milestones already stored in the platform
4. Notifications are a curated subset of activity events intended for inbox-style display.
5. Notifications support lightweight read acknowledgment in-app only.
6. Notification delivery status is internal metadata; this slice does not send real external messages.

Debug tracing rule

• Each servicing mutation should generate or propagate a debug correlation id so support/devs can trace a user-visible action through logs without exposing secrets.
• This id is not an auth token and carries no privilege.

Technical design summary

API additions

• extend card service/resolver with customer servicing mutations
• implement a real notification module with customer-scoped list + mark-read behavior
• introduce a lightweight activity service that projects items from card events and transaction history
• attach debug correlation ids to servicing responses and generated activity items

App additions

• customer mobile app:
  • add servicing controls on issued cards
  • add an activity / notifications section
• customer web app:
  • same core servicing controls and feed behavior

Data persistence approach

This slice prefers small additive collections/fields over invasive rewrites:

• reuse existing audit_logs for customer card-service events
• add in-app notification persistence with read timestamps
• reuse transactions for transaction-derived activity items

Technical architecture / data flow

flowchart LR
  User[Authenticated customer] --> App[Mobile or Web customer app]
  App --> GQL[rl-bank-api GraphQL]
  GQL --> CardSvc[Card service]
  GQL --> ActivitySvc[Activity service]
  GQL --> NotificationSvc[Notification service]
  CardSvc --> CardDB[(cards)]
  CardSvc --> EventDB[(audit_logs)]
  NotificationSvc --> NotificationDB[(notifications)]
  ActivitySvc --> TxDB[(transactions)]
  ActivitySvc --> EventDB
  NotificationSvc --> EventDB
  CardSvc --> Logs[App logs / debug correlation]

Flow: freeze card

1. customer triggers freeze in app
2. GraphQL mutation validates ownership + card state
3. card status updates to FROZEN
4. card service event is written
5. notification record is written
6. response returns updated card + debug correlation id
7. apps refresh cards/activity/notifications

Flow: unfreeze card

Same as freeze, but target status is ACTIVE.

Flow: update spending limit

1. customer submits new limit
2. API validates ownership + min/max range
3. card spending limit updates
4. card service event is written with old/new value summary
5. notification record is written
6. response returns updated card + debug correlation id

Permissions / access model

Customer permissions

• authenticated customer may only access their own:
  • cards
  • accounts
  • transactions/activity
  • notifications
• customer may mutate only their own eligible cards and notifications

API guard model

• GraphQL auth guard remains mandatory
• customer ownership checks remain mandatory at the service layer
• no staff/admin-only permissions are added for this slice

Least-privilege impact

• no new AWS IAM permissions should be required for this slice if persistence remains in the existing database
• if log correlation config is added, it must remain runtime-local and not widen privileges

Notes / exceptions

• IaC / AWS architecture change: not applicable for this slice beyond existing API/app hosting, because the work is application-layer only.
• PBX impact: none for this slice.