FinSight

FinSight is a financial crime analytics platform focused on anti-money laundering (AML) detection, alert triage, network analysis, and evidence management. The MVP demonstrates an end-to-end workflow: ingesting transaction and KYC data, surfacing alerts, triaging entities, exploring networks, managing cases, and preparing SAR-ready evidence.

Features

• Multi-tenant analyst workspace built with React, Vite, TailwindCSS, React Flow, and Recharts, supporting institution switching and persisted data masking preferences.
• FastAPI backend with PostgreSQL for entities, alerts, cases, detection rules, and Celery for asynchronous jobs.
• Role-based access control for regulator admins, FIU analysts, bank analysts, and bank managers with tenant-aware API filtering.
• Rule engine running AML heuristics (structuring, rapid movement, high-risk corridors, round tripping) across 50k synthetic transactions.
• Entity 360 and graph explorer views enriched with behavioural analytics, watchlist matches, regulatory notes, and multi-hop network insights.
• AI intelligence layer automatically enriches alerts with narratives, explanations, risk factors, and recommended next actions, while prioritising queues with configurable severity weights.
• Admin transparency controls automatically expose true entity identifiers, account numbers, and transaction references for regulator logins while preserving masking for analysts.
• Deterministic entity references (e.g., ENT-2039) exposed via the API for auditors to jump directly into Desert Transfers LLC and other seeded typologies.
• Data intelligence workspace visualises connected sources, lineage, feature engineering, and profiling commentary so reviewers can trace how datasets are unified for AML analytics.
• Supervisory dashboard for regulators to monitor institution KPIs, alert trends, corridor flows, and drill into individual banks.
• Evidence management with PDF report generation per alert and audit logging.
• Mock data ingestion (transactions, KYC, watchlist, links) and CSV batch upload endpoint.
• Curated AML scenarios seeded across high-, medium-, and low-severity cases including Desert Transfers LLC layering, remittance structuring bursts, and benign retail activity for contrast.
• MinIO storage stub for evidence and document storage in containerised deployments.
• JWT authentication with seeded demo users for regulator, bank analyst, bank manager, and FIU analyst personas.
• Testing suite (Pytest, Vitest) and GitHub Actions-ready pipeline stubs.
• Graph explorer with directional flow intelligence highlights round-tripping, high-intensity corridors, AI annotations, and now supports investigator-grade focus mode with hop-based expansion, entity search, and adaptive layouts.

Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js 20+ and Python 3.11 (for local development outside containers)

One-time setup

cp .env.example .env

Run with Docker Compose

docker compose up -d --build

Once all services are healthy:

• Frontend: http://localhost:3000
• API docs: http://localhost:8000/docs
• MinIO console: http://localhost:9001 (credentials from .env)
• Database migrations: the backend container now runs alembic upgrade head only when an alembic.ini file is present. If you need schema migrations, drop your Alembic configuration into the backend image (or mount it) before start-up.

Windows users: Git may check out shell scripts with Windows line endings, causing env: 'bash\r': No such file or directory during container startup. The backend image now normalises .sh files to Unix line endings during the build, but you can also run git config core.autocrlf false (or *.sh text eol=lf in .gitattributes) locally to avoid the issue altogether.

Demo credentials:

• Regulator admin: admin@finsight.gov / admin123
• Gulf Capital analyst: analyst@gulfcapitalbank.com / analyst123
• Desert Bank manager: manager@desertbank.com / manager123
• FIU analyst: central@gccfiu.gov / central123

Local development (optional)

make bootstrap  # install backend + frontend deps
make backend    # run FastAPI with auto-reload (requires DATABASE_URL env)
make frontend   # run Vite dev server

Tests

# Backend API + integration tests (runs against an ephemeral SQLite database)
pytest backend/app/tests

# Frontend unit tests
npm --prefix frontend test -- --run

# Graph explorer regression tests (focus mode, layout helpers, edge styling)
npm --prefix frontend test -- --run GraphExplorer.integration.test.tsx graph.utils.test.ts

# Targeted entity reference smoke test
pytest backend/app/tests/test_entities.py -k reference

# Regression coverage for entities lacking reference IDs
pytest backend/app/tests/test_entity_schema.py -k null_external_id

# Type-check and build the analyst console
npm --prefix frontend run build

The Playwright spec (frontend/e2e/analyst.spec.ts) provides an end-to-end smoke scenario. Run npm --prefix frontend run test:ui once the application is running locally.

Frontend tests now include coverage for the reusable masking utilities to ensure personally identifiable information remains obfuscated when analysts enable that preference. Additional integration tests exercise the Entity 360 experience, confirming risk metrics render with fixed precision and gracefully degrade when upstream APIs omit optional numeric fields. Graph explorer regression tests guard the directional flow labels, ensure round-trip styling stays animated, validate the hop-based focus subgraph helpers, and lock in the TypeScript-safe label styling required for successful Docker builds.

The backend test suite now includes coverage for the dashboard KPIs service and API to ensure the operational metrics rendered in the UI remain consistent with the database counts.

Architecture

finsight/
├── backend/              # FastAPI application, Celery worker, tests, data loaders
├── frontend/             # React + Vite analyst console
├── docker-compose.yml    # Docker stack (PostgreSQL, Redis, MinIO, API, frontend, worker)
├── Makefile              # Helper commands
├── .env.example          # Environment variables template
└── tests/                # Reserved for cross-cutting integration tests

Backend highlights

• SQLAlchemy ORM models for entities, accounts, transactions, alerts, cases, notes, attachments, and rules.
• JWT security utilities with bcrypt password hashing and OAuth2 login endpoint.
• Rule engine service encapsulating AML detection heuristics.
• AI intelligence service generates severity-aware prioritisation, summaries, and recommended actions for alerts, entities, and cases.
• Upload API that ingests CSV transaction batches and triggers rule evaluation.
• Dashboard KPIs summarising alert and case health.
• Data intelligence API exposes source metadata, lineage, feature mappings, and profiling commentary for transparency.
• Celery worker for recalculating alerts asynchronously.
• Startup routine (lifespan) seeds schema, default user, rules, and mock data.
• Automatic schema guard patches legacy databases missing the users.role and users.organization_id columns before seeding demo accounts, preventing startup failures when upgrading from older snapshots.
• Schema synchronisation now audits every ORM table on startup, creating any missing columns (including tenant scoping fields) and secondary indexes so upgrades from previous releases do not fail when new attributes are added.

Frontend highlights

• Zustand-driven authentication store storing JWT tokens and analyst-controlled PII masking preferences.
• Axios API client with automatic bearer token injection.
• React Router guarded routes with Layout shell and responsive navigation.
• Dashboard presenting AI-enriched KPIs, severity trend chart, narrative insights, and top alerts.
• Alert inbox with search, AI summaries, severity badges, and prioritised ordering.
• Entity 360, Graph Explorer (React Flow), Case Workspace (timeline + notes + PDF export), Data Intelligence transparency view, and Rule Editor.
• TailwindCSS design system echoing Presight.ai aesthetic: dark surfaces, blue gradients, soft shadows.

Network Explorer quick guide

• Entity-centric focus: Use the “Focus on an entity” search in the top-left overlay to isolate any customer, account, merchant, or counterparty. The graph automatically declutters around the selection.
• Hop-based exploration: Choose 1–3 hops to progressively expand the visible network outward while retaining clear spacing and directional cues.
• Reset controls: Toggle focus mode or reset the view at any time; zoom and fit actions remain available through the floating control set.
• Dynamic context: The focus summary panel surfaces connected node counts, flow totals, and relative centrality for the active entity, while the flow detail panel updates on hover with masking-aware metadata.

CI/CD

A GitHub Actions workflow (to be configured) can run the following tasks:

1. Install backend + frontend dependencies
2. Run pytest and npm test
3. Build Docker images and optionally push to a registry
4. docker compose up smoke test

Mock Data

Mock data is generated in backend/data/2024-aml-demo/ on first boot:

• entities.csv – 2,000 customers/entities distributed across four banks with risk metrics.
• Includes Desert Transfers LLC (ENT-2039) so regulators can verify the circular Dubai ↔ Singapore typology via the reference lookup endpoint.
• transactions.csv – 50,000 transactions featuring the Dubai ↔ Singapore circular flow typology.
• watchlist.csv – 200 sanctioned or sensitive names used for fuzzy/partial matches.
• links.json – relationship graph (accounts, devices, counterparties) used by the graph explorer.

app/demo_seed.py executes automatically during container start (and can be re-run manually) to create tenants, load the dataset, generate AML alerts, inject regulatory notes, and produce audit trail entries.

Environment Variables

Key variables (see .env.example):

• DATABASE_URL or individual POSTGRES_* variables for the database
• REDIS_URL for Celery broker
• MINIO_* for evidence storage
• DEFAULT_USER_* for seeding the analyst account
• VITE_API_URL to configure the frontend API base URL

License

This project is released under the Apache 2.0 License. See LICENSE for details.