UTA Sub-Ledger — CNB Integration Decisions Log
Purpose: Append-only record of all binding architectural, design, and scope decisions.
Rule: Once logged, a decision is closed. Re-opening requires a new entry that supersedes the prior one.
Format:[DEC-XXX] | Date | Decision | Rationale | Decided By | Closes / Affects
Architectural Decisions
[DEC-001] | 2026-Q1 | REST-first hybrid architecture adopted
Decision: The integration uses JSON REST as the primary outbound command layer for all payment initiation, status, account balance, and FX services. SFTP is used for inbound audit/reporting (BAI2, IFX XML). A single isolated SOAP adapter class handles check image retrieval only, with internals abstracted so they can be swapped when CNB ships a REST equivalent.
Rationale: CNB is actively migrating services from SOAP to REST. Building REST-first avoids locking into a legacy stack. SFTP is unavoidable for BAI2 specifically.
Decided by: Cliff / Amir
Affects: All feature areas. SOAP is not a valid integration path except for the isolated check image adapter.
[DEC-002] | 2026-Q1 | SOAP/WCF layer formally excluded from scope
Decision: CNB's SOAP implementation requires stacked WS-Security with X.509 mutual certificate auth, WSTrust February 2005 bindings, SecureConversation bootstrapping, Basic256Rsa15 encryption, SignBeforeEncrypt message ordering, and signature confirmation. This is incompatible with the REST-first codebase and will not be implemented.
Rationale: Configuration is brittle, hard to maintain, and CNB is migrating away from it. Any currently-SOAP-only service either gets an SFTP file alternative or waits for a REST equivalent.
Decided by: Cliff / Amir
Affects: FEAT-009 Stop Payment (pending Amir decision on portal vs. adapter), FEAT-005 Check Images (pending REST confirmation from CNB).
[DEC-003] | 2026-Q1 | Two-step reconciliation model adopted
Decision: Reconciliation runs in two independent daily steps. Step 1 (fully automated): bank vs. sub-ledger match using the formal reconciliation equation when BAI2 lands at ~6 AM PT. Step 2 (GL user approval): sub-ledger vs. NetSuite delta comparison, expected completed by end of business.
Rationale: Separates automated bank matching from human GL approval. Errors are never more than one day old. Sub-ledger is the exclusive owner of bank data; NetSuite receives only Journal Entries.
Decided by: Cliff
Affects: FEAT-011 End-of-Day Brakes, FEAT-012 Reconciliation Logic.
[DEC-004] | 2026-Q1 | Formal reconciliation equation required (not simple balance comparison)
Decision: Step 1 reconciliation must balance the equation: Bank Closing Balance (BAI2) + Deposits in Transit − Outstanding Checks = Sub-Ledger Book Balance. A simple balance match is insufficient.
Rationale: Two offsetting errors can make balances appear to match while underlying records are wrong. The equation only balances if individual reconciling items are correct.
Decided by: Cliff
Affects: FEAT-012 Reconciliation Logic.
[DEC-005] | 2026-Q1 | NetSuite receives Journal Entries only — no direct bank data
Decision: BAI2, IFX XML, and all raw bank data are ingested and processed by the sub-ledger only. NetSuite is kept at the pure GL level. No bank data format touches NetSuite directly.
Rationale: Clean separation of concerns. Sub-ledger owns the bank relationship; NetSuite owns the GL.
Decided by: Cliff
Affects: All reconciliation and posting features.
[DEC-006] | 2026-Q1 | SFTP topology is client-pull (UTA → CNB), not bank-push
Decision: UTA's system connects outbound to CNB's SFTP server to pull files. CNB does not push files to UTA infrastructure.
Rationale: Confirmed from CNB documentation. Affects firewall rules, credential management, and scheduler design.
Decided by: CNB (confirmed from EASI-Link docs)
Affects: FEAT-010 Inbound Audit Layer, FEAT-011 End-of-Day Brakes.
[DEC-007] | 2026-Q1 | EOD reconciliation runs against prior day's closed dataset (one-day lag is expected)
Decision: BAI2 reflects the prior business day's closed transactions. EOD reconciliation is therefore always T-1. This is normal and expected, not a defect.
Rationale: BAI2 is a prior-day file by definition. Current-day activity is handled via intraday SFTP/IFX polling.
Decided by: Cliff
Affects: FEAT-011 End-of-Day Brakes, FEAT-012 Reconciliation Logic.
[DEC-008] | 2026-Q1 | DepAcctStmtInq is one service with two modes (date parameter controls current vs. prior day)
Decision: DepAcctStmtInq (SOAP DDA reporting) uses a single service endpoint controlled by the SelRangeDt date parameter. When StartDt = EndDt = today, it returns current-day activity. When StartDt = EndDt = yesterday, it returns the prior-day closed set.
Rationale: Not two separate services. Architects must not split these into separate integration paths.
Decided by: Cliff (sourced from EASI-Link Appendix B v14.1.0, p. 104)
Affects: FEAT-005 Intraday Engine, FEAT-011 End-of-Day Brakes.
[DEC-009] | 2026-Q1 | GetDDABalance returns a balance number only — line-item matching requires DepAcctStmtInq
Decision: GetDDABalance returns ledgerBalance and availableBalance as scalar numbers. It cannot be used for transaction-level reconciliation. Line-by-line matching requires DepAcctStmtInq.
Rationale: Sourced from REST JSON 2025 spec. Prevents incorrect use of balance endpoint as a substitute for transaction reporting.
Decided by: Cliff
Affects: FEAT-002 Pre-Flight, FEAT-012 Reconciliation Logic.
[DEC-010] | 2026-Q1 | Book Transfers (Account Transfer / CNS Transfer) must post as two offsetting JEs — never a single net entry
Decision: Any AccountTransfer or CNSTransfer must result in two Journal Entries in NetSuite: debit source account GL, credit destination account GL. CNB confirmation reference used as memo.
Rationale: Single net entry would obscure the cash movement in the GL and break the audit trail.
Decided by: Cliff
Affects: FEAT-003 Payment Initiation (book transfer subtype), FEAT-012 Reconciliation Logic.
[DEC-011] | 2026-Q1 | Failed Postings Queue specified for four failure modes
Decision: A Failed Postings Queue captures: (1) technical failure (API/network), (2) closed accounting period, (3) missing GL account mapping, (4) duplicate rejection. All four modes are handled by the queue, not silent failure.
Rationale: Silent failures in GL posting are unacceptable for audit purposes.
Decided by: Cliff
Affects: All payment and posting features.
[DEC-012] | 2026-Q1 | OAuth 2.0 Bearer Token with 10-minute TTL — proactive refresh required
Decision: CNB authentication uses OAuth 2.0 Bearer Token from https://sso.cityntl.com/as/token.oauth2. Token TTL is 599 seconds (~10 minutes). Application must implement proactive refresh before expiry — not reactive on 401.
Rationale: Reactive refresh on 401 creates a race condition during intraday loops. Proactive refresh at ~8 minutes eliminates mid-request token expiry.
Decided by: Cliff (sourced from EASI-Link AppendixB JSON 2025, p. 3)
Affects: FEAT-001 Authentication — all other features depend on this.
[DEC-013] | 2026-Q1 | Intraday polling cadence: ~30-minute SFTP sweep + 30-minute Change Status offset by 15 minutes
Decision: SFTP sweep runs every 30 minutes. Change Status Inquiry (getChangedStatus) runs every 30 minutes, offset 15 minutes from SFTP sweep so the two channels are staggered. GetDDABalance runs at BOD and EOD only.
Rationale: Staggering prevents simultaneous load spikes. Dual-channel approach (SFTP + REST status) gives redundant coverage.
Decided by: Cliff
Affects: FEAT-005 Intraday Engine.
[DEC-014] | 2026-04-20 | DEC-001 SUPERSEDED — Full REST + SOAP dual-layer architecture adopted
Supersedes: DEC-001 (REST-first hybrid) and DEC-002 (SOAP excluded)
Decision: The integration now uses both the JSON REST API and the SOAP/IFX layer as first-class integration paths. REST remains the primary layer for payment initiation, status inquiry, account balance, and FX. SOAP is now a fully supported layer for all DDA reporting services (DepAcctStmtInq, IWN), check image retrieval (ImagePaidCheck, ImageDepositItem), statement image, and stop payment. SFTP remains for BAI2 inbound audit. There is no longer a restriction on SOAP use — service selection is driven by which layer provides the best capability for each feature, not by a blanket protocol preference.
Rationale: Amir (dev lead) confirmed that the WS-Security configuration overhead is manageable with AI-assisted development. The complexity that previously justified exclusion is no longer a blocker. SOAP unlocks check images, direct IWN polling, and stop payment without waiting for CNB REST equivalents.
Decided by: Amir Hajizadeh (Engineering) / Cliff (Product) — 2026-04-20
Affects: All feature areas. See downstream impact table below.
Downstream impact of DEC-014:
| Feature | Previous State | New State |
|---|---|---|
| FEAT-005 Intraday Engine | SFTP-only for IWN (30-min lag) | SOAP DepAcctStmtInq + SOAP IWN — direct polling, no file lag |
| FEAT-006 Payment Receipts | Blocked on CNB REST webhook confirmation | SOAP IWN now available immediately |
| FEAT-007 Stop Payment | Blocked on Amir decision (DEC-P001) | SOAP StopPayment / StopPaymentCancel — confirmed in scope |
| FEAT-009 Check Images | Blocked on CNB REST confirmation (OI-CK-001) | SOAP ImagePaidCheck + ImageDepositItem — available now |
| FEAT-010 Inbound Audit | SFTP-only | SFTP for BAI2 + SOAP for statement image and transaction detail |
| OI-005-002 IWN REST webhook | Open — blocking intraday | Closed — SOAP IWN is the solution |
| OI-CK-001 Check image REST | Open — blocking images | Closed — SOAP path now in scope |
| OI-007-001 Stop Payment routing | Open — pending Amir | Closed — SOAP adapter confirmed |
[DEC-015] | 2026-04-20 | DEC-002 SUPERSEDED — SOAP/WCF configuration overhead accepted; AI-assisted implementation approved
Supersedes: DEC-002
Decision: The WS-Security stack previously cited as a blocker (X.509 mutual certificate auth, WSTrust February 2005 bindings, SecureConversation bootstrapping, Basic256Rsa15 encryption, SignBeforeEncrypt message ordering) will be implemented. The complexity is acknowledged but deemed manageable with AI-assisted development tooling.
Rationale: DEC-002 was a risk/cost decision, not a technical impossibility. With AI reducing the implementation effort, the calculus changes. Unlocking SOAP removes multiple open items and eliminates dependency on CNB REST roadmap timeline.
Decided by: Amir Hajizadeh (Engineering) — 2026-04-20
Note for dev team: The SOAP adapter should still be encapsulated behind a service interface so individual SOAP calls can be swapped for REST equivalents when CNB ships them, without changing calling code. This is now a clean-architecture preference, not a blocker.
Open / Pending Decisions
| DEC-ID | Question | Owner | Status |
|---|---|---|---|
| CLOSED — SOAP adapter confirmed (DEC-014/DEC-015) | |||
| DEC-P002 | Check Images: CNB REST alternative confirmed? | Jerome (CNB) | Deprioritized — SOAP path now in scope (DEC-014); REST still preferred if available |
| DEC-P003 | Intraday SFTP: sub-30-min cadence available? | Jerome (CNB) | Deprioritized — SOAP IWN eliminates the lag concern (DEC-014) |
| DEC-P004 | IWN REST webhook: any REST push alternative for wire credits? | Jerome (CNB) | Deprioritized — SOAP IWN is the confirmed solution (DEC-014) |
Log version: 1.1 — 2026-04-20: DEC-014, DEC-015 added. DEC-001, DEC-002 superseded. DEC-P001/P003/P004 closed or deprioritized.