🔄 CDD Workflow

End-to-end process breakdown

🎯 Workflow Overview The CDD Builder uses a multi-agent architecture with specialized AI agents (Writer, Critic, Updater) working in sequence to produce compliance-grade Customer Due Diligence reports. The system automatically gathers evidence, assesses geographic and AML risks, generates drafts with citations, critiques for compliance gaps, and applies corrections.

Case Initialization

Create a new CDD case with customer information

▼

1.1

User Creates Case

User navigates to the home page and fills out the case creation form with customer details.

Input Fields:

Company Name - Customer legal name
Registration Number - Company registration/incorporation number
Country - Country of incorporation
Website URL - Official company website (optional)

Technical Flow:

index.html → Form submission via app.js
POST request to /cases endpoint
node/src/server.ts → Creates PostgreSQL record
Database: INSERT into cases table
Returns: Case ID and redirects to case.html?id={caseId}

1.2

Case Page Loads

System loads the case management page with empty evidence section.

Loaded Components:

Case metadata display (name, reg number, country, website)
Evidence sources section (initially empty)
Draft panel (placeholder "No draft yet")
Findings panel (hidden until critique runs)
Citations tab (hidden until draft generated)

Evidence Gathering & Risk Assessment

Collect evidence from websites/PDFs and perform automated risk analysis

▼

2.1

Add Evidence Sources

User adds evidence sources (websites or PDF uploads) to the case.

Website Sources:

User clicks "Add Website" button
Enters URL and optional display name
Stored temporarily in browser state (not yet gathered)
POST to /cases/:id/sources → Saves to database

PDF Sources:

User clicks "Upload PDF" button
Selects PDF file from local machine
POST to /cases/:id/upload-pdf with multipart form data
Server saves to node/uploads/{hash}
Database record created with file path

2.2

Gather Evidence

User clicks "Gather Evidence" button to trigger automated evidence collection and chunking.

Process Flow:

Frontend: POST to /cases/:id/gather (Node API)
Node API: Proxies to http://python-api:8888/gather
Python: python/src/api.py → gather() endpoint
Calls: python/src/cdd/gatherer.py → Gatherer.gather_evidence()

Website Processing:

web_connector.py → fetch_allowlisted() fetches HTML
Extracts text content from HTML (strips tags)
Computes SHA-256 hash for deduplication
Saves raw HTML to cases/{case_id}/raw/website_{hash}.txt
chunking.py → chunk_text() splits into 800-char chunks with 100-char overlap
Saves chunks to cases/{case_id}/extracted/web_{hash}.jsonl

PDF Processing:

pdf_connector.py → extract_pdf_pages() uses PyMuPDF
Extracts text page-by-page
Combines all pages into single text document
Chunks with same logic (800-char chunks, 100-char overlap)
Saves to cases/{case_id}/extracted/pdf_{hash}.jsonl

Evidence Items Created:

Each source produces an evidence item with:
- evidence_id: "web-{hash}" or "pdf-{hash}"
- type: "WEBSITE" or "PDF"
- chunks: Array of {chunk_id, text, span_start, span_end}
- original_ref: URL or filename

2.3

Auto-Load Policy Evidence

AMLR COMPLIANCE

System automatically loads regulatory policy evidence (EU high-risk countries, FATF lists).

Process Flow:

gatherer.py calls policy_loader.load_policy_evidence()
Loads 3 policy evidence sources:
- EU High-Risk Countries: 28 countries from EU AML/CFT Directive
- FATF Black List: 3 countries under Call for Action
- FATF Grey List: 23 countries under increased monitoring

Policy Evidence Items:

evidence_id: "eu-high-risk-policy", "fatf-black-list", "fatf-grey-list"
type: "HIGH_RISK_COUNTRY_POLICY"
chunks: One chunk per country with:
- Country name and ISO code
- Policy designation (EU Annex I, FATF Black, FATF Grey)
- Risk rationale
- Citable reference (e.g., "EU Directive 2015/849 Annex I")
These chunks enable policy-anchored citations in drafts

Modules Involved:

policy_ingest_eu.py - EU high-risk countries
policy_ingest_fatf.py - FATF black/grey lists
policy_loader.py - Loads and structures policy evidence

2.4

Geographic Risk Assessment

AMLR COMPLIANCE

System automatically performs policy-anchored geographic risk assessment.

Process Flow:

api.py calls geo_risk_assessment_v2.assess_geographic_risk()
Step 1: Extract countries from evidence
- geo_extractor.py → GeoExposureExtractor
- Uses country_normalization.py to normalize country names to ISO codes
- Handles variations: "United States" / "USA" / "US" → "US"
- Assigns confidence levels: HIGH (explicit mention), MEDIUM (inferred), LOW (ambiguous)
Step 2: Lookup policy risk classification
- policy_lookup.py → PolicyLookup
- Cross-references against EU/FATF lists
- Classification logic:
  - CRITICAL: FATF Black List (Iran, Myanmar, North Korea)
  - HIGH: On both EU + FATF Grey (e.g., Nigeria, South Africa)
  - ELEVATED: On EU or FATF Grey only
  - STANDARD: Not on any list
Step 3: Generate assessment artifact
- Creates geo_risk_assessment.json with:
  - countries_assessed: Array of country objects
  - risk_summary: Aggregate stats (critical_count, high_count, edd_required)
  - policy_refs: Array of citable policy evidence references
  - evidence_refs: Array of customer evidence references
- Saves to cases/{case_id}/artifacts/geo_risk_assessment.json
Step 4: Add as special evidence item
- evidence_id: "geo-assessment-{case_id}"
- type: "GEO_RISK_ASSESSMENT"
- Enables Writer agent to cite geographic assessment

Key Enhancement:

Replaces inference-based geo assessment with policy-anchored approach
Every geographic risk statement is backed by:
1. Customer evidence (where country mentioned in website/PDF)
2. Policy evidence (EU/FATF designation with regulatory citation)

2.5

Store Evidence in Database

All gathered evidence items are stored in PostgreSQL for persistence and retrieval.

Database Operations:

Node API receives evidence array from Python
For each evidence item:
- INSERT into evidence_sources table
- Stores: evidence_id, type, original_ref, content_hash, chunks JSON
- Links to case via case_id foreign key
Frontend refreshes evidence list from database

Draft Generation (Writer Agent)

AI agent generates CDD draft v1 with inline citations

▼

3.1

User Triggers Draft Generation

User clicks "Generate Draft v1" button after evidence gathering completes.

Trigger Conditions:

At least one evidence source must exist
Evidence must be gathered (chunks created)
Button disabled until conditions met

3.2

Load Writer Prompts

System loads Writer agent system and user prompts from external files.

Prompt Loading:

node/src/server.ts → POST /cases/:id/draftv1
Calls node/src/agentService.ts → generateDraftV1()
Uses prompts/index.ts → getWriterPrompts()
Loads:
- prompts/writer/system.txt - Core instructions (130 lines)
- prompts/writer/user-template.txt - Case-specific template
Substitutes variables: {{name}}, {{registrationNumber}}, {{country}}, {{websiteUrl}}, {{evidenceContext}}

3.3

Build Evidence Context

System formats all evidence items (including geo assessment and policy evidence) into prompt context.

Context Structure:

For each evidence item:
- Evidence ID: "web-abc123"
- Type: WEBSITE, PDF, GEO_RISK_ASSESSMENT, HIGH_RISK_COUNTRY_POLICY
- Source: Original URL or filename
- Chunks: List of chunk_id + text preview (first 150 chars)

Example:

Evidence ID: web-abc123
Type: WEBSITE
Source: https://sandvik.com
Chunks:
  - c-0: Sandvik is a high-tech engineering group with...
  - c-1: The company operates in 160 countries...
  - c-2: Products include mining equipment, cutting tools...

Evidence ID: geo-assessment-case-123
Type: GEO_RISK_ASSESSMENT
Source: Geographic Risk Assessment
Chunks:
  - assessment-summary: Geographic risk assessment completed...

Evidence ID: fatf-black-list
Type: HIGH_RISK_COUNTRY_POLICY
Source: FATF Call for Action List
Chunks:
  - country-1: Iran - FATF Black List...
  - country-2: Myanmar - FATF Black List...

3.4

Writer Agent Processing

AMLR COMPLIANCE

OpenAI GPT-4o processes the Writer system prompt and evidence context to generate CDD draft.

Key Writer Instructions:

Section Structure: 7 mandatory sections:
1. Business Profile
2. Ownership & Control
3. AML/CTF/Sanctions Screening (3 subsections)
4. Inherent Financial Crime Risk Assessment (5 subsections)
5. EDD Triggers & Rationale
6. Monitoring Plan
7. Conclusion
Citation Requirements:
- EVERY factual paragraph MUST have inline citations [EID:evidence_id:chunk_id]
- If information missing, write [OPEN QUESTION] instead of fabricating
- Each paragraph gets unique paragraph_id (p-1, p-2, ..., p-N)
Geographic Risk Rules (NEW - Task 14):
- ALWAYS check for geo_risk_assessment.json evidence
- Cite BOTH policy evidence (EU/FATF) AND customer evidence
- Example: "Operations in Iran [EID:web-abc:c-5] pose CRITICAL AML risk as Iran is designated on FATF Call for Action list [EID:fatf-black-list:country-1]"
- Use policy_refs and evidence_refs from geo assessment
- If edd_required_geo=true, MUST mention in EDD Triggers section
- NEVER infer countries from "global operations" - only use explicitly identified countries
Screening Action Statements (NEW - Task 18):
- Required screening actions at onboarding:
  1. "Customer and beneficial owners (>25%) must be screened against EU, OFAC, UN, UK sanctions lists"
  2. "Beneficial owners and key management must be screened for PEP status"
  3. "Adverse media screening for financial crime (5-year lookback) required"
  4. "Corporate registry verification required for beneficial ownership structure"
- If screening evidence NOT provided, include action statements AND [OPEN QUESTION]
- Do NOT state "no matches" or "clean" without explicit screening evidence
- Do NOT use ESG memberships or sustainability indices as "screening"
EDD Triggers Assessment (NEW - Task 25):
- MUST assess ALL 5 EDD trigger categories:
  1. GEOGRAPHIC: High-risk/sanctioned countries (use geo_risk_assessment.json)
  2. SCREENING: Sanctions/PEP/adverse media hits
  3. BUSINESS MODEL: Complex structures, cash-intensive, PEP ownership
  4. TRANSACTION PATTERNS: High volume, unusual patterns
  5. CUSTOMER TYPE: Shell companies, trusts, bearer shares
- For EACH category, state "TRIGGERED" or "NOT TRIGGERED" with citation/rationale
- If ANY trigger active, conclude: "Enhanced Due Diligence procedures apply"

API Call:

Model: gpt-4o
Temperature: 0.3 (deterministic, compliance-focused)
Response format: JSON object
Messages:
- Role: "system" → Writer system prompt (130 lines)
- Role: "user" → Case info + evidence context

3.5

Parse Draft Response

System parses the JSON response from OpenAI and extracts draft text and citations structure.

Response Structure:

draft: Markdown-formatted CDD text with inline [EID:...] citations
citations: Object with paragraphs array:
- paragraph_id: "p-1", "p-2", ..., "p-N"
- section_id: "business_profile", "risk_geographic", "edd_triggers", etc.
- citations: Array of {evidence_id, chunk_id, span_start, span_end}

Example Citation Object:

{
  "paragraph_id": "p-7",
  "section_id": "risk_geographic",
  "citations": [
    {"evidence_id": "web-abc123", "chunk_id": "c-5", "span_start": 0, "span_end": 50},
    {"evidence_id": "fatf-black-list", "chunk_id": "country-1", "span_start": 120, "span_end": 170}
  ]
}

3.6

Store Draft in Database

Draft and citations are stored in PostgreSQL for retrieval and versioning.

Database Operations:

UPDATE cases table:
- Set draft_v1 = markdown text
- Set citations_v1 = JSON object
- Set updated_at = current timestamp
Frontend fetches updated case record
Renders draft in "Draft" tab with inline citations highlighted
Populates "Citations" tab with evidence references

Draft Critique (Critic Agent)

AI agent analyzes draft for compliance gaps and missing evidence

▼

4.1

User Triggers Critique

User reviews draft v1 and clicks "Critique" button to run quality assurance checks.

Trigger Conditions:

Draft v1 must exist
Citations must be available
Button enabled after draft generation completes

4.2

Load Critic Prompts

System loads Critic agent system and user prompts from external files.

Prompt Loading:

node/src/server.ts → POST /cases/:id/critique
Calls agentService.ts → generateFindings()
Uses prompts/index.ts → getCriticPrompts()
Loads:
- prompts/critic/system.txt - Compliance checks (21 rules)
- prompts/critic/user-template.txt - Draft + citations

4.3

Critic Agent Analysis

AMLR COMPLIANCE

OpenAI GPT-4o analyzes draft against 21 compliance rules and generates findings.

Critic Rules (BLOCKERS - Must Fix):

EVD-01: Paragraphs without citations (uncited factual claims)
EVD-02: Invalid evidence references (broken citation links)
SCR-01: Missing AML/CTF/Sanctions Screening section
SCR-02: Incomplete screening coverage (missing subsections)
SAN-01: Sanctions subsection missing or lacks evidence/[OPEN QUESTION]
SCR-ESG-01: Screening incorrectly uses ESG/governance indices
SCR-ACT-01 (NEW - Task 19): Missing screening action statements when evidence not provided
COMP-01: Missing mandatory section_ids (incomplete structure)

Critic Rules (MAJORS - Should Fix):

PEP-01: PEP subsection missing or incomplete
ADV-01: Adverse media subsection missing or not evidence-backed
GEO-01: Geographic risk assessment missing when applicable
GEO-POL-01 (NEW - Task 32): Geographic risk doesn't cite policy evidence (EU/FATF lists)
OWN-06: Ownership section doesn't conclude if controlling UBO exists (>25%)
SECT-01: No sector AML typology discussion for relevant sectors
TP-01: No third-party risk consideration when relevant
CTF-01: No terrorist financing risk consideration
GEO-EDD-01 (NEW - Task 32): Geographic assessment shows edd_required_geo=true but EDD section doesn't mention it
EDD-SCOPE-01 (NEW - Task 32): EDD Triggers section incomplete - missing assessment of all 5 categories
EDD-SCOPE-02 (NEW - Task 32): EDD Triggers section missing comprehensive conclusion
RISK-03: EDD triggers not identified when risk indicators present
BUS-03: [OPEN QUESTION] markers present (missing information)

Finding Structure:

finding_id: "FID-1", "FID-2", etc.
severity: "BLOCKER", "MAJOR", or "MINOR"
code: Rule code (e.g., "SCR-ACT-01")
title: Brief description
impacted_paragraph_ids: Array of affected paragraph IDs
evidence_refs: What evidence exists or is missing
remediation: Specific fix instructions

4.4

Store Findings in Database

Findings are stored in PostgreSQL for review and correction tracking.

Database Operations:

UPDATE cases table:
- Set findings_v1 = JSON array of findings
- Set updated_at = current timestamp
Frontend fetches findings and displays in "Findings" panel
Findings grouped by severity (BLOCKERS first, then MAJORS, then MINORS)
Each finding shows code, title, affected paragraphs, and remediation

Draft Update (Updater Agent)

AI agent applies corrections and generates draft v2

▼

5.1

User Triggers Update

User reviews findings and clicks "Update to v2" button to apply automated corrections.

Trigger Conditions:

Findings must exist from Critic
At least one BLOCKER or MAJOR finding present
Button enabled after critique completes

5.2

Load Updater Prompts

System loads Updater agent system and user prompts from external files.

Prompt Loading:

node/src/server.ts → POST /cases/:id/updatev2
Calls agentService.ts → applyFindings()
Uses prompts/index.ts → getUpdaterPrompts()
Loads:
- prompts/updater/system.txt - Fix instructions with auto-fix logic
- prompts/updater/user-template.txt - Draft + findings + evidence

5.3

Updater Agent Processing

AMLR COMPLIANCE

OpenAI GPT-4o applies corrections to draft, tracking all changes and documenting open questions.

Update Rules:

Minimal Patch Policy: Only modify sections with identified findings
Preserve Citations: Maintain all existing valid citations
Add Evidence: Add proper citations [EID:...] for new content
[OPEN QUESTION]: Use when evidence missing for fix
Track Changes: Document every change in delta_log with finding_id
No Fabrication: Do NOT invent screening results or risk assessments

Auto-Fix Logic (NEW - Task 33):

SCR-ACT-01 Auto-Fix: Missing screening action statements
- Insert standardized action statements in screening subsections
- Example: "Customer and beneficial owners (>25%) must be screened against EU, OFAC, UN, UK sanctions lists [OPEN QUESTION] Provide sanctions screening results"
- Track as "auto-fix: added required screening action statements"
EDD-SCOPE-01/02 Auto-Fix: Incomplete EDD assessment
- Restructure EDD Triggers section to assess ALL 5 categories
- For each category, state "TRIGGERED" or "NOT TRIGGERED" with rationale
- Check geo_risk_assessment.json for edd_required_geo flag
- Add comprehensive conclusion
GEO-POL-01 Auto-Fix: Missing policy citations
- Check for geo_risk_assessment.json in evidence
- For each high-risk country, add policy_refs from geo assessment
- Format: "[Country] [customer EID] designated as [risk] under [policy] [policy EID]"

Output Structure:

draftV2: Updated markdown draft with fixes applied
deltaLog: Object with changes array:
- finding_id: Which finding addressed
- before: Original text snippet
- after: Updated text snippet
- rationale: Why this change fixes the finding
openQuestions: Markdown-formatted list of unanswered items:
- [CODE] Specific requirement
- Section/paragraph reference
- What evidence type needed

5.4

Store Draft v2 in Database

Updated draft, delta log, and open questions are stored in PostgreSQL.

Database Operations:

UPDATE cases table:
- Set draft_v2 = updated markdown text
- Set delta_log = JSON changes array
- Set open_questions = markdown text
- Set updated_at = current timestamp
Frontend displays:
- Draft v2 in "Draft" tab (replaces v1)
- Delta log in "Changes" section (shows before/after for each fix)
- Open questions in expandable panel (what evidence still needed)

Human Review & Export

Compliance officer reviews final draft and exports for approval

▼

6.1

Review Draft v2

Compliance officer reviews the updated draft with all corrections applied.

Review Checklist:

Verify all BLOCKER findings resolved
Check MAJOR findings addressed or documented as [OPEN QUESTION]
Review geographic risk statements have policy citations
Confirm screening action statements present when evidence missing
Validate EDD Triggers section assesses all 5 categories
Check citations resolve correctly (click to view source chunks)

6.2

Review Open Questions

Officer reviews list of outstanding evidence requirements.

Open Questions Format:

Grouped by category: Screening, Geographic Risk, Business Profile, etc.
Each item shows:
- Compliance code (e.g., [SAN-01], [PEP-01])
- Specific requirement
- What evidence to collect
- Finding ID reference (links back to Critic finding)
Officer can gather additional evidence and re-run workflow

6.3

Review Citations

Officer clicks on citations in draft to verify source evidence.

Citation Features:

Inline citations are clickable links: [EID:web-abc:c-5]
Click opens modal with:
- Evidence source (URL or filename)
- Chunk text (full 800-char chunk)
- Context (preceding and following chunks)
"Citations" tab shows all citations grouped by section
Each section lists all evidence items referenced

6.4

Export Draft (Future)

Officer exports final draft to PDF/Word for submission to approval workflow.

Export Options (To Be Implemented):

Export as PDF with formatted citations
Export as Word document (editable)
Export evidence bundle (draft + all source PDFs/URLs)
Export audit trail (delta log, findings, open questions)

Technology Stack

Frontend

Vanilla JavaScript (ES6+)
HTML5 / CSS3
Responsive design (mobile-first)
No framework dependencies

Node.js API

TypeScript 5.x
Express.js server
OpenAI GPT-4o integration
PostgreSQL client (pg)
Multer file uploads

Python API

Python 3.11+
Flask web framework
PyMuPDF (PDF extraction)
BeautifulSoup (web scraping)
Custom CDD modules (8 new)

Database

PostgreSQL 16
Tables: cases, evidence_sources
JSON columns for citations, findings
Migrations system

Infrastructure

Docker containers (Podman)
Docker Compose orchestration
Nginx reverse proxy
Volume mounts for evidence files

AI/ML

OpenAI GPT-4o (Writer, Critic, Updater)
Temperature: 0.3 (deterministic)
JSON response format
External prompt files (versioned)

📊 Workflow Metrics (Typical Case)

Phase 1: 1 minute (case creation)
Phase 2: 2-5 minutes (evidence gathering + geo assessment)
Phase 3: 30-60 seconds (draft generation via GPT-4o)
Phase 4: 20-30 seconds (critique via GPT-4o)
Phase 5: 30-45 seconds (update via GPT-4o)
Phase 6: 5-15 minutes (human review)
Total: ~10-25 minutes end-to-end