📃 Module: Account Listing

ID: account-listing | Legacy Source: CBACT01C.cbl + bridge.py:get_all_accounts() + Flask GET /

This guide provides the technical foundation and User Story patterns for the Account Listing module — a paginated, searchable view of all accounts migrated from a COBOL sequential flat-file reader to a .NET 8 REST API with a React frontend.

🏗️ Technical Foundation

Layer	Target Component	Legacy Equivalent
API Controller	`AccountsController.cs`	Flask `GET /` route in `app.py`
Application Query	`ListAccountsQuery.cs` + `ListAccountsQueryHandler.cs`	`bridge.py:get_all_accounts()`
Response DTO	`AccountSummaryDto.cs`	ACCT01\|pipe-delimited stream (CBACT01C)
Data Access	EF Core `AccountRepository.cs` (PostgreSQL)	CBACT01C sequential read of `acctdata.txt` (300-byte records)
React Page	`AccountListPage.tsx`	`templates/accounts.html` (Jinja2)
React Component	`AccountDataTable.tsx`	HTML table in `accounts.html`
React Hook	`useAccounts.ts` (TanStack Query)	Server-side render (no client state)

🌐 Public API

GET /api/accounts

Returns a paginated list of account summaries with optional filtering.

Query Parameters

Parameter	Type	Default	Description
`page`	int	1	Page number (1-based)
`pageSize`	int	50	Results per page (max 200)
`status`	string	—	`Y` (active only) \| `N` (inactive only)
`search`	string	—	Filter by account ID prefix or group ID

Response Shape

{
  "data": [
    {
      "id": 4000000111,
      "activeStatus": "Y",
      "currentBalance": 1234.56,
      "creditLimit": 5000.00,
      "openDate": "2018-03-15",
      "groupId": "GOLD"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 350,
  "totalPages": 7
}

📐 Data Model Involved

// AccountSummaryDto — surface only what the list view needs
public record AccountSummaryDto(
    long Id,
    string ActiveStatus,        // "Y" | "N"
    decimal CurrentBalance,
    decimal CreditLimit,
    DateOnly OpenDate,
    string GroupId
);

🎯 User Story Development Patterns

Story Template

As a [Persona],
I want to [Action],
So that [Business Value].

Acceptance Criteria:
  Given [context],
  When [action],
  Then [expected outcome].

Backlog Stories for This Module

US-AL-01 · View Account List (3 pts)
As a bank clerk, I want to view a list of all accounts with their ID, status, current balance, credit limit, and group ID, so that I can get a quick overview of all accounts in the system.

Given the user navigates to the account list, When the page loads, Then a paginated table shows 50 accounts per page with columns: ID, Status, Balance, Credit Limit, Open Date, Group.
Given 350 accounts exist, When the user is on page 1, Then pagination controls show "Page 1 of 7" and a "Next" button is active.
Given no accounts exist, When the page loads, Then an empty state message is shown: "No accounts found."
The API call GET /api/accounts?page=1&pageSize=50 must respond in <200ms P95.

US-AL-02 · Filter Active/Inactive Accounts (2 pts)
As a bank clerk, I want to filter the account list by active status (Active / Inactive / All), so that I can focus on a subset of accounts.

Given the user selects "Active" in the status filter, When the filter is applied, Then only accounts with activeStatus = "Y" are shown.
Given the user selects "Inactive", Then only accounts with activeStatus = "N" are shown.
Given the user selects "All" (default), Then all accounts are shown regardless of status.

US-AL-03 · Search Accounts by ID or Group (3 pts)
As a bank clerk, I want to search accounts by account ID prefix or group ID, so that I can quickly locate a specific account or a set of accounts.

Given the user types "40000" in the search field, When results render, Then only accounts whose ID starts with "40000" are listed.
Given the user types "GOLD", Then accounts with groupId = "GOLD" are listed.
The search must be debounced (300ms) and not submit a request on every keystroke.

US-AL-04 · Navigate to Account Detail from List (1 pt)
As a bank clerk, I want to click on an account in the list to navigate to its detail page, so that I can view full account information without manually typing an account ID.

Given the user clicks on account row 4000000111, When clicked, Then the user is navigated to /accounts/4000000111.

📊 Story Complexity Guidelines

Points	Example
1–2	Add a new column to the table, change sort order default.
3–5	Add filtering or search with debounce and TanStack Query integration.
8+	Full CSV export with server-side streaming; real-time account status updates via WebSockets.

⚡ Performance Requirements

GET /api/accounts response time: <200ms P95 for up to 10,000 accounts.
Account list page LCP: <2s on a standard broadband connection.
Add database index on accounts.active_status and accounts.group_id to support filtering.