BANKGUARD
Architecture Guide
1 / 13
p.01
APIntelligence
BANKGUARD
Architecture Guide
Real-time fraud detection, case management, and graph intelligence for community and regional banks.
v3.0 · Phase 3 Complete
2026-06-27
APIntelligence · bankguard.apintelligence.ai · See also: /user-guide
p.02
System Overview

BankGuard is a modular fraud detection platform for community and regional banks. Five ML analytical engines, three operational services, and one Command Center UI — all communicating over a NATS JetStream message bus. Banks connect via four depth levels (observe, monitor, alert, intercept) and receive real-time fraud scores, case queues, explainability, and regulatory document drafts.

Bank Core System
       │
       ├──[Polling] ──────────────────────────────┐
       ├──[Webhook] ──────────────────────────────┤
       └──[Intercept] ────────────────────────────┤
                                                  ▼
                              bankguard-connector (4299)
                              ┌─────────────────────────┐
                              │  Rules Cache             │
                              │  Redis Velocity Features │
                              │  SHAP Explain            │
                              │  Step-Up Auth            │
                              └──────────┬──────────────┘
                                         │ NATS JetStream
             ┌───────────────┬───────────┼────────────────┬────────────────┐
             ▼               ▼           ▼                ▼                ▼
        fraud-score    risk-score   compliance      retention       predictive
        engine         engine       engine           engine          engine
             └───────────────┴───────────┴────────────────┴────────────────┘
                                         │
                    ┌────────────────────┼──────────────────┐
                    ▼                    ▼                  ▼
             bankguard-cases       bankguard-rules    bankguard-graph
                (4200)              (4201)              (4202)
                    │                    │                  │
                    └────────────────────┴──────────────────┘
                                         │
                                bankguard-ui (5000)
                              Command Center + Proxy
5 ML Engines
8 Services
NATS JetStream
4 Integration Depths
p.03
Service Map
Core Services
bankguard-node — ML Scoring Hub
Port: internal (NATS only) Language: Node.js Store: Redis + SQLite
Five NATS subjects: bankguard.fraud.score, bankguard.risk.customer.score, bankguard.compliance.score, bankguard.retention.score, bankguard.predictive.score. Each engine scores independently; results fan back to connector.
bankguard-connector — Bank Adapter + Scoring API
Port: 4299 Language: Node.js Store: Redis (velocity features)
Receives bank transactions via REST (POST /api/v1/score), fetches velocity features from Redis, fans out to all 5 engines in parallel, merges results, applies rules, and returns a decision within 500ms for intercept depth. Also hosts step-up auth endpoints.
bankguard-registry — Node Registry + Health
Port: 4100 Language: Node.js Store: SQLite
Tracks all BankGuard service instances via heartbeat. Provides live cluster health over WebSocket. Command Center's topology view reads from registry.
bankguard-cases — Cases, Feedback, Governance, Metering
Port: 4200 Language: Node.js Store: SQLite (cases.db)
Creates cases from NATS events when connector generates STEP_UP or DECLINE. Houses analyst workflow (assign, note, disposition), SAR/CTR draft management, SR 11-7 model governance, billing metering, and step-up challenge storage.
p.04
Service Map
Operational Services
bankguard-rules — Rules Engine
Port: 4201 Language: Node.js Store: SQLite (rules.db)
Stores declarative fraud rules in a JSON DSL. Serves active rules to connector via REST (fetched at startup + refreshed every 60s or on bankguard.rules.changed NATS event). Supports async simulation (backtest a new rule against historical data before activating). Exposes hit stats and per-rule FP rate.
bankguard-graph — Entity Graph + Ring Detection
Port: 4202 Language: Node.js Store: SQLite (graph.db)
Maintains an entity graph of accounts, customers, merchants, devices, IPs, and hashed PII nodes. Subscribes to bankguard.connector.transaction.new to upsert nodes and edges. Provides 1-hop and 2-hop neighborhood expansion. DFS ring detection finds fraud rings 3–8 hops long. Louvain community detection runs weekly.
bankguard-ui — Command Center
Port: 5000 Language: Node.js + React/Vite/Tailwind
16-route Command Center SPA. Backend proxies /api/ui/* to all downstream services. Frontend provides overview, topology, nodes, events, alerts, security, cases, rules, graph, model governance, and billing views. Includes a guided demo tour with ElevenLabs TTS (Brian voice).
bankguard-txgen — Demo Transaction Generator
Port: internal Language: Node.js Store: PostgreSQL (corebanking)
Maintains a real PostgreSQL banking schema (accounts, customers, transactions, fraud_alerts, SAR records). Generates realistic transaction patterns including fraud scenarios at configurable rates. Powers the live demo environment.
p.05
Data Flow
Scoring Path (all depths)
Bank → POST /api/v1/score → connector
  → evaluateRules(payload, cachedRules) → ruleResult
  → Redis: fetch velocity features (tx_count_1h, sum_24h, etc.)
  → NATS fan-out: [fraud, risk, compliance, retention, predictive].score
  → NATS fan-out: fraud.explain (if ?explain=true or STEP_UP/DECLINE)
  → merge results: max(mlAction, ruleAction) → finalAction
  → if finalAction ≠ APPROVE: publish bankguard.case.new
  → return { request_id, recommended_action, scores, rules_applied,
             feature_contributions, processing_time_ms }
Webhook (Alert Depth) — async
Bank → POST /bankguard-webhook → connector → 202 Accepted
  → async: process score → publish bankguard.case.new if STEP_UP/DECLINE
  → Bank polls GET /api/v1/result/:request_id for outcome
Intercept Depth — inline sync
Bank → POST /api/v1/score?depth=intercept
  → connector must respond in < 500ms
  → Bank holds the transaction pending the decision
  → Returns APPROVE or BLOCK with reason
  → Bank enforces the decision inline
p.06
Feature Inventory
Bank Integration
Legend: ✓ LIVE ⚠ PARTIAL ✗ PLANNED
FeatureServiceStatusNotes
FIS Horizon Adapterconnector✓ LIVESQL Server polling + webhook
Fiserv DNA Adapterconnector✓ LIVE
Jack Henry SilverLake Adapterconnector✓ LIVE
Generic Adapterconnector✓ LIVEConfigurable column mapping
Observe Depth (5-min poll)connector✓ LIVERead-only risk visibility
Monitor Depth (1-min poll)connector✓ LIVENear-real-time
Alert Depth (webhook, HMAC-signed)connector✓ LIVEAsync; 202 immediate
Intercept Depth (inline sync, <500ms)connector✓ LIVEHard approve/block
CDC Streaming Ingestion (Debezium/Kafka)connector✗ PLANNEDPhase 4
Oracle Bank DB Adapterconnector✓ LIVE
MSSQL Bank DB Adapterconnector✓ LIVE
Connection Setup Wizardui✓ LIVEXState multi-step; live test
Schema Discovery / Column Mappingconnector✓ LIVEINFORMATION_SCHEMA introspection
Published API SDK (JS/Python)—✗ PLANNEDPhase 4
p.07
Feature Inventory
Scoring & Detection
FeatureServiceStatusNotes
Fraud Detection Enginenode✓ LIVEbankguard.fraud.score
Customer Risk Enginenode✓ LIVE
Compliance Enginenode✓ LIVEBSA/AML alerts
Customer Retention Enginenode✓ LIVE
Predictive Analytics Enginenode✓ LIVEAnomaly score
Redis Velocity Feature Storeconnector✓ LIVEtx_count_1h, sum_24h per account
SHAP Explainability (inline)connector + node✓ LIVEfeature_contributions[]
SHAP Async Path (auto on DECLINE/STEP_UP)connector + node✓ LIVERedis by request_id
Rules Engine with JSON DSLrules✓ LIVEAND/OR; 10 operators
Rule Simulation / Backtestingrules✓ LIVEAsync vs historical
Rules Cache (in-process, zero network)connector✓ LIVE60s refresh
ML Action Override by Ruleconnector✓ LIVEoverride_ml: true
Configurable Score Thresholdsconnector✓ LIVEEnv vars
Analyst Feedback Loop → ML Retrainingcases✓ LIVEDisposition → NATS
Behavioral Biometrics (mouse)connector✓ LIVEIsolationForest, 36 features
Behavioral Biometrics (keystroke)connector✓ LIVEManhattan Distance baseline
Biometric Step-Up Suppressionconnector✓ LIVE
GNN-Based Node Fraud Probabilitygraph✗ PLANNEDPhase 4
p.08
Feature Inventory
Case Management
FeatureServiceStatusNotes
Case Queue with SLA Trackingcases✓ LIVECRITICAL 4h / HIGH 8h / MEDIUM 24h / LOW 72h
Analyst Assignmentcases✓ LIVE
Case Status Managementcases✓ LIVEOPEN → IN_REVIEW → ESCALATED → CLOSED
Case Escalationcases✓ LIVE
Case Dispositioncases✓ LIVETRUE_POSITIVE / FALSE_POSITIVE / SUSPICIOUS / INCONCLUSIVE
Analyst Notes Timelinecases✓ LIVEImmutable event log per case
SAR Auto-Draft (LLM-assisted)cases✓ LIVEClaude API + template fallback
CTR Auto-Draftcases✓ LIVE
Document Review Workflowcases✓ LIVEDRAFT → REVIEWED → FILED
Auto-Filing to FinCEN—✗ PLANNEDBy design — analyst must file manually
Feedback Events Export (JSONL)cases✓ LIVE
Precision / Recall Metricscases✓ LIVEFrom disposed cases
p.09
Feature Inventory
Graph Intelligence
FeatureServiceStatusNotes
Entity Graph (accounts, customers, merchants, devices, IPs)graph✓ LIVE
PII-Hashed Nodes (phone, email, address)graph✓ LIVESHA-256 16-char prefix
Recency-Decayed Edge Weightsgraph✓ LIVEHalf-weight at 30 days
1-hop Neighborhood Expansiongraph✓ LIVE
2-hop Neighborhood (D3 format)graph✓ LIVE
DFS Fraud Ring Detection (cycles 3–8)graph✓ LIVEConfidence scoring
Louvain Community Detectiongraph✓ LIVEWeekly; density threshold
Personalized PageRank (guilt-by-proximity)graph✓ LIVEOn TRUE_POSITIVE
D3 Force-Directed Graph Visualizationui✓ LIVECanvas-rendered
GNN Layer for Node-Level Fraud Probabilitygraph✗ PLANNEDPhase 4
p.10
Feature Inventory
Model Governance & Operations
FeatureServiceStatusNotes
SR 11-7 Model Cardscases✓ LIVEPer-engine
180-Day Validation Trackingcases✓ LIVE30-day advance alert
PSI Auto-Computationcases✓ LIVE10 bins; 0.25 retrain threshold
Step-Up OTP Challengecases + connector✓ LIVEbcrypt; 10-min TTL
Biometric Step-Up Suppressionconnector✓ LIVE
Billing / Usage Meteringcases✓ LIVEp50/p95/p99; 12-month history
Multi-Tenant Data Isolationall✓ LIVEtenant_id middleware-enforced
Node Registry + Health (WebSocket)registry✓ LIVE
Command Center UI (16 routes)ui✓ LIVEReact + Vite + Tailwind
Guided Demo Tour (ElevenLabs TTS)ui✓ LIVEBrian voice; phrase-visual sync
Health Status Pageui✓ LIVE/api/ui/health
CoreBanking PostgreSQL Demo Databasetxgen✓ LIVEReal bank schema
Synthetic Transaction Generatortxgen✓ LIVERealistic patterns + fraud scenarios
On-Premises Packaged Deployment—✗ PLANNEDNo installer; can run on-prem manually
Published API SDK—✗ PLANNEDPhase 4
p.11
Integration Modes
Four Connection Depths
Observe
Polling every 5 minutes
Risk visibility without inline decision-making. BankGuard polls the bank's database directly. Bank gets a risk dashboard; no change to transaction processing. Fastest to set up; no webhook required.
Monitor
Polling every 1 minute
Near-real-time monitoring. Same as Observe but more frequent. Suitable for institutions that want risk signals without integrating into their core processing.
Alert
Webhook, async, HMAC-signed
Bank sends transaction data to BankGuard at the moment of processing (POST). BankGuard returns 202 immediately so bank processing is unblocked. BankGuard processes asynchronously; bank polls for outcome or receives callback. Best balance of security depth and implementation effort.
Intercept
Inline sync, < 500ms
Bank holds the transaction pending BankGuard's decision. BankGuard must respond within 500ms — hard real-time requirement. Returns APPROVE or BLOCK. Bank enforces inline. Highest security depth; most rigorous integration work.
ModeLatency ImpactBank Code ChangeBest For
ObserveNoneMinimal (read-only creds)Initial evaluation, low-risk portfolios
MonitorNoneMinimal (read-only creds)Ongoing monitoring, trend detection
AlertNone (async)Moderate (outbound webhook)General fraud prevention
Intercept< 500ms inlineSignificantHigh-value / high-risk transaction blocking
p.12
Security Model
BoundaryMethodDetails
Bank → ConnectorAPI key (Bearer token)64-char hex; per-bank issued
Analyst → Command CenterJWT24h expiry
Service → ServiceNATS (internal)No external exposure
Step-Up Tokensbcrypt hashOTP never stored plaintext; 10-min TTL
Network
All services bind localhost-only; nginx terminates TLS; HSTS 63072000s; rate limiting per-IP.
Data Protection
Credentials AES-256-GCM; PII graph nodes SHA-256 hashed; tenant_id enforced at middleware; no cross-tenant data possible.
SR 11-7 Governance
Model cards per engine; PSI monitoring; 180-day validation cycle; drift alerts at 30-day warning.
Operational
All NATS subjects internal; bankguard-node has no external port; registry WebSocket internal only; zero-downtime rolling restarts.
p.13
Gaps & Planned Work

This section documents features referenced in BankGuard marketing and sales materials that are not yet implemented. Every claimed feature that is not listed as ✓ LIVE on the preceding pages is documented here.

FeaturePriorityPhaseNotes
CDC Streaming Ingestion (Debezium/Kafka)MEDIUMPhase 4Sub-second latency for high-volume institutions; no bank-side code required
Published API SDK (JS/Python)LOWPhase 4Programmatic access for institutional developers; not required for standard integration
GNN-Based Node Fraud ProbabilityLOWPhase 4Requires Python ML sidecar or NATS bridge; Louvain (✓ live) covers community-level detection
Auto-Filing to FinCEN—By designAnalyst review is required before filing. BankGuard drafts SARs and CTRs; filing is always a human action.
FinCEN Note
BankGuard intentionally does not auto-file regulatory documents. BSA regulations require human review before SAR submission. Auto-filing would be a compliance violation. The ✗ PLANNED marker reflects that no auto-filing is planned.
User Guide → bankguard.apintelligence.ai
p.15
Topology: Docker

The Docker delivery model packages BankGuard as two separately deployable compose stacks. The server stack runs all scoring services in an isolated internal network with no direct internet access. The Connector is the only service that bridges to the external network on port 4299 — it is the single entry point for the bank's core system. The Command Center (UI) deploys via a separate compose file and can run on the same host or on the bank's own infrastructure.

DOCKER DELIVERY · docker-compose.server.yml + docker-compose.client.yml Bank Core or Browser HTTPS NGINX :443 /api/demo/score→:4299 /*→:5000 /* → :5000 docker-compose.server.yml bankguard-external · port :4299 exposed to reverse proxy bankguard-connector :4299 · REST scoring API · rules cache bankguard-internal · isolated network · no direct internet access NATS :4222 · account-isolated · BG_ENGINE · BG_CONNECTOR · BG_REGISTRY · BG_GRAPH bankguard-node NATS only · no HTTP fraud · risk · compliance retention · predictive bankguard-registry :4100 · SQLite node lifecycle cluster health state bankguard-cases :4200 · SQLite cases · SAR/CTR feedback · billing bankguard-rules :4201 · SQLite rules DSL · simulation cache push via NATS bankguard-graph :4202 · SQLite entity graph fraud ring detection storage: SQLite ×4 · Redis :6379 (feature store) · ONNX model files docker-compose.client.yml (separate deployment) bankguard-ui :5000 · Command Center React SPA · WebSocket hub /api/ui/* proxy · analyst workflow model governance · billing UI bankguard-web (static) marketing · demo · architecture · user-guide BANK INTEGRATION Bank’s core system calls: POST /api/v1/score Authorization: Bearer <key> Connector is the only service with an external-facing port. Command Center proxies to server services via HTTP (cases, rules, graph, registry). Both stacks can run on the same host or on separate servers. bankguard-node has no HTTP port — it is a pure NATS subscriber. The Connector fans scored requests to all 5 engines simultaneously over NATS subjects scoped per tenant.
User Guide → bankguard.apintelligence.ai
p.16
Topology: PM2 · Bare Metal

The PM2 deployment model runs all services as native Node.js processes on a single server, managed by PM2. Every service binds to 127.0.0.1 (loopback) — nothing is directly reachable from the internet. Nginx terminates SSL on port 443 and proxies inbound requests via loopback to the Connector (:4299) or the UI (:5000). This is the current live deployment model on the AnswerPoint VPS.

PM2 / BARE-METAL DEPLOYMENT · current live on VPS 104.207.95.68 VPS 104.207.95.68 · all services bind to 127.0.0.1 INTERNET Bank Core → HTTPS → bankguard.apintelligence.ai (Nginx :443) /api/demo/score → 127.0.0.1:4299 (auth injected server-side) · /* → 127.0.0.1:5000 (WebSocket upgrade) NGINX :443 · bankguard.apintelligence.ai /api/demo/score → 127.0.0.1:4299 (auth injected) /* → 127.0.0.1:5000 (WebSocket upgrade) PM2 PROCESSES NATS 127.0.0.1:4222 · account-isolated: BG_ENGINE · BG_CONNECTOR · BG_REGISTRY · BG_UI · BG_GRAPH bankguard-connector 127.0.0.1:4299 REST API · rules cache · metering Redis feature store bankguard-node NATS only · no HTTP port fraud · risk · compliance retention · predictive bankguard-registry 127.0.0.1:4003 node lifecycle · SQLite cluster health · heartbeat bankguard-cases 127.0.0.1:4200 case queue · SAR/CTR feedback loop · billing bankguard-rules 127.0.0.1:4201 rules DSL · simulation cache push → connector bankguard-graph 127.0.0.1:4202 entity graph · SQLite DFS ring detection bankguard-ui 127.0.0.1:5000 Command Center · WebSocket /api/ui/* proxy bankguard-web static files (nginx serves) marketing · demo · architecture user-guide.html bankguard-check.js System Integrity Checker node bankguard-check.js run after deploy or to troubleshoot STORAGE SQLite ×4 (registry.db · cases.db · rules.db · graph.db) Redis :6379 (feature store · 127.0.0.1) · ONNX model files (/var/www/html/bankguard/bankguard-node/models/)
User Guide → bankguard.apintelligence.ai
p.14
Deployment Guide

BankGuard runs as a cluster of Node.js microservices managed by PM2. No Docker is required for the managed-hosted deployment model; each service starts directly on the server and communicates over an internal NATS message bus.

PrerequisitesMinimumNotes
Node.jsv18.x LTSRequired by all services
PM2v5.xnpm install -g pm2
NATS Serverv2.10+Account-based isolation; config at /etc/nats/nats.conf
Nginx1.20+Reverse proxy for BankGuard UI and connector API
Disk20 GBAllows for model files and log rotation

Installation Steps

  1. Copy service directories to /var/www/html/bankguard/.
  2. Run npm install inside each service directory.
  3. Copy .env.example to .env for each service and populate all values.
  4. Start NATS: nats-server -c /etc/nats/nats.conf
  5. Start all services: pm2 start ecosystem.config.js
  6. Save PM2 state: pm2 save && pm2 startup
  7. Configure Nginx to proxy /api/v1/ to :4299 and the UI to :5000.
  8. Run the System Integrity Checker to confirm all engines are operational.
Post-Deployment Verification
After all services are running, execute the System Integrity Checker to confirm that every engine is reachable, NATS connectivity is established, environment variables are fully populated, and the connector can accept a live transaction:

node /var/www/html/bankguard/bankguard-check.js All five sections should report PASS before the system accepts production traffic. See the User Guide → System Integrity Check for output interpretation and common fixes.
User Guide → bankguard.apintelligence.ai
Cover

Contents