Sentinel Documentation

Catch It. Explain It. Report It — In Real Time.

Complete installation, integration, and usage guide for bank IT and compliance teams

Overview

Sentinel AML is a CBN-compliant anti-money laundering platform purpose-built for Nigerian banks and fintechs. It ingests transactions in real time via Kafka, evaluates them against six CBN detection rules and an ML anomaly model (Isolation Forest with SHAP explainability), generates instant alerts with full reasoning explanations, supports maker-checker case management workflows, and exports NFIU goAML STR XML reports. All screening is performed internally — no personally identifiable information ever leaves your server, ensuring full NDPA compliance.

System Requirements

Tier vCPU RAM Storage Use Case
Minimum 4 8 GB 100 GB SSD Development, evaluation, small MFBs
Recommended 8 16 GB 250 GB SSD Mid-tier banks, up to 500K txn/day
Production 16+ 32 GB+ 500 GB+ NVMe Tier-1 banks, high-volume processing

Architecture Overview

The platform follows an event-driven architecture with clear separation of concerns:

CBS (Core Banking) --> Kafka --> Rule Engine --> Alerts --> Dashboard | ML Engine (Isolation Forest + SHAP) | XAI Reasoning Card | Case Management (Maker-Checker) | NFIU goAML STR XML Export
Component Port Technology
Backend API 8000 FastAPI, SQLAlchemy (async), aiokafka
Frontend Dashboard 3000 Next.js 15, React 18, Zustand, Radix UI
PostgreSQL / TimescaleDB 5432 Append-only audit, time-series transactions
Redis 6379 Alert cache, screening cache, sessions
Kafka (KRaft mode) 9092 Transaction ingestion (internal only)

Tutorial — Getting Started with Sentinel

This step-by-step tutorial walks compliance officers and bank IT staff through the first-time experience after installation. By the end, you will have ingested test transactions, reviewed an alert, opened a case, and exported an STR report.

1. First Login

After installation, open your Sentinel URL in a browser and sign in with the admin credentials created during setup.

  1. Navigate to your Sentinel URL — e.g., https://sentinel.yourbank.ng. You will see the login screen.
  2. Enter your email and password — Use the super-admin account created during the setup wizard.
  3. Complete MFA enrolment — Scan the QR code with your authenticator app (Google Authenticator, Microsoft Authenticator, or similar).
  4. Arrive at the Dashboard — You will see the real-time monitoring overview with empty charts (no data yet).

2. Understanding the Dashboard

The dashboard is your command centre. Here is what each section shows:

SectionPurpose
Alert FeedLive stream of triggered alerts, colour-coded by severity (critical, high, medium, low)
Transaction VolumeReal-time chart of ingested transactions per hour/day
Rule BreakdownWhich CBN rules are firing most frequently
ML Anomaly ScoreDistribution of anomaly scores from the Isolation Forest model
Case PipelineCases by stage: open, under review, escalated, closed

3. Ingesting Test Transactions

Use the built-in MockCBS to generate realistic test data and see the system in action:

# Start MockCBS service docker compose --profile testing up -d mockcbs # Generate 200 transactions over 2 minutes (includes suspicious patterns) curl -X POST http://localhost:9500/generate \ -H "Content-Type: application/json" \ -d '{"count": 200, "duration_seconds": 120, "include_suspicious": true}'

Within seconds, you should see transactions appearing in the dashboard and alerts beginning to fire.

4. Reviewing an Alert

  1. Click an alert in the feed — The alert detail panel opens showing the triggered rule, risk score, and affected entity.
  2. Read the XAI explanation — Sentinel provides a plain-language reasoning card explaining WHY the alert fired, powered by SHAP feature attribution.
  3. Check entity history — The entity profile shows transaction history, prior alerts, and screening results in one view.
  4. Take action — Dismiss (with reason), escalate to a case, or mark for further monitoring.

5. Opening and Managing a Case

When an alert warrants investigation, escalate it to a case:

  1. Click "Escalate to Case" — The case is created and assigned to you (or routed by your assignment rules).
  2. Add investigation notes — Document findings, attach supporting evidence, tag related transactions.
  3. Submit for approval (Maker) — Once your analysis is complete, submit the case for checker review.
  4. Checker approves or returns — A second authorised user reviews and either approves the resolution or sends it back with comments.
Maker-Checker: All case state transitions require two-user approval in compliance with CBN internal control requirements. A single user cannot both open and close a case.

6. Generating an STR Report

For cases that must be reported to the NFIU:

  1. Open the approved case — Navigate to Cases → Closed/Reported.
  2. Click "Generate STR" — Sentinel pre-fills the goAML XML template with entity data, transaction details, and your investigation narrative.
  3. Review and download — Verify the XML contents, then download for submission via the NFIU goAML portal.

7. Managing Users and Roles

Navigate to Settings → Users to invite team members. Sentinel supports four roles:

RolePermissions
ViewerRead-only access to dashboard, alerts, and cases
AnalystReview alerts, manage cases, run screening (Maker)
Compliance OfficerApprove cases, generate STRs, manage watchlists (Checker)
AdminFull access including user management, integrations, and system configuration

8. Screening Entities

Sentinel performs internal screening against local watchlists (no PII leaves your server):

  1. Navigate to Entities — Find the customer you want to screen.
  2. Click "Screen" — Sentinel checks against PEP lists, sanctions, and adverse media from your local index.
  3. Review matches — Results show match confidence, source list, and the matched record for manual confirmation.

9. Setting Up CBS Integration (Production)

When you are ready to connect your live Core Banking System, follow the CBS Integration section below. The key steps are: register your CBS in Settings → Integrations, obtain your API key, and configure your CBS to push transactions to the ingest endpoint.

Next steps: Once live transactions are flowing, Sentinel's ML model will begin learning your institution's baseline patterns within 7 days. Alert accuracy improves significantly after this initial learning period.

Docker Compose Install

The fastest way to deploy Sentinel. A single command downloads the release tarball, runs pre-flight checks, and launches the interactive setup wizard.

Quick Install

curl -sL https://sentinel.sjultra.ng/install.sh | bash
Prerequisites: Docker Engine 24+, Docker Compose v2, 8 GB free RAM minimum, and a domain with DNS pointing to your server. The installer will verify all prerequisites before proceeding.

Setup Wizard Steps

The interactive wizard guides you through nine configuration stages:

  1. Prerequisites Check — Verifies Docker, Compose, available memory, disk space, and network connectivity.
  2. Organization Details — Bank name, CBN licence number, and institution category (DMB, MFB, OFI).
  3. Security Keys — Generates JWT signing keys, API secrets, and inter-service tokens. Stored in .env with restricted permissions.
  4. Public URL — Your Sentinel domain (e.g., sentinel.yourbank.ng). Used for SSL certificate provisioning and webhook callbacks.
  5. Database Configuration — PostgreSQL credentials and data directory. TimescaleDB extension is enabled automatically.
  6. Email / SMTP — Alert notification delivery. Supports standard SMTP, Amazon SES, and SendGrid relay.
  7. Backup Schedule — Automated daily database dumps. Configure retention period and optional S3-compatible offsite storage.
  8. KYC Provider — Select and configure your identity verification provider (YouVerify, Smile ID, Prembly, or VerifyMe).
  9. Admin Account — Creates the initial super-admin user with MFA enrollment prompt.

Post-Install Verification

After installation completes, verify all services are healthy:

# Check service status docker compose ps # Verify API health curl -s https://your-sentinel.ng/api/health | jq . # Expected response: # { # "status": "healthy", # "services": { # "database": "connected", # "redis": "connected", # "kafka": "connected", # "ml_engine": "loaded" # } # } # View recent logs docker compose logs --tail=50 backend
Updating an Existing Installation

Sentinel supports zero-downtime rolling updates. The update process backs up your current configuration before applying changes.

# Pull latest release and apply migrations curl -sL https://sentinel.sjultra.ng/install.sh | bash -s -- --update # Or manually: cd /opt/sentinel docker compose pull docker compose up -d --remove-orphans docker compose exec backend alembic upgrade head

The --update flag preserves your .env, SSL certificates, and database. Only container images and static assets are replaced.

Backup and Restore

Manual Backup

# Database dump (includes TimescaleDB hypertables) docker compose exec postgres pg_dump -U sentinel -Fc sentinel_db \ > backup_$(date +%Y%m%d_%H%M%S).dump # Full configuration backup tar czf sentinel-config-$(date +%Y%m%d).tar.gz \ .env docker-compose.yml ssl/ config/

Restore from Backup

# Stop services docker compose down # Restore database docker compose up -d postgres docker compose exec -T postgres pg_restore -U sentinel -d sentinel_db \ --clean --if-exists < backup_20260715_120000.dump # Restart all services docker compose up -d

Kubernetes / Helm

For production deployments requiring high availability, auto-scaling, and managed infrastructure, deploy Sentinel using our official Helm chart.

Prerequisites

  • kubectl configured with cluster access
  • Helm 3.12+
  • Kubernetes 1.26+ cluster
  • Ingress controller (nginx-ingress or ALB controller)
  • Persistent volume provisioner (for database and Kafka storage)

Quick Start

# Add the Sentinel Helm repository helm repo add sentinel https://charts.sentinel.sjultra.ng helm repo update # Install with custom values helm install sentinel sentinel/sentinel \ --namespace sentinel \ --create-namespace \ -f values.yaml

Minimal values.yaml

global: domain: sentinel.yourbank.ng backend: image: tag: "1.4.0" replicas: 2 frontend: replicas: 2 secrets: jwtSecret: "your-256-bit-secret" databaseUrl: "postgresql+asyncpg://sentinel:password@postgres:5432/sentinel_db" redisUrl: "redis://redis:6379/0" ingress: enabled: true className: nginx tls: - secretName: sentinel-tls hosts: - sentinel.yourbank.ng postgresql: enabled: true persistence: size: 100Gi redis: enabled: true kafka: enabled: true persistence: size: 50Gi
Cloud-Specific Notes

AWS EKS

  • Use aws-load-balancer-controller for ingress with ACM certificates
  • RDS PostgreSQL with TimescaleDB extension recommended for managed database
  • Amazon MSK can replace the bundled Kafka for managed streaming
  • ElastiCache for Redis in production workloads

Google GKE

  • Cloud SQL for PostgreSQL with TimescaleDB extension
  • Memorystore for Redis
  • GKE Ingress with managed certificates

Azure AKS

  • Azure Database for PostgreSQL (Flexible Server)
  • Azure Cache for Redis
  • Application Gateway Ingress Controller for TLS termination
Scaling Guidance
Transaction Volume Backend Replicas Kafka Partitions DB Pool Size
Up to 100K txn/day 2 3 20
100K - 1M txn/day 4 6 50
1M - 10M txn/day 8 12 100
10M+ txn/day 12+ 24+ 200+

Horizontal Pod Autoscaler (HPA) is pre-configured in the Helm chart. Default scaling triggers at 70% CPU utilisation or 80% memory utilisation. Kafka consumer lag is also available as a custom metric for scaling.

# Check current scaling status kubectl get hpa -n sentinel # Manually scale backend kubectl scale deployment sentinel-backend --replicas=6 -n sentinel

CBS Integration

Sentinel ingests transactions from your Core Banking System (CBS) via a simple REST endpoint. The integration takes four steps and can be tested with our MockCBS utility before connecting to production.

Integration Steps

  1. Register Integration — In the Sentinel dashboard, navigate to Settings → Integrations → Add CBS Connection. Enter your CBS identifier and IP whitelist.
  2. Obtain API Key — After registration, Sentinel generates a dedicated API key with transaction-push scope. Store this securely in your CBS configuration.
  3. Configure CBS — Point your CBS transaction webhook to POST https://your-sentinel.ng/api/v1/ingest/transactions with the API key in the Authorization header.
  4. Test Connection — Use the "Test Connection" button in the dashboard, or submit a test transaction via the API. Verify it appears in the transaction log within seconds.

Transaction Schema

Push transactions to POST /api/v1/ingest/transactions with the following JSON body:

{ "entity_id": "ENT-001-2024-00482", "timestamp": "2026-07-20T14:32:00Z", "amount": 4850000.00, "currency": "NGN", "channel": "branch", "direction": "credit", "counterparty_token": "CP-TOKEN-8a3f2e", "counterparty_name": "Adewale Trading Ltd", "reference": "FT26201ABCDE", "transaction_type": "transfer" }
Field Type Required Description
entity_id string Yes Unique customer/entity identifier in your CBS
timestamp ISO 8601 Yes Transaction timestamp in UTC
amount number Yes Transaction amount (positive value)
currency string Yes ISO 4217 currency code (e.g., NGN, USD)
channel string Yes Transaction channel: branch, mobile, internet, atm, pos
direction string Yes credit or debit
counterparty_token string No Tokenized counterparty reference (preserves privacy)
counterparty_name string No Counterparty display name
reference string Yes Unique transaction reference from CBS
transaction_type string Yes transfer, deposit, withdrawal, payment, forex
MockCBS for Testing

Sentinel ships with a MockCBS service for integration testing. It simulates realistic transaction patterns including structuring attempts, dormant activations, and rapid fund movements.

# Start MockCBS (available on port 9500) docker compose --profile testing up mockcbs # Generate 1000 test transactions over 5 minutes curl -X POST http://localhost:9500/generate \ -H "Content-Type: application/json" \ -d '{"count": 1000, "duration_seconds": 300, "include_suspicious": true}' # Check MockCBS status curl http://localhost:9500/status

MockCBS pushes transactions directly to the Sentinel ingest endpoint, so alerts will appear in your dashboard in real time during testing.

KYC Provider Setup

Sentinel integrates with major Nigerian identity verification providers for automated onboarding (KYC/KYB). Configure your preferred provider to enable real-time identity checks and risk scoring during entity onboarding.

Supported Providers

Provider KYC KYB Provider Code
YouVerify Yes Yes youverify
Smile ID Yes Yes smileid
Prembly (Identitypass) Yes Yes prembly
VerifyMe Yes No verifyme

Webhook Configuration

After completing setup in your provider's dashboard, register the following webhook URL to receive verification results:

https://your-sentinel.ng/api/v1/onboarding/webhook/{provider} # Examples: # https://sentinel.yourbank.ng/api/v1/onboarding/webhook/youverify # https://sentinel.yourbank.ng/api/v1/onboarding/webhook/smileid # https://sentinel.yourbank.ng/api/v1/onboarding/webhook/prembly # https://sentinel.yourbank.ng/api/v1/onboarding/webhook/verifyme

Required Headers

All webhook requests from providers must include these headers for verification:

Header Description Example
X-Bank-Id Your bank's unique identifier in Sentinel bank_001
X-Signature HMAC-SHA256 signature of the request body sha256=a1b2c3d4e5...
Security Note: Sentinel validates every incoming webhook by recomputing the HMAC-SHA256 signature using your provider's shared secret. Requests with invalid or missing signatures are rejected and logged to the audit trail.
Testing KYC Integration

Use the Sentinel API to submit a test onboarding request and verify the end-to-end flow:

# Submit a test KYC verification request curl -X POST https://your-sentinel.ng/api/v1/onboarding \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "entity_type": "individual", "provider": "youverify", "document_type": "nin", "document_number": "12345678901", "first_name": "Test", "last_name": "User", "date_of_birth": "1990-01-15" }' # Check verification status curl https://your-sentinel.ng/api/v1/onboarding/status/REQ-ID-HERE \ -H "Authorization: Bearer YOUR_JWT_TOKEN"

Most providers offer sandbox/test modes. Configure sandbox API keys in your .env for testing before switching to production credentials.

API Reference

Core endpoints for programmatic integration. All endpoints require authentication via Bearer JWT token unless otherwise noted.

Authentication

# Obtain a JWT token curl -X POST https://your-sentinel.ng/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email": "admin@yourbank.ng", "password": "your-password"}' # Use token in subsequent requests curl https://your-sentinel.ng/api/v1/alerts \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Endpoints

Method Endpoint Description Auth
POST /api/v1/ingest/transactions Push transactions from CBS. Triggers rule engine evaluation and ML scoring. API Key
POST /api/v1/screening/entity/{id} Screen an entity against internal watchlists (PEP, sanctions, adverse media). Bearer JWT
POST /api/v1/onboarding Submit KYC/KYB verification request via configured provider. Bearer JWT
GET /api/v1/alerts List alerts with filtering by severity, rule, status, and date range. Bearer JWT
GET /api/v1/cases List cases with maker-checker status, assigned analyst, and resolution. Bearer JWT
GET /api/v1/health System health check. Returns status of all connected services. None
Response Format

All API responses use a standard envelope format:

{ "success": true, "data": [ ... ], "meta": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } } // Error response: { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "entity_id is required", "details": { ... } } }
Rate Limits
Endpoint Category Limit Window
Transaction Ingest 10,000 requests Per minute
Screening 500 requests Per minute
General API 1,000 requests Per minute
Authentication 20 requests Per minute

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in all responses.

Support

SJULTRA provides dedicated support for all Sentinel deployments. Our team includes compliance engineers familiar with CBN regulations and technical staff experienced with Nigerian banking infrastructure.

Channel Contact Response Time
Partnerships / General partners@sjultra.ng Within 24 hours
Technical Support support@sjultra.ng Within 4 hours (business days)
Sales / Licensing sales@sjultra.ng Within 24 hours
Enterprise SLA: Production deployments include 24/7 critical incident support with a 30-minute response commitment. Contact sales@sjultra.ng for enterprise tier details.

Useful Links