B2B Banking Decisioning Platform

• Embedded B2B banking recommendation platform for client channels, RM tools, and internal banking decisioning.
• FastAPI prod API, separate sandbox service/UI, dedicated background worker, DB-backed offer registry, source-ingestion staging, materialized snapshots/features, feedback-driven learning loop, offline ranking-model training, Kafka events, Prometheus metrics, Postgres audit.
• Docker Compose environment for local development and manual testing.

Main capabilities

• Normalize client profile, relationship, transactions, and risk signals into a banking snapshot.
• Build explainable next-best-actions such as acquiring, credit line, overdraft, factoring, payroll, tariff optimization, FX tools, liquidity alerts, and treasury offers.
• Track recommendation history and client reaction, apply frequency capping, and adapt scores from acceptance/rejection feedback.
• Serve a dedicated sandbox UI for manual testing with synthetic B2B clients and scenarios.
• Materialize client snapshots and features from relational banking tables.
• Keep offer catalog and policy rules in a DB-backed registry with admin endpoints and JSON seed assets.
• Drain Kafka events from a durable outbox via a dedicated worker and run scheduled materialization refreshes.
• Load production-like source extracts into staging and merge them into normalized banking tables.
• Build a feature store and retrain bounded ranking models from recommendation history and feedback.
• Use an admin UI for registry edits, ingestion, retraining, DLQ, and ops checks.
• Provide synthetic data generator in services/b2b-rec-service/app/demo_bank_data/.

Layered architecture

• app/domain/decisioning/ contains pure business logic for catalog, feature extraction, policy, explanations, and ranking.
• app/application/ orchestrates use cases, request flows, and runtime assembly.
• app/infrastructure/ contains adapters for LLM, learning, repositories, and persistence wrappers.
• app/interfaces/http/ exposes separate prod and sandbox FastAPI applications.

Runtime profiles

• Prod API: http://localhost:8010
• Sandbox UI/API: http://localhost:8011
• Prod admin UI: http://localhost:8010/admin/ui
• Sandbox admin UI: http://localhost:8011/admin/ui
• Background worker: b2b-rec-worker

Prod endpoints

• POST /api/v1/recommendations
• POST /api/v1/recommendations/feedback
• GET /api/v1/internal/banking/clients
• GET /api/v1/internal/banking/clients/{client_id}/snapshot
• POST /api/v1/internal/recommendations/by-client/{client_id}
• GET /api/v1/internal/analytics/client/{client_id}
• GET /api/v1/internal/ops/status
• POST /api/v1/admin/registry/seed-defaults
• GET /api/v1/admin/registry/offers
• PUT /api/v1/admin/registry/offers/{offer_key}
• GET /api/v1/admin/registry/rules
• POST /api/v1/admin/registry/rules
• DELETE /api/v1/admin/registry/rules/{rule_id}
• GET /api/v1/admin/ops/status
• POST /api/v1/admin/materializations/refresh
• POST /api/v1/admin/outbox/publish
• GET /api/v1/admin/outbox/dlq
• POST /api/v1/admin/outbox/dlq/{event_id}/requeue
• POST /api/v1/admin/outbox/cleanup
• POST /api/v1/admin/ingestion/load-assets
• POST /api/v1/admin/ingestion/run
• POST /api/v1/admin/ml/feature-store/rebuild
• POST /api/v1/admin/ml/train
• GET /api/v1/admin/ml/models

Internal endpoints require header X-Internal-Service-Token. Admin endpoints require header X-Admin-Api-Key.

Sandbox endpoints

• GET /ui
• GET /api/v1/demo/clients
• GET /api/v1/demo/clients/{client_id}
• POST /api/v1/demo/recommendations/{client_id}
• GET /api/v1/analytics/client/{client_id}
• POST /api/v1/internal/banking/seed-demo-data
• POST /api/v1/internal/registry/seed-defaults
• POST /api/v1/internal/materializations/refresh
• POST /api/v1/internal/outbox/publish
• GET /api/v1/internal/ops/status
• POST /api/v1/internal/ingestion/load-assets
• POST /api/v1/internal/ingestion/run
• POST /api/v1/internal/ml/feature-store/rebuild
• POST /api/v1/internal/ml/train
• GET /api/v1/internal/ml/models

Quick start

1. Copy .env.example to .env.
2. Run docker compose up --build.
3. Use http://localhost:8010 as the prod API.
4. Open http://localhost:8011/ui for the sandbox banking UI.
5. The sandbox auto-seeds demo banking data, the platform auto-seeds the offer registry and source assets when enabled, and the worker handles outbox delivery, ingestion, materialization refreshes, and optional retraining.
6. Open http://localhost:8010/admin/ui for the admin console.

Docs

• docs/B2B_AGENT_EVOLUTION_PLAN.md
• docs/BANKING_DECISIONING_DELIVERY_PLAN.md
• docs/PRODUCTION_ROADMAP_SPRINTS.md