How ashkanrdn/dd works
1. Overall shape
- This is a monorepo for an AML / sanctions due-diligence workspace.
- The architecture is split into a Next.js analyst UI, a local worker/API process, and shared libraries for workflow, contracts, persistence, matching, and external integrations.
- The core unit of work is a case that moves through screening, investigation, review, reporting, and archive/cancel states.
2. Primary runtime boundary
- apps/web is the user-facing application running on the web port.
- apps/worker is the case-execution backend running separately on its own local HTTP port.
- Both depend on the same PostgreSQL database through shared Prisma-backed repositories, but the worker is where most workflow execution and agentic processing happens.
3. Web app responsibilities
- The Next.js app owns the analyst workspace UI: case list, case detail, create-case flow, review workspace, lead disposition, findings review, and report display.
- Its app/api routes provide a thin server-side API layer for case CRUD and operational actions like start, cancel, archive, analyst review, event streaming, report retrieval, and final HTML report access.
- UI components are organized around case panels rather than generic frontend primitives, indicating a workflow-centric analyst console rather than a consumer web app.
4. Worker responsibilities
- The worker process is the execution engine for case progression.
- Its jobs include case runner orchestration, investigation execution, risk-signal evaluation, sanctions execution, report generation, and final HTML report generation.
- It also exposes an internal API server used by the UI and by tests to drive workflow actions and inspect generated artifacts.
5. Shared domain contracts
- packages/contracts defines the shared data model for the system: cases, events, leads, findings, reports, subjects, match candidates, ownership edges, and risk decisions.
- This package is the main schema boundary between UI, worker, and persistence, keeping all subsystems aligned on the same case vocabulary.
- The presence of dedicated contract types for findings, risk decisions, and investigation reports suggests the product is built around structured due-diligence artifacts, not just freeform notes.
6. Workflow and state machine
- packages/workflow contains the state transitions, phases, review logic, risk-signal logic, and ownership evaluation.
- This is the central business-logic boundary that determines how a case moves from intake to screening, investigation, review, and completion.
- The worker consumes this layer to decide what to run next, while the web app consumes the resulting case state and events for display.
7. Agentic analysis layer
- packages/agents contains the LLM/agent orchestration and specialist analyzers.
- It includes helpers for entity resolution, search planning, OSINT lead generation, sanctions reasoning, risk reasoning, investigation coordination, and final report generation.
- Specialist modules such as adverse media, entity enrichment, ownership, key-person, and narrative indicate a multi-step analyst-assist pipeline rather than a single prompt call.
8. External data integrations
- packages/connectors is the boundary for third-party and public-data sources.
- It includes Tavily for OSINT search/extract, Companies House, OpenCorporates, and sanctions registry adapters.
- The README shows the default active sanctions policy is US-centric: OFAC SDN, OFAC CONS, and BIS Denied Persons, with additional mapped-but-dormant sources in the registry.
9. Screening, matching, and policy
- packages/matching implements sanctions matching logic, including OFAC-related matching.
- packages/policy holds the source activation policy configuration, which determines which registries are active by default.
- packages/connectors/src/sanctions/registry-data.json is the canonical source registry, while packages/policy/src/config/ofac-demo-policy.v2.json defines the default screening scope. This is an important separation: registry coverage exists independently of what the active policy enables.
10. Persistence layer
- packages/db owns the Prisma schema, DB bootstrap, repositories, and seed/test helpers.
- The app expects a PostgreSQL database and uses it for case state, reports, events, and investigation artifacts.
- Local startup bootstraps the database, applies schema changes, and attempts to enable pg_trgm, which is significant because matching depends on trigram support.
11. Eventing and live updates
- The worker and web app share a case event model through packages/contracts and packages/workflow.
- The web API includes a streaming events route, indicating that case progress is surfaced to the UI as an event stream rather than only through polling.
- This supports a live analyst experience where workflow ticks, findings, and report generation can appear incrementally.
12. Memory and optional services
- packages/memory wraps a Redis-backed agent memory service used by some agent workflows.
- Optional integration keys gate features such as Tavily, Gemini/Google GenAI, Redis memory, Companies House, and OpenCorporates.
- The repo is designed so the core case workflow still runs without these keys; unavailable integrations degrade gracefully rather than blocking startup.
13. Python ingestion utility
- python/ingestion is a separate utility layer for fixture and source sync ingestion, especially for OpenSanctions downloads.
- It is not part of the main runtime path, but it supports data acquisition and reproducible fixtures for tests and offline development.
- The presence of fixture directories for Companies House and OpenSanctions suggests strong emphasis on repeatable integration testing and offline validation.
14. Testing and validation boundaries
- Each major package has its own tests, and the worker/web layers also have integration-style tests around API routes and workflow behavior.
- The fixture-heavy test setup indicates the architecture is designed to verify end-to-end sanctions and investigation flows without always depending on live external APIs.
- From an architecture diagram perspective, the key arrows are: analyst UI → web API → DB/worker, and worker → connectors/agents/workflow → DB/events/reports → UI.
Main entry points: case-runner.ts Case runner · api API routes · workflow Workflow · connectors Connectors
Components 19
Apps
Runtime applications
- Web app · Analyst workspace, case views, and thin API routes for case operations
apps/web - Case UI · Case list, detail, review workspace, leads, findings, and report panels
apps/web/src/components/cases - API routes · Case CRUD, start/cancel/archive, review, events, and report retrieval endpoints
apps/web/src/app/api - Worker · Separate case-processing runtime with internal API and job orchestration
apps/worker - Worker API · Internal server used to drive workflow actions and inspect generated artifacts
apps/worker/src/api-server.ts - Case runner · Coordinates case progression and gates execution phases
apps/worker/src/jobs/case-runner.ts - Investigation · Runs investigation steps and coordinates deeper due-diligence work
apps/worker/src/jobs/investigation-executor.ts - Sanctions · Executes sanctions matching and screening-related processing
apps/worker/src/jobs/sanctions-executor.ts - Reports · Builds structured case reports from workflow outputs
apps/worker/src/jobs/report-generator.ts - HTML report · Generates final HTML report artifacts for cases
apps/worker/src/jobs/final-html-report-generator.ts
Packages
Shared domain and service libraries
- Contracts · Shared case, event, lead, finding, report, subject, match, and decision types
packages/contracts - Workflow · State transitions, phases, review logic, risk signals, and ownership evaluation
packages/workflow - Agents · Specialist analyzers for search planning, entity resolution, sanctions reasoning, and report generation
packages/agents - Connectors · Tavily, Companies House, OpenCorporates, and sanctions registry adapters
packages/connectors - Matching · OFAC-oriented matching logic and candidate comparison
packages/matching - Policy · Default source activation policy and screening scope configuration
packages/policy - Database · Prisma schema, repositories, bootstrap, seed, and persistence helpers
packages/db - Memory · Optional Redis-backed memory service for agent workflows
packages/memory
Python
Ingestion utility
- Ingestion · OpenSanctions download and fixture-sync utility for reproducible data ingestion
python/ingestion
Connections 27
- Web app → Case UI: renders · The Next.js app serves the analyst console
- Web app → API routes: exposes · Server routes provide case and integration operations
- Case UI → API routes: reads/writes · The UI uses API routes for case actions and live state
- API routes → Contracts: uses · API payloads follow the shared domain schema
- API routes → Workflow: interprets · Routes present case state and workflow outcomes
- API routes → Database: queries · Case data and reports are loaded from persistence
- Worker → Worker API: serves · Worker exposes an internal HTTP interface
- Worker → Case runner: runs · Primary execution loop for case progression
- Case runner → Investigation: dispatches · Investigation phase jobs are launched from the runner
- Case runner → Sanctions: dispatches · Screening and matching work is triggered from the runner
- Case runner → Reports: dispatches · Structured report generation happens after workflow milestones
- Case runner → HTML report: dispatches · Final HTML artifact generation is a downstream job
- Worker API → Contracts: uses · Internal API serializes shared case/event artifacts
- Worker API → Workflow: drives · Internal API can advance or inspect workflow state
- Case runner → Workflow: depends on · Runner uses transitions, phases, and review logic
- Investigation → Agents: uses · Investigation relies on agentic analysis helpers
- Sanctions → Matching: uses · Sanctions execution depends on matching logic
- Sanctions → Connectors: reads · Screening consults registry and source adapters
- Agents → Connectors: calls · LLM workflows pull OSINT and registry data through connectors
- Agents → Memory: optionally uses · Some agent flows persist or retrieve Redis-backed memory
- Workflow → Contracts: defines · The workflow layer operates on the shared case vocabulary
- Workflow → Database: persists · State changes and events are stored through repositories
- Database → Contracts: stores · Repositories persist contract-shaped case artifacts
- Policy → Connectors: configures · Policy selects which registry sources are active
- Ingestion → Connectors: syncs data for · Python ingestion supports registry fixture and source sync
- Connectors → Matching: feeds · Source and registry data provide match candidates
- Web app → Worker: coordinates with · The analyst app drives execution through the worker boundary