AML/DD MVP

SancTrust Slides

Internal AML and sanctions due diligence workspace.

This monorepo contains:

• a Next.js analyst UI
• a local worker/API process that runs case workflow ticks
• shared contracts, workflow logic, connectors, and Prisma-backed persistence

The repo is set up so a new developer can clone it, set environment variables, and run the app locally without needing extra repo-specific setup steps.

Current Sanctions Data Sources

The current MVP policy is US-centric. The active screening scope in policy.v2 is:

• OFAC Specially Designated Nationals (SDN)
• OFAC Consolidated Sanctions List (CONS)
• US BIS Denied Persons List

Active by default

Source	Status	Update cadence	Official URL
OFAC Specially Designated Nationals (SDN)	Active in policy.v2	Daily	https://ofac.treasury.gov/sanctions-list-service
OFAC Consolidated Sanctions List (CONS)	Active in policy.v2	Daily	https://ofac.treasury.gov/sanctions-list-service
US BIS Denied Persons List	Active in policy.v2	Weekly	https://www.bis.doc.gov/index.php/policy-guidance/lists-of-parties-of-concern/denied-persons-list

The source registry also contains mapped but currently dormant sources that are not part of the default active workflow:

• OpenSanctions Combined Sanctions
• OpenSanctions Default Collection
• US Consolidated Screening List (CSL)

Mapped but dormant

Source	Status	Update cadence	Official URL
OpenSanctions Combined Sanctions	Mapped, not active by default	Daily	https://www.opensanctions.org/datasets/sanctions/
OpenSanctions Default Collection	Mapped, not active by default	Daily	https://www.opensanctions.org/datasets/default/
US Consolidated Screening List (CSL)	Mapped, not active by default	Daily	https://www.trade.gov/consolidated-screening-list

Important note:

• the canonical source registry lives in packages/connectors/src/sanctions/registry-data.json
• the active default policy lives in packages/policy/src/config/ofac-demo-policy.v2.json
• broader UK / EU / UN coverage is discussed in the architecture docs, but it is not the default active screening scope in the current MVP path

What You Need

• Node.js 24.x or newer
• pnpm 10.x
• access to a PostgreSQL server
• a .env file based on .env.example

Optional keys unlock extra integrations, but they are not required to boot the app:

• Tavily for OSINT enrichment
• Gemini / Google Generative AI for deep investigation
• Redis memory service for long-term memory features
• Companies House / OpenCorporates keys for richer registry integrations

Quick Start

git clone <your-fork-or-repo-url>
cd DD
cp .env.example .env
pnpm install
pnpm dev

Then open:

• web app: http://127.0.0.1:3010
• worker API: http://127.0.0.1:4010

pnpm dev now does the local bootstrap for you:

1. generates the Prisma client
2. creates the target database if it does not exist
3. applies the Prisma schema
4. starts the web app and worker together

Environment Variables

Copy .env.example to .env and fill in what you need.

Required

Variable	Required	Purpose
DATABASE_URL	Yes	PostgreSQL connection string used by the web app, worker, and schema bootstrap.

Example:

DATABASE_URL=postgresql://postgres@127.0.0.1:5432/aml_dd?schema=public

Notes:

• The database name must be present in the URL.
• On local development, pnpm dev will create that database automatically if your Postgres user has permission.
• The bootstrap step also attempts to enable the pg_trgm extension because matching depends on it.

Optional

Variable	Purpose
NEXT_PUBLIC_APP_NAME	UI label for the app shell.
WORKER_API_ORIGIN	Override the worker API origin used by the web app. Leave blank for local development.
TAVILY_API_KEY	Enables Tavily-backed OSINT search/extract flows.
TAVILY_PROJECT	Optional Tavily project label.
TAVILY_RESEARCH_POLL_ATTEMPTS	Optional Tavily polling override.
TAVILY_RESEARCH_POLL_DELAY_MS	Optional Tavily polling delay override.
GEMINI_API_KEY	Enables Google/Gemini-backed deep investigation.
GOOGLE_GENERATIVE_AI_API_KEY	Alternate Google key env name supported by the runtime.
AML_DD_AGENT_MODE	Agent runtime mode. auto is the recommended local default.
AML_DD_AGENT_MODEL	Optional override for the fast model.
AML_DD_AGENT_REASONING_MODEL	Optional override for the reasoning model.
REDIS_MEMORY_BASE_URL	Enables Redis-backed memory endpoints.
REDIS_MEMORY_BEARER_TOKEN	Optional bearer token for the Redis memory service.
COMPANIES_HOUSE_API_KEY	Enables richer Companies House registry lookups.
OPENCORPORATES_API_KEY	Enables OpenCorporates-backed registry lookups.

Local Development Flow

One-command startup

pnpm dev

That command starts:

• @aml-dd/web on port 3010
• @aml-dd/worker on port 4010

If you only want the database bootstrap

pnpm bootstrap

or

pnpm db:prepare

If you want to run each app separately

pnpm dev:web
pnpm dev:worker

Repository Layout

apps/
  web/       Next.js analyst UI
  worker/    worker loop + local HTTP API

packages/
  agents/      agent runtime helpers
  connectors/  external data integrations
  contracts/   shared schemas and types
  db/          Prisma schema, repositories, and DB bootstrap
  matching/    sanctions matching logic
  memory/      Redis memory client
  policy/      source-activation and risk-policy config
  workflow/    workflow phases and transitions

python/
  ingestion/   ingestion utilities for fixtures and source sync

Common Commands

pnpm dev
pnpm bootstrap
pnpm db:prepare
pnpm db:push
pnpm db:generate
pnpm lint
pnpm typecheck
pnpm test
pnpm build

What Works Without Optional API Keys

The app can still run with only DATABASE_URL configured.

Without optional keys:

• the web app and worker still boot
• case creation and case review still work
• database-backed workflow records still work
• Tavily-backed endpoints report that the integration is unavailable
• deep investigation is skipped when Gemini credentials are absent
• Redis memory endpoints report unavailable when memory is not configured

This makes local UI and workflow development possible even before integration keys are available.

Troubleshooting

pnpm dev fails while creating or migrating the database

Check:

• DATABASE_URL points to a reachable PostgreSQL server
• the user in DATABASE_URL can create the target database, or the database already exists
• the database user can enable pg_trgm, or the extension is already installed

If your managed Postgres provider does not allow CREATE DATABASE or CREATE EXTENSION, create the database and enable pg_trgm once from the provider side, then rerun pnpm dev.

Web app cannot reach the worker

For local development, the default worker API origin is http://127.0.0.1:4010.

Only set WORKER_API_ORIGIN if you intentionally want the web app to talk to a different worker instance.

Optional integrations show as unavailable

That is expected when the corresponding keys are blank. Add the relevant env vars and restart pnpm dev.

Validation

After setup, these are the main validation commands:

pnpm lint
pnpm typecheck
pnpm test

Note: the current test suite creates temporary PostgreSQL databases during integration tests, so running pnpm test still expects access to a local or otherwise writable PostgreSQL server.

Additional Docs

• Architecture and workflow baseline: docs/purring-inventing-pine-revised.md
• Rebased implementation plan: docs/aml-dd-mvp-implementation-plan-rebased.md
• Historical OMX plan artifacts: .omx/plans/