Reconciliation — engineering

Runtime shape

Seven Cloud Run services (README) plus exception-service, coordinated by Pub/Sub and BigQuery. Engine fans windows to workers; Redis supports session/pipeline state; DLQ replay prevents silent loss.

flowchart LR
  ing[bk_ingestion] --> names[bk_name_worker]
  ing --> rev[bk_reversals]
  rev --> eng[bk_recon_engine]
  eng --> workers[bk_recon_worker]
  workers --> eng
  eng --> load[bk_loader]
  workers --> dlq[bk_dlq_replay]
  exc[exception_service] --> eng

Layout

banking-reconciliation-ai-backend/
  microservices/
    ingestion/ reconciliation-engine/ loader/ reversals/ exception-service/
  cloud-functions/
    name-worker/ reconciliation-worker/ recon-work-dlq-replay/ ingest-worker/
  shared/
  docs/          # contracts + flagged inconsistencies
  Makefile
  head-cloudbuild.yaml

Happy-path trail (money)

1. POST /v1/ingestion/background → ETL to BigQuery + publish names-work-topic-<env>
2. Name worker POST /extract-names → cache / Gemini → session_name_results
3. Reversals → engine POST /v1/reconcile/banking
4. Engine publishes recon-work-topic-<env> (pull by default)
5. Worker matches window → recon-complete push → /v1/reconcile/complete-batch
6. Loader persists matches / updates backend
7. Failures → DLQ → POST /replay

Invariants

• Do not drop DLQ messages without an operational decision.
• Exception resolve scope: partner + tenant + domain + cluster type (exception_resolution.md).
• Asset flows use separate ingest endpoint and event contract.
• Prefer router paths when README disagrees (e.g. reversals /pipeline/background vs README /background).

Local

cd banking-reconciliation-ai-backend
make run-all    # or make run-core
# APP_ENVIRONMENT=local → sequential matching

Ports: ingestion 8001, engine 8002, loader 8003, reversals 8004, exception-service 8005.

Flagged inconsistencies

docs/FLAGGED-inconsistencies.md — behaviour-preserving metric/summary quirks awaiting product decisions. Do not “quietly fix” in drive-by changes.