refactor: rename accounts → pb_accounts (Phase 1 of normal accounts) (#26)

* docs: design for normal accounts (single-pool) alongside PB accounts

Introduces normal accounts as a parallel domain backed by a single
TigerBeetle account. Trust money enters via a normal account and reaches
PB accounts only through internal transfers; the direct trust→PB
deposit path is removed.

Covers schema (rename accounts→pb_accounts, new normal_accounts,
transactions discriminator + correlation_id), API surface
(/pb-accounts and /normal-accounts canonical, /accounts as in-process
alias with Sunset headers), service & ledger conventions, transfer
flow with shared correlation_id and tb_transfer_id across two journal
rows, and a three-PR rollout plan.

Bite-sized, TDD-driven plan covering all three phases: rename
accounts→pb_accounts (PR 1), add normal accounts (PR 2), and
add normal→PB transfers + remove direct trust deposit (PR 3).

Author: knutties

crates/pba_service/src/admin/handlers.rs

@@ -48,15 +48,15 @@ struct DashboardTemplate {
 }
 
 pub async fn dashboard(State(state): State<AppState>) -> Response {
-    let status_counts = match state.account_repo.count_accounts_by_status().await {
+    let status_counts = match state.pb_account_repo.count_accounts_by_status().await {
         Ok(c) => c,
         Err(e) => {
             tracing::error!("Failed to count accounts: {e}");
             return (StatusCode::INTERNAL_SERVER_ERROR, "Database error").into_response();
         }
     };
 
-    let purpose_counts = match state.account_repo.count_accounts_by_purpose().await {
+    let purpose_counts = match state.pb_account_repo.count_accounts_by_purpose().await {
         Ok(c) => c,
         Err(e) => {
             tracing::error!("Failed to count by purpose: {e}");
@@ -114,15 +114,15 @@ async fn render_accounts_list(
     error: Option<String>,
     success: Option<String>,
 ) -> Response {
-    let accounts = match state.account_repo.list_accounts().await {
+    let accounts = match state.pb_account_repo.list_accounts().await {
         Ok(a) => a,
         Err(e) => {
             tracing::error!("Failed to list accounts: {e}");
             return (StatusCode::INTERNAL_SERVER_ERROR, "Database error").into_response();
         }
     };
 
-    let purpose_codes = match state.account_repo.list_purpose_types().await {
+    let purpose_codes = match state.pb_account_repo.list_purpose_types().await {
         Ok(pts) => pts.into_iter().map(|p| p.purpose_code).collect(),
         Err(_) => vec![],
     };
@@ -193,7 +193,7 @@ pub async fn create_account(
     };
 
     match state
-        .account_service
+        .pb_account_service
         .create_account(
             holder_id,
             &form.purpose_code,
@@ -229,7 +229,7 @@ pub async fn update_account_status(
     };
 
     match state
-        .account_service
+        .pb_account_service
         .update_status(account_id, status)
         .await
     {
@@ -278,7 +278,7 @@ pub async fn account_detail(
     State(state): State<AppState>,
     Path(account_id): Path<Uuid>,
 ) -> Response {
-    let account = match state.account_repo.get_account(account_id).await {
+    let account = match state.pb_account_repo.get_account(account_id).await {
         Ok(a) => a,
         Err(e) => {
             tracing::error!("Account not found: {e}");
@@ -463,7 +463,7 @@ struct DepositTemplate {
 }
 
 pub async fn deposit_form(State(state): State<AppState>, Path(account_id): Path<Uuid>) -> Response {
-    let account = match state.account_repo.get_account(account_id).await {
+    let account = match state.pb_account_repo.get_account(account_id).await {
         Ok(a) => a,
         Err(_) => return (StatusCode::NOT_FOUND, "Account not found").into_response(),
     };
@@ -495,7 +495,7 @@ pub async fn process_deposit(
     let gateway_ref = form.gateway_ref.as_deref().filter(|s| !s.is_empty());
     let funding_type = form.funding_type.as_deref().filter(|s| !s.is_empty());
     match state
-        .deposit_service
+        .pb_deposit_service
         .deposit(
             account_id,
             &form.source_ifsc,
@@ -513,7 +513,7 @@ pub async fn process_deposit(
             .into_response(),
         Err(e) => {
             let purpose_code = state
-                .account_repo
+                .pb_account_repo
                 .get_account(account_id)
                 .await
                 .map(|a| a.purpose_code)
@@ -533,7 +533,7 @@ pub async fn post_deposit(
     Path((account_id, deposit_id)): Path<(Uuid, Uuid)>,
 ) -> Response {
     match state
-        .deposit_service
+        .pb_deposit_service
         .post_deposit(account_id, deposit_id)
         .await
     {
@@ -552,7 +552,7 @@ pub async fn void_deposit(
     Path((account_id, deposit_id)): Path<(Uuid, Uuid)>,
 ) -> Response {
     match state
-        .deposit_service
+        .pb_deposit_service
         .void_deposit(account_id, deposit_id, None)
         .await
     {
@@ -576,7 +576,7 @@ struct PaymentTemplate {
 }
 
 pub async fn payment_form(State(state): State<AppState>, Path(account_id): Path<Uuid>) -> Response {
-    let account = match state.account_repo.get_account(account_id).await {
+    let account = match state.pb_account_repo.get_account(account_id).await {
         Ok(a) => a,
         Err(_) => return (StatusCode::NOT_FOUND, "Account not found").into_response(),
     };
@@ -604,7 +604,7 @@ pub async fn process_payment(
 ) -> Response {
     let gateway_ref = form.gateway_ref.as_deref().filter(|s| !s.is_empty());
     match state
-        .payment_service
+        .pb_payment_service
         .make_payment(
             account_id,
             form.amount,
@@ -620,7 +620,7 @@ pub async fn process_payment(
             .into_response(),
         Err(e) => {
             let purpose_code = state
-                .account_repo
+                .pb_account_repo
                 .get_account(account_id)
                 .await
                 .map(|a| a.purpose_code)
@@ -648,7 +648,7 @@ pub async fn withdrawal_form(
     State(state): State<AppState>,
     Path(account_id): Path<Uuid>,
 ) -> Response {
-    let account = match state.account_repo.get_account(account_id).await {
+    let account = match state.pb_account_repo.get_account(account_id).await {
         Ok(a) => a,
         Err(_) => return (StatusCode::NOT_FOUND, "Account not found").into_response(),
     };
@@ -673,15 +673,15 @@ pub async fn process_withdrawal(
 ) -> Response {
     let gateway_ref = form.gateway_ref.as_deref().filter(|s| !s.is_empty());
     match state
-        .withdrawal_service
+        .pb_withdrawal_service
         .withdraw(account_id, form.amount, None, gateway_ref)
         .await
     {
         Ok(_) => Redirect::to(&prefixed(&state, &format!("/admin/accounts/{account_id}")))
             .into_response(),
         Err(e) => {
             let purpose_code = state
-                .account_repo
+                .pb_account_repo
                 .get_account(account_id)
                 .await
                 .map(|a| a.purpose_code)
@@ -929,7 +929,7 @@ struct PurposeTypesTemplate {
 }
 
 pub async fn purpose_types_page(State(state): State<AppState>) -> Response {
-    let purpose_types = match state.account_repo.list_purpose_types().await {
+    let purpose_types = match state.pb_account_repo.list_purpose_types().await {
         Ok(pts) => pts,
         Err(e) => {
             tracing::error!("Failed to list purpose types: {e}");
@@ -993,7 +993,7 @@ pub async fn transaction_detail(
 
     let dash = "—".to_string();
 
-    let (holder_id, purpose_code) = match state.account_repo.get_account(txn.account_id).await {
+    let (holder_id, purpose_code) = match state.pb_account_repo.get_account(txn.account_id).await {
         Ok(a) => (a.holder_id, a.purpose_code),
         Err(e) => {
             tracing::warn!("Failed to load parent account for transaction {transaction_id}: {e}");
@@ -1101,7 +1101,7 @@ pub async fn post_transaction(
         Err(_) => return (StatusCode::NOT_FOUND, "Transaction not found").into_response(),
     };
     if let Err(e) = state
-        .deposit_service
+        .pb_deposit_service
         .post_deposit(txn.account_id, transaction_id)
         .await
     {
@@ -1123,7 +1123,7 @@ pub async fn void_transaction(
         Err(_) => return (StatusCode::NOT_FOUND, "Transaction not found").into_response(),
     };
     if let Err(e) = state
-        .deposit_service
+        .pb_deposit_service
         .void_deposit(txn.account_id, transaction_id, None)
         .await
     {

crates/pba_service/src/api/handlers.rs

@@ -18,7 +18,7 @@ pub async fn create_account(
     let origin_account_number = AccountNumber::parse(&req.origin_account_number)?;
 
     let account = state
-        .account_service
+        .pb_account_service
         .create_account(
             &req.holder_id,
             &req.purpose_code,
@@ -34,7 +34,7 @@ pub async fn get_account(
     State(state): State<AppState>,
     Path(account_id): Path<Uuid>,
 ) -> Result<Json<AccountResponse>, AppError> {
-    let account = state.account_service.get_account(account_id).await?;
+    let account = state.pb_account_service.get_account(account_id).await?;
     Ok(Json(account.into()))
 }
 
@@ -46,7 +46,7 @@ pub async fn update_account_status(
     let status = AccountStatus::from_str(&req.status)
         .ok_or_else(|| AppError::DatabaseError(format!("Invalid status: {}", req.status)))?;
     let account = state
-        .account_service
+        .pb_account_service
         .update_status(account_id, status)
         .await?;
     Ok(Json(account.into()))
@@ -58,7 +58,7 @@ pub async fn get_balance(
     State(state): State<AppState>,
     Path(account_id): Path<Uuid>,
 ) -> Result<Json<BalanceResponse>, AppError> {
-    let account = state.account_service.get_account(account_id).await?;
+    let account = state.pb_account_service.get_account(account_id).await?;
     let balance = state
         .ledger_repo
         .get_balance(account.tb_self_account_id, account.tb_others_account_id)
@@ -82,7 +82,7 @@ pub async fn deposit(
     Json(req): Json<DepositRequest>,
 ) -> Result<(axum::http::StatusCode, Json<DepositResponse>), AppError> {
     let result = state
-        .deposit_service
+        .pb_deposit_service
         .deposit(
             account_id,
             &req.source_ifsc,
@@ -116,7 +116,7 @@ pub async fn post_deposit(
     Path((account_id, deposit_id)): Path<(Uuid, Uuid)>,
 ) -> Result<Json<DepositResponse>, AppError> {
     let result = state
-        .deposit_service
+        .pb_deposit_service
         .post_deposit(account_id, deposit_id)
         .await?;
 
@@ -138,7 +138,7 @@ pub async fn void_deposit(
     Json(req): Json<VoidDepositRequest>,
 ) -> Result<Json<DepositResponse>, AppError> {
     let result = state
-        .deposit_service
+        .pb_deposit_service
         .void_deposit(account_id, deposit_id, req.reason.as_deref())
         .await?;
 
@@ -162,7 +162,7 @@ pub async fn make_payment(
     Json(req): Json<PaymentRequest>,
 ) -> Result<(axum::http::StatusCode, Json<PaymentResponse>), AppError> {
     let result = state
-        .payment_service
+        .pb_payment_service
         .make_payment(
             account_id,
             req.amount,
@@ -196,7 +196,7 @@ pub async fn withdraw(
     Json(req): Json<WithdrawalRequest>,
 ) -> Result<(axum::http::StatusCode, Json<WithdrawalResponse>), AppError> {
     let result = state
-        .withdrawal_service
+        .pb_withdrawal_service
         .withdraw(
             account_id,
             req.amount,
@@ -223,7 +223,7 @@ pub async fn list_transactions(
     axum::extract::Query(query): axum::extract::Query<ListTransactionsQuery>,
 ) -> Result<Json<ListTransactionsResponse>, AppError> {
     // Verify account exists
-    let _ = state.account_service.get_account(account_id).await?;
+    let _ = state.pb_account_service.get_account(account_id).await?;
 
     let offset = query.offset.unwrap_or(0).max(0);
     let limit = query.limit.unwrap_or(20).clamp(1, 100);
@@ -274,7 +274,7 @@ pub async fn list_all_transactions(
 pub async fn list_purpose_types(
     State(state): State<AppState>,
 ) -> Result<Json<ListPurposeTypesResponse>, AppError> {
-    let types = state.account_repo.list_purpose_types().await?;
+    let types = state.pb_account_repo.list_purpose_types().await?;
     Ok(Json(ListPurposeTypesResponse {
         purpose_types: types.into_iter().map(|t| t.into()).collect(),
     }))
@@ -284,7 +284,10 @@ pub async fn get_purpose_type(
     State(state): State<AppState>,
     Path(purpose_code): Path<String>,
 ) -> Result<Json<PurposeTypeResponse>, AppError> {
-    let purpose = state.account_repo.get_purpose_type(&purpose_code).await?;
+    let purpose = state
+        .pb_account_repo
+        .get_purpose_type(&purpose_code)
+        .await?;
     Ok(Json(purpose.into()))
 }
 

crates/pba_service/src/db/migrations/20260508000001_rename_accounts_to_pb_accounts.sql

@@ -0,0 +1,11 @@
+-- Rename the dual-pool account table to pb_accounts (purpose-bound).
+-- A future migration introduces normal_accounts as a sibling table.
+ALTER TABLE accounts RENAME TO pb_accounts;
+-- NOTE: idx_accounts_origin_purpose was already dropped in
+-- 20260428000001_drop_origin_purpose_uniqueness.sql; no rename needed here.
+ALTER INDEX idx_accounts_holder RENAME TO idx_pb_accounts_holder;
+
+-- The existing FK on transactions.account_id was created as
+-- transactions_account_id_fkey REFERENCES accounts(id). Postgres preserves
+-- the FK target across the rename automatically. We do NOT drop it here —
+-- the FK now points at pb_accounts(id), which is correct for Phase 1.