# sribuddha/aml architecture

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

- Interactive diagram: https://gitdiagram.com/sribuddha/aml
- Repository: https://github.com/sribuddha/aml

## Overview

This is an AML transaction-monitoring product: users upload CSVs, accepted transactions enter persistent storage, and an asynchronous workflow applies rules, enrichment, LLM triage/deep-dive, and SAR review before status is reflected in the dashboard. The map preserves the documented evaluation and rule-management capabilities. Workflow internals beyond the sampled rule engine and job service are based on README descriptions; their individual call wiring was not inspected.

Main entry points: [`src/bff/app.py`](https://github.com/sribuddha/aml/blob/main/src/bff/app.py) (FastAPI application), [`src/aml_workflow/graph.py`](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/graph.py) (Workflow graph), [`src/aml_workflow/llm.py`](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/llm.py) (LLM client and providers), [`src/aml_workflow/nodes/rule_engine.py`](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/rule_engine.py) (Rule engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Officer UI"]
  node_web["React application<br/>[App.tsx]"]
  node_review["SAR review<br/>[useSarReview.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["REST API"]
  node_bff["FastAPI application<br/>[app.py]"]
  node_file_routes["Upload and read routes<br/>[upload.py]"]
  node_sar_routes["SAR endpoints<br/>[sar.py]"]
  node_rule_routes["Rule management<br/>[rules.py]"]
  node_eval_routes["Evaluation API<br/>[eval.py]"]
end

subgraph group_ingestion["File ingestion"]
  node_ingest["CSV validation and insert<br/>[__init__.py]"]
  node_workflow_jobs["Workflow job service<br/>[services.py]"]
end

subgraph group_analysis["AML analysis"]
  node_workflow["Workflow graph<br/>[graph.py]"]
  node_rules["Rule engine<br/>[rule_engine.py]"]
  node_enrichment["Transaction enrichment<br/>[enrichment.py]"]
  node_triage["LLM triage<br/>[triage.py]"]
  node_deep_dive["LLM deep-dive<br/>[triage.py]"]
  node_sar_generation["SAR generation<br/>[sar.py]"]
  node_llm["LLM client and providers<br/>[llm.py]"]
  node_prompts["Prompt builders<br/>[builders.py]"]
  node_fallbacks["LLM fallbacks<br/>[fallbacks.py]"]
end

subgraph group_persistence["State and evaluation"]
  node_database[("SQLite database<br/>[database.py]")]
  node_transaction_model["Transaction records<br/>[transaction.py]"]
  node_upload_model["Upload records<br/>[uploaded_files.py]"]
  node_validation_model["Validation results"]
  node_eval_metrics["Detection quality metrics<br/>[__init__.py]"]
end

node_officer(("Compliance officer"))

node_officer -->|"uses"| node_web
node_web -->|"requests data"| node_api_client
node_api_client -->|"HTTP requests"| node_bff
node_web -->|"presents review"| node_review
node_review -->|"submits decisions"| node_api_client
node_bff -->|"registers routes"| node_file_routes
node_bff -->|"registers routes"| node_sar_routes
node_bff -->|"registers routes"| node_rule_routes
node_bff -->|"registers routes"| node_eval_routes
node_file_routes -->|"processes upload"| node_ingest
node_ingest -->|"inserts accepted rows"| node_database
node_ingest -->|"triggers workflow"| node_workflow_jobs
node_workflow_jobs -->|"runs validation"| node_workflow
node_workflow -.->|"dispatches stage"| node_rules
node_workflow -.->|"dispatches stage"| node_triage
node_workflow -.->|"dispatches stage"| node_deep_dive
node_workflow -.->|"dispatches stage"| node_sar_generation
node_rules -->|"reads and writes"| node_database
node_rules -->|"persists results"| node_validation_model
node_rules -->|"reads transactions"| node_transaction_model
node_enrichment -.->|"supplies context"| node_triage
node_triage -.->|"requests decisions"| node_llm
node_deep_dive -.->|"requests investigation"| node_llm
node_sar_generation -.->|"requests narratives"| node_llm
node_llm -->|"builds prompts"| node_prompts
node_llm -->|"uses fallback"| node_fallbacks
node_eval_routes -->|"runs evaluation"| node_eval_metrics
node_database -->|"stores"| node_transaction_model
node_database -->|"stores"| node_upload_model

click node_web "https://github.com/sribuddha/aml/blob/main/ui/src/App.tsx"
click node_review "https://github.com/sribuddha/aml/blob/main/ui/src/hooks/useSarReview.ts"
click node_api_client "https://github.com/sribuddha/aml/blob/main/ui/src/api/client.ts"
click node_bff "https://github.com/sribuddha/aml/blob/main/src/bff/app.py"
click node_file_routes "https://github.com/sribuddha/aml/blob/main/src/file_processor/rest/upload.py"
click node_sar_routes "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/rest/sar.py"
click node_rule_routes "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/rest/rules.py"
click node_eval_routes "https://github.com/sribuddha/aml/blob/main/src/bff/routes/eval.py"
click node_ingest "https://github.com/sribuddha/aml/blob/main/src/file_processor/service/__init__.py"
click node_workflow_jobs "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/services.py"
click node_workflow "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/graph.py"
click node_rules "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/rule_engine.py"
click node_enrichment "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/enrichment.py"
click node_triage "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/triage.py"
click node_deep_dive "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/triage.py"
click node_sar_generation "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/sar.py"
click node_llm "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/llm.py"
click node_prompts "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/prompts/builders.py"
click node_fallbacks "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/fallbacks.py"
click node_database "https://github.com/sribuddha/aml/blob/main/src/bff/database.py"
click node_transaction_model "https://github.com/sribuddha/aml/blob/main/src/core/models/transaction.py"
click node_upload_model "https://github.com/sribuddha/aml/blob/main/src/core/models/uploaded_files.py"
click node_validation_model "https://github.com/sribuddha/aml/blob/main/src/core/models/validation_result.py"
click node_eval_metrics "https://github.com/sribuddha/aml/blob/main/src/aml_workflow/eval/__init__.py"

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_review,node_api_client toneBlue
class node_bff,node_file_routes,node_sar_routes,node_rule_routes,node_eval_routes toneAmber
class node_ingest,node_workflow_jobs toneMint
class node_workflow,node_rules,node_enrichment,node_triage,node_deep_dive,node_sar_generation,node_llm,node_prompts,node_fallbacks toneRose
class node_database,node_transaction_model,node_upload_model,node_validation_model,node_eval_metrics,node_officer toneIndigo
```

## Components

### Officer UI

- [React application](https://github.com/sribuddha/aml/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [SAR review](https://github.com/sribuddha/aml/blob/main/ui/src/hooks/useSarReview.ts): `ui/src/hooks/useSarReview.ts`
- [API client](https://github.com/sribuddha/aml/blob/main/ui/src/api/client.ts): `ui/src/api/client.ts`

### REST API

- [FastAPI application](https://github.com/sribuddha/aml/blob/main/src/bff/app.py): `src/bff/app.py`
- [Upload and read routes](https://github.com/sribuddha/aml/blob/main/src/file_processor/rest/upload.py): `src/file_processor/rest/upload.py`
- [SAR endpoints](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/rest/sar.py): `src/aml_workflow/rest/sar.py`
- [Rule management](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/rest/rules.py): `src/aml_workflow/rest/rules.py`
- [Evaluation API](https://github.com/sribuddha/aml/blob/main/src/bff/routes/eval.py): `src/bff/routes/eval.py`

### File ingestion

- [CSV validation and insert](https://github.com/sribuddha/aml/blob/main/src/file_processor/service/__init__.py): `src/file_processor/service/__init__.py`
- [Workflow job service](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/services.py): `src/aml_workflow/services.py`

### AML analysis

- [Workflow graph](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/graph.py): `src/aml_workflow/graph.py`
- [Rule engine](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/rule_engine.py): `src/aml_workflow/nodes/rule_engine.py`
- [Transaction enrichment](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/enrichment.py): `src/aml_workflow/enrichment.py`
- [LLM triage](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/triage.py): `src/aml_workflow/nodes/triage.py`
- [LLM deep-dive](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/triage.py): `src/aml_workflow/nodes/triage.py`
- [SAR generation](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/nodes/sar.py): `src/aml_workflow/nodes/sar.py`
- [LLM client and providers](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/llm.py): `src/aml_workflow/llm.py`
- [Prompt builders](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/prompts/builders.py): `src/aml_workflow/prompts/builders.py`
- [LLM fallbacks](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/fallbacks.py): `src/aml_workflow/fallbacks.py`

### State and evaluation

- [SQLite database](https://github.com/sribuddha/aml/blob/main/src/bff/database.py): `src/bff/database.py`
- [Transaction records](https://github.com/sribuddha/aml/blob/main/src/core/models/transaction.py): `src/core/models/transaction.py`
- [Upload records](https://github.com/sribuddha/aml/blob/main/src/core/models/uploaded_files.py): `src/core/models/uploaded_files.py`
- [Validation results](https://github.com/sribuddha/aml/blob/main/src/core/models/validation_result.py): `src/core/models/validation_result.py`
- [Detection quality metrics](https://github.com/sribuddha/aml/blob/main/src/aml_workflow/eval/__init__.py): `src/aml_workflow/eval/__init__.py`

### Other components

- **Compliance officer**

## Connections

- Compliance officer → React application: uses (evidence: `README.md`)
- React application → API client: requests data (evidence: `README.md`)
- API client → FastAPI application: HTTP requests (evidence: `README.md`)
- React application → SAR review: presents review (evidence: `ui/src/App.tsx`)
- SAR review → API client: submits decisions (evidence: `ui/src/hooks/useSarReview.ts`)
- FastAPI application → Upload and read routes: registers routes (evidence: `src/bff/app.py`)
- FastAPI application → SAR endpoints: registers routes (evidence: `src/bff/app.py`)
- FastAPI application → Rule management: registers routes (evidence: `src/bff/app.py`)
- FastAPI application → Evaluation API: registers routes (evidence: `src/bff/app.py`)
- Upload and read routes → CSV validation and insert: processes upload (evidence: `src/file_processor/rest/upload.py`)
- CSV validation and insert → SQLite database: inserts accepted rows (evidence: `src/file_processor/service/__init__.py`)
- CSV validation and insert → Workflow job service: triggers workflow (evidence: `src/file_processor/service/__init__.py`)
- Workflow job service → Workflow graph: runs validation (evidence: `src/aml_workflow/services.py`)
- Workflow graph → Rule engine: dispatches stage (evidence: `README.md`)
- Workflow graph → LLM triage: dispatches stage (evidence: `README.md`)
- Workflow graph → LLM deep-dive: dispatches stage (evidence: `README.md`)
- Workflow graph → SAR generation: dispatches stage (evidence: `README.md`)
- Rule engine → SQLite database: reads and writes (evidence: `src/aml_workflow/nodes/rule_engine.py`)
- Rule engine → Validation results: persists results (evidence: `src/aml_workflow/nodes/rule_engine.py`)
- Rule engine → Transaction records: reads transactions (evidence: `src/aml_workflow/nodes/rule_engine.py`)
- Transaction enrichment → LLM triage: supplies context (evidence: `README.md`)
- LLM triage → LLM client and providers: requests decisions (evidence: `src/aml_workflow/llm.py`)
- LLM deep-dive → LLM client and providers: requests investigation (evidence: `src/aml_workflow/llm.py`)
- SAR generation → LLM client and providers: requests narratives (evidence: `src/aml_workflow/llm.py`)
- LLM client and providers → Prompt builders: builds prompts (evidence: `src/aml_workflow/llm.py`)
- LLM client and providers → LLM fallbacks: uses fallback (evidence: `src/aml_workflow/llm.py`)
- Evaluation API → Detection quality metrics: runs evaluation (evidence: `src/bff/routes/eval.py`)
- SQLite database → Transaction records: stores (evidence: `src/bff/database.py`)
- SQLite database → Upload records: stores (evidence: `src/bff/database.py`)
