Public technical reference
Reliable Financial Integration & Transfer Architecture
A synthetic reference implementation for conservative integration design
A runnable, synthetic interview project that demonstrates financial-data and ACH-transfer integration design. It is deliberately not presented as a live banking system or production client work; its value is the clarity of its failure-mode and quality-engineering decisions.
Project outcomes
What changed in the work.
- Synthetic
- no real customer or financial data
- API + UI
- automated verification scenarios
- UNKNOWN
- explicit ambiguous-transfer state
- Role
- Architecture, implementation, test design, and technical documentation
- Scope
- backend · frontend · architecture · integrations · data · etl · security · testing
- Status
- Public technical reference
The problem
Start with the constraint.
Partner integrations create a tension between a responsive product experience and uncertain external state. A transfer request can time out after submission, webhooks can duplicate, and upstream reads can be stale. The system must be safe when it does not know the answer yet.
What I contributed
- Designed a Go API, Next.js interface, SQL Server read model, partner mock, and Docker Compose environment.
- Documented acceptance criteria, protected-data boundaries, failure behavior, and implementation decisions.
- Created deterministic mocks and browser/API verification around the core workflows.
Sanitized architecture
A tenant-scoped SQL read model supports a responsive experience while background reconciliation handles freshness and external uncertainty. The partner integration is represented by a deterministic mock rather than a live financial service.
Next.js interface
Presents read-model data and transfer workflow states.
Go service
Validates requests, preserves durable intent, and coordinates reconciliation.
SQL Server
Stores tenant-scoped snapshots, deduplication records, and freshness metadata.
Partner adapter and mock
Exercises failure paths without real financial data or accounts.
Engineering decisions
Context, choice, and tradeoff.
Use a local read model instead of blocking every screen on a partner API
Context: Users need a responsive view even when a partner is slow or unavailable.
Options: Call the partner synchronously for every read, or preserve a local snapshot with freshness information.
Decision: Use a SQL snapshot and asynchronous comparison/reconciliation path.
Tradeoff: The UI can show last-known-good information, but must make freshness explicit rather than pretending it is live.
Result: A responsive read experience designed around known data freshness boundaries.
Model ambiguous transfer submission explicitly
Context: A timeout after a transfer is submitted does not prove the transfer failed.
Options: Retry automatically, mark it failed, or preserve an unresolved state pending reconciliation.
Decision: Store durable intent and use an UNKNOWN state until reconciliation establishes the outcome.
Tradeoff: The workflow can require follow-up, but avoids creating a duplicate monetary action through an unsafe retry.
Result: Failure behavior is conservative by design rather than hidden behind a generic error message.
Treat webhooks as signals to reconcile, not the source of truth
Context: External events can be duplicated, delayed, or delivered out of order.
Options: Apply each webhook directly, or deduplicate it and reconcile against durable state.
Decision: Use a durable inbox/deduplication pattern and reconciliation workflow.
Tradeoff: Extra persistence and code paths are required, balanced by clearer event handling.
Result: Event processing is designed for repeat delivery and uncertain ordering.
Quality & operations
How the work is made operable.
- Structured logging redacts credentials and financial payloads at the boundary.
- Health checks, Docker Compose, deterministic mocks, and documented acceptance matrices make the demo reproducible.
- Go tests and Playwright API and UI scenarios verify expected and failure paths.
Lessons
What carries forward.
- The correct answer to an ambiguous money movement is often “not yet known.”
- Data freshness belongs in the product model, not only in background infrastructure.
- Executable documentation makes integration tradeoffs easier to review.
Want to discuss the technical decision-making behind this work?
Contact Kyle