Skip to content

Banking Reconciliation

Automates bank statement ↔ GL matching (and asset holdings ↔ custodian reports) with multi-stage rules, fuzzy matching, and Gemini-assisted steps.
Repo banking-reconciliation-ai-backend/
Runtime Cloud Run microservices + Pub/Sub workers + BigQuery
Status IMPLEMENTED

Why it exists

Finance ops upload statements and GL extracts. The platform parses files, resolves counterparty names, fans matching across windows, persists results, and supports exception workflows — with DLQ + replay so failed windows are not silently lost.

Happy path (money)

sequenceDiagram
  participant Client
  participant Ing as bk_ingestion
  participant NW as bk_name_worker
  participant Rev as bk_reversals
  participant Eng as bk_recon_engine
  participant W as bk_recon_worker
  participant Load as bk_loader
  Client->>Ing: POST /v1/ingestion/background
  Ing->>NW: names-work Pub/Sub
  Ing->>Rev: chain
  Rev->>Eng: reconcile
  Eng->>W: recon-work windows
  W->>Eng: complete-batch
  Eng->>Load: matches / session update

Evidence: README.md, FastAPI routers under microservices/, workers under cloud-functions/.

Services (README)

Service Local port Role Status
bk-ingestion 8001 ETL → BigQuery; start money or asset flow IMPLEMENTED
bk-name-worker 8080 Narration → name (POST /extract-names) IMPLEMENTED
bk-reversals 8004 GL reversal detection IMPLEMENTED
bk-recon-engine 8002 Orchestration + finalization IMPLEMENTED
bk-recon-worker 8080 Match one window (POST /process-window) IMPLEMENTED
bk-loader 8003 Persist matches; backend updates IMPLEMENTED
bk-recon-work-dlq-replay 8080 Replay / finalize DLQ (POST /replay) IMPLEMENTED
exception-service 8005 (Makefile) Detect + resolve exception clusters IMPLEMENTED

Apps use FastAPI root_path="/v1"; public paths are /v1/....

Integrator entry points

Concern Path (as documented in service README / routers) Status
Start money ingestion POST /v1/ingestion/background IMPLEMENTED
Start asset ingestion POST /v1/ingestion/asset IMPLEMENTED
Resolve exceptions POST /v1/exceptions/resolve IMPLEMENTED
Detect exceptions POST /v1/exceptions/banking/detect, /v1/exceptions/commercial/detect IMPLEMENTED

Money vs asset payloads are separated by endpoint (README). See Integrate — Reconciliation for engine/loader paths and README vs router notes.

Limitations

  • docs/FLAGGED-inconsistencies.md lists preserved metric inconsistencies awaiting decisions.
  • Banking exception resolution must not naively invoke full-period reconcile (side effects) — see reference docs.
  • APP_ENVIRONMENT=local uses sequential matching without worker fan-out.