# ashkanrdn/dd architecture

> Architecture diagram of the GitHub repository ashkanrdn/dd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashkanrdn/dd
- Repository: https://github.com/ashkanrdn/dd

## Overview

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: [`apps/worker/src/jobs/case-runner.ts`](https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/case-runner.ts) (Case runner), [`apps/web/src/app/api`](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/web/src/app/api) (API routes), [`packages/workflow`](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/workflow) (Workflow), [`packages/connectors`](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/connectors) (Connectors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_web["Web app<br/>nextjs analyst UI"]
  node_web_ui["Case UI<br/>analyst console"]
  node_web_api["API routes<br/>server routes"]
  node_worker["Worker<br/>execution backend"]
  node_worker_api["Worker API<br/>internal http api<br/>[api-server.ts]"]
  node_case_runner["Case runner<br/>workflow orchestrator<br/>[case-runner.ts]"]
  node_investigation_exec["Investigation<br/>analysis job"]
  node_sanctions_exec["Sanctions<br/>screening job"]
  node_report_gen["Reports<br/>report job"]
  node_html_report_gen["HTML report<br/>render job"]
end

subgraph group_packages["Packages"]
  node_contracts["Contracts<br/>shared schema"]
  node_workflow["Workflow<br/>state machine"]
  node_agents["Agents<br/>llm orchestration"]
  node_connectors["Connectors<br/>external sources"]
  node_matching["Matching"]
  node_policy["Policy<br/>source activation"]
  node_db[("Database<br/>prisma postgres")]
  node_memory["Memory"]
end

subgraph group_python["Python"]
  node_ingestion["Ingestion<br/>python sync utility"]
end

node_web -->|"renders"| node_web_ui
node_web -->|"exposes"| node_web_api
node_web_ui -->|"reads/writes"| node_web_api
node_web_api -->|"uses"| node_contracts
node_web_api -->|"interprets"| node_workflow
node_web_api -->|"queries"| node_db
node_worker -->|"serves"| node_worker_api
node_worker -->|"runs"| node_case_runner
node_case_runner -->|"dispatches"| node_investigation_exec
node_case_runner -->|"dispatches"| node_sanctions_exec
node_case_runner -->|"dispatches"| node_report_gen
node_case_runner -->|"dispatches"| node_html_report_gen
node_worker_api -->|"uses"| node_contracts
node_worker_api -->|"drives"| node_workflow
node_case_runner -->|"depends on"| node_workflow
node_investigation_exec -->|"uses"| node_agents
node_sanctions_exec -->|"uses"| node_matching
node_sanctions_exec -->|"reads"| node_connectors
node_agents -->|"calls"| node_connectors
node_agents -.->|"optionally uses"| node_memory
node_workflow -->|"defines"| node_contracts
node_workflow -->|"persists"| node_db
node_db -->|"stores"| node_contracts
node_policy -->|"configures"| node_connectors
node_ingestion -.->|"syncs data for"| node_connectors
node_connectors -->|"feeds"| node_matching
node_web -->|"coordinates with"| node_worker

click node_web "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/web"
click node_web_ui "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/web/src/components/cases"
click node_web_api "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/web/src/app/api"
click node_worker "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/worker"
click node_worker_api "https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/api-server.ts"
click node_case_runner "https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/case-runner.ts"
click node_investigation_exec "https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/investigation-executor.ts"
click node_sanctions_exec "https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/sanctions-executor.ts"
click node_report_gen "https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/report-generator.ts"
click node_html_report_gen "https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/final-html-report-generator.ts"
click node_contracts "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/contracts"
click node_workflow "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/workflow"
click node_agents "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/agents"
click node_connectors "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/connectors"
click node_matching "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/matching"
click node_policy "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/policy"
click node_db "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/db"
click node_memory "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/memory"
click node_ingestion "https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/python/ingestion"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_web_ui,node_web_api,node_worker,node_worker_api,node_case_runner,node_investigation_exec,node_sanctions_exec,node_report_gen,node_html_report_gen toneBlue
class node_contracts,node_workflow,node_agents,node_connectors,node_matching,node_policy,node_db,node_memory toneAmber
class node_ingestion toneMint
```

## Components

### Apps

Runtime applications

- [Web app](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/web): nextjs analyst UI · Analyst workspace, case views, and thin API routes for case operations · `apps/web`
- [Case UI](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/web/src/components/cases): analyst console · Case list, detail, review workspace, leads, findings, and report panels · `apps/web/src/components/cases`
- [API routes](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/web/src/app/api): server routes · Case CRUD, start/cancel/archive, review, events, and report retrieval endpoints · `apps/web/src/app/api`
- [Worker](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/apps/worker): execution backend · Separate case-processing runtime with internal API and job orchestration · `apps/worker`
- [Worker API](https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/api-server.ts): internal http api · Internal server used to drive workflow actions and inspect generated artifacts · `apps/worker/src/api-server.ts`
- [Case runner](https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/case-runner.ts): workflow orchestrator · Coordinates case progression and gates execution phases · `apps/worker/src/jobs/case-runner.ts`
- [Investigation](https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/investigation-executor.ts): analysis job · Runs investigation steps and coordinates deeper due-diligence work · `apps/worker/src/jobs/investigation-executor.ts`
- [Sanctions](https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/sanctions-executor.ts): screening job · Executes sanctions matching and screening-related processing · `apps/worker/src/jobs/sanctions-executor.ts`
- [Reports](https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/report-generator.ts): report job · Builds structured case reports from workflow outputs · `apps/worker/src/jobs/report-generator.ts`
- [HTML report](https://github.com/ashkanrdn/dd/blob/feature/m5-2-through-m8/apps/worker/src/jobs/final-html-report-generator.ts): render job · Generates final HTML report artifacts for cases · `apps/worker/src/jobs/final-html-report-generator.ts`

### Packages

Shared domain and service libraries

- [Contracts](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/contracts): shared schema · Shared case, event, lead, finding, report, subject, match, and decision types · `packages/contracts`
- [Workflow](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/workflow): state machine · State transitions, phases, review logic, risk signals, and ownership evaluation · `packages/workflow`
- [Agents](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/agents): llm orchestration · Specialist analyzers for search planning, entity resolution, sanctions reasoning, and report generation · `packages/agents`
- [Connectors](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/connectors): external sources · Tavily, Companies House, OpenCorporates, and sanctions registry adapters · `packages/connectors`
- [Matching](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/matching): sanctions matching · OFAC-oriented matching logic and candidate comparison · `packages/matching`
- [Policy](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/policy): source activation · Default source activation policy and screening scope configuration · `packages/policy`
- [Database](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/db): prisma postgres · Prisma schema, repositories, bootstrap, seed, and persistence helpers · `packages/db`
- [Memory](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/packages/memory): redis agent memory · Optional Redis-backed memory service for agent workflows · `packages/memory`

### Python

Ingestion utility

- [Ingestion](https://github.com/ashkanrdn/dd/tree/feature/m5-2-through-m8/python/ingestion): python sync utility · OpenSanctions download and fixture-sync utility for reproducible data ingestion · `python/ingestion`

## Connections

- 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
