# abo7adeed/omerta.ai architecture

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

- Interactive diagram: https://gitdiagram.com/abo7adeed/omerta.ai
- Repository: https://github.com/abo7adeed/omerta.ai

## Overview

Omerta.ai is a financial-crime investigation and banking platform with customer and compliance web experiences. Customers use the portal to manage accounts and transfers; compliance staff monitor risk, investigate cases, and review evidence and reports. The README documents double-entry banking, risk controls, network analysis, support, and multi-agent forensics. The graph preserves those product branches and the sampled Agentic RAG internals; unsampled routes and services are represented only at supported directory-level granularity.

Main entry points: [`apps/api/main.py`](https://github.com/abo7adeed/omerta.ai/blob/main/apps/api/main.py) (FastAPI Gateway), [`apps/agentic_rag/nodes.py`](https://github.com/abo7adeed/omerta.ai/blob/main/apps/agentic_rag/nodes.py) (RAG Orchestration), [`infrastructure/database/models.py`](https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/database/models.py) (PostgreSQL), [`domain/services/transfer_service.py`](https://github.com/abo7adeed/omerta.ai/blob/main/domain/services/transfer_service.py) (Transfers and Ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Customer and Staff Apps"]
  node_customer["Customer Portal<br/>[SendMoneyPage.tsx]"]
  node_staff["Compliance Console<br/>[App.tsx]"]
end

subgraph group_gateway["API and Identity"]
  node_api["FastAPI Gateway<br/>[main.py]"]
  node_auth["JWT Identity<br/>[jwt_auth.py]"]
end

subgraph group_banking["Banking and Risk"]
  node_transfers["Transfers and Ledger"]
  node_risk["Risk Assessment<br/>[ml_provider.py]"]
  node_banking_services["Banking Services"]
end

subgraph group_forensics["Investigation and RAG"]
  node_investigation["Investigation Workflow"]
  node_specialists["Specialist Agents"]
  node_scoring["Investigation Scoring<br/>[scoring.py]"]
  node_rag_api["RAG API<br/>[agentic_rag.py]"]
  node_rag_graph["RAG Graph<br/>[graph.py]"]
  node_rag_nodes["RAG Orchestration<br/>[nodes.py]"]
  node_rag_memory["Conversation Memory<br/>[memory.py]"]
  node_rag_tools["RAG Data Tools<br/>[database_tools.py]"]
  node_rag_graph_tools["Graph Tools<br/>[graph_tools.py]"]
  node_rag_visuals["Evidence Visualization<br/>[visualization.py]"]
  node_ingestion["Document Ingestion<br/>[ingest.py]"]
end

subgraph group_data["Persistence and Integrations"]
  node_postgres[("PostgreSQL<br/>[models.py]")]
  node_neo4j[("Neo4j Graph<br/>[client.py]")]
  node_mcp["MCP Tool Servers<br/>[server.py]"]
end

node_customer_actor(("Customer"))
node_staff_actor(("Compliance Staff"))
node_llm["LLM Provider"]

node_customer_actor -->|"uses"| node_customer
node_staff_actor -->|"uses"| node_staff
node_customer -->|"requests"| node_api
node_staff -->|"requests"| node_api
node_api -->|"enforces identity"| node_auth
node_api -->|"handles transfers"| node_transfers
node_api -->|"routes banking operations"| node_banking_services
node_transfers -->|"evaluates risk"| node_risk
node_transfers -->|"records ledger"| node_postgres
node_api -->|"runs investigations"| node_investigation
node_investigation -->|"uses specialists"| node_specialists
node_specialists -->|"applies scoring"| node_scoring
node_api -->|"serves RAG"| node_rag_api
node_rag_api -->|"invokes graph"| node_rag_graph
node_rag_graph -->|"dispatches nodes"| node_rag_nodes
node_rag_nodes -->|"queries records"| node_rag_tools
node_rag_nodes -->|"uses memory"| node_rag_memory
node_rag_nodes -->|"queries graph"| node_rag_graph_tools
node_rag_nodes -->|"renders evidence"| node_rag_visuals
node_rag_nodes -->|"uses knowledge corpus"| node_ingestion
node_rag_tools -->|"reads records"| node_postgres
node_rag_graph_tools -->|"queries graph"| node_neo4j
node_ingestion -->|"stores indexed chunks"| node_postgres
node_mcp -.->|"serves banking tools"| node_postgres
node_mcp -.->|"serves graph tools"| node_neo4j
node_investigation -.->|"uses model"| node_llm
node_rag_nodes -.->|"uses model"| node_llm
node_api -->|"persists results"| node_postgres

click node_customer "https://github.com/abo7adeed/omerta.ai/blob/main/frontend/src/pages/customer/SendMoneyPage.tsx"
click node_staff "https://github.com/abo7adeed/omerta.ai/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/abo7adeed/omerta.ai/blob/main/apps/api/main.py"
click node_auth "https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/security/jwt_auth.py"
click node_transfers "https://github.com/abo7adeed/omerta.ai/blob/main/domain/services/transfer_service.py"
click node_risk "https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/risk/ml_provider.py"
click node_banking_services "https://github.com/abo7adeed/omerta.ai/tree/main/domain/services"
click node_investigation "https://github.com/abo7adeed/omerta.ai/blob/main/apps/investigator/account_workflow.py"
click node_specialists "https://github.com/abo7adeed/omerta.ai/blob/main/domain/investigation/specialist_agents.py"
click node_scoring "https://github.com/abo7adeed/omerta.ai/blob/main/domain/investigation/scoring.py"
click node_rag_api "https://github.com/abo7adeed/omerta.ai/blob/main/apps/api/v1/agentic_rag.py"
click node_rag_graph "https://github.com/abo7adeed/omerta.ai/blob/main/apps/agentic_rag/graph.py"
click node_rag_nodes "https://github.com/abo7adeed/omerta.ai/blob/main/apps/agentic_rag/nodes.py"
click node_rag_memory "https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/memory.py"
click node_rag_tools "https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/tools/database_tools.py"
click node_rag_graph_tools "https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/tools/graph_tools.py"
click node_rag_visuals "https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/visualization.py"
click node_ingestion "https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/knowledge/ingest.py"
click node_postgres "https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/database/models.py"
click node_neo4j "https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/neo4j/client.py"
click node_mcp "https://github.com/abo7adeed/omerta.ai/blob/main/mcp_servers/graph_server/server.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_customer,node_staff toneBlue
class node_api,node_auth toneAmber
class node_transfers,node_risk,node_banking_services toneMint
class node_investigation,node_specialists,node_scoring,node_rag_api,node_rag_graph,node_rag_nodes,node_rag_memory,node_rag_tools,node_rag_graph_tools,node_rag_visuals,node_ingestion toneRose
class node_postgres,node_neo4j,node_mcp,node_customer_actor,node_staff_actor,node_llm toneIndigo
```

## Components

### Customer and Staff Apps

- [Customer Portal](https://github.com/abo7adeed/omerta.ai/blob/main/frontend/src/pages/customer/SendMoneyPage.tsx): `frontend/src/pages/customer/SendMoneyPage.tsx`
- [Compliance Console](https://github.com/abo7adeed/omerta.ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### API and Identity

- [FastAPI Gateway](https://github.com/abo7adeed/omerta.ai/blob/main/apps/api/main.py): `apps/api/main.py`
- [JWT Identity](https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/security/jwt_auth.py): `infrastructure/security/jwt_auth.py`

### Banking and Risk

- [Transfers and Ledger](https://github.com/abo7adeed/omerta.ai/blob/main/domain/services/transfer_service.py): `domain/services/transfer_service.py`
- [Risk Assessment](https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/risk/ml_provider.py): `infrastructure/risk/ml_provider.py`
- [Banking Services](https://github.com/abo7adeed/omerta.ai/tree/main/domain/services): `domain/services`

### Investigation and RAG

- [Investigation Workflow](https://github.com/abo7adeed/omerta.ai/blob/main/apps/investigator/account_workflow.py): `apps/investigator/account_workflow.py`
- [Specialist Agents](https://github.com/abo7adeed/omerta.ai/blob/main/domain/investigation/specialist_agents.py): `domain/investigation/specialist_agents.py`
- [Investigation Scoring](https://github.com/abo7adeed/omerta.ai/blob/main/domain/investigation/scoring.py): `domain/investigation/scoring.py`
- [RAG API](https://github.com/abo7adeed/omerta.ai/blob/main/apps/api/v1/agentic_rag.py): `apps/api/v1/agentic_rag.py`
- [RAG Graph](https://github.com/abo7adeed/omerta.ai/blob/main/apps/agentic_rag/graph.py): `apps/agentic_rag/graph.py`
- [RAG Orchestration](https://github.com/abo7adeed/omerta.ai/blob/main/apps/agentic_rag/nodes.py): `apps/agentic_rag/nodes.py`
- [Conversation Memory](https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/memory.py): `domain/agentic_rag/memory.py`
- [RAG Data Tools](https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/tools/database_tools.py): `domain/agentic_rag/tools/database_tools.py`
- [Graph Tools](https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/tools/graph_tools.py): `domain/agentic_rag/tools/graph_tools.py`
- [Evidence Visualization](https://github.com/abo7adeed/omerta.ai/blob/main/domain/agentic_rag/visualization.py): `domain/agentic_rag/visualization.py`
- [Document Ingestion](https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/knowledge/ingest.py): `infrastructure/knowledge/ingest.py`

### Persistence and Integrations

- [PostgreSQL](https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/database/models.py): `infrastructure/database/models.py`
- [Neo4j Graph](https://github.com/abo7adeed/omerta.ai/blob/main/infrastructure/neo4j/client.py): `infrastructure/neo4j/client.py`
- [MCP Tool Servers](https://github.com/abo7adeed/omerta.ai/blob/main/mcp_servers/graph_server/server.py): `mcp_servers/graph_server/server.py`

### Other components

- **Customer**
- **Compliance Staff**
- **LLM Provider**

## Connections

- Customer → Customer Portal: uses
- Compliance Staff → Compliance Console: uses
- Customer Portal → FastAPI Gateway: requests
- Compliance Console → FastAPI Gateway: requests
- FastAPI Gateway → JWT Identity: enforces identity (evidence: `apps/api/main.py`)
- FastAPI Gateway → Transfers and Ledger: handles transfers
- FastAPI Gateway → Banking Services: routes banking operations (evidence: `apps/api/main.py`)
- Transfers and Ledger → Risk Assessment: evaluates risk (evidence: `domain/services/transfer_service.py`)
- Transfers and Ledger → PostgreSQL: records ledger (evidence: `domain/services/transfer_service.py`)
- FastAPI Gateway → Investigation Workflow: runs investigations (evidence: `apps/api/main.py`)
- Investigation Workflow → Specialist Agents: uses specialists (evidence: `apps/investigator/account_workflow.py`)
- Specialist Agents → Investigation Scoring: applies scoring (evidence: `domain/investigation/specialist_agents.py`)
- FastAPI Gateway → RAG API: serves RAG (evidence: `apps/api/main.py`)
- RAG API → RAG Graph: invokes graph (evidence: `apps/api/v1/agentic_rag.py`)
- RAG Graph → RAG Orchestration: dispatches nodes (evidence: `apps/agentic_rag/graph.py`)
- RAG Orchestration → RAG Data Tools: queries records (evidence: `apps/agentic_rag/nodes.py`)
- RAG Orchestration → Conversation Memory: uses memory (evidence: `apps/agentic_rag/nodes.py`)
- RAG Orchestration → Graph Tools: queries graph (evidence: `apps/agentic_rag/nodes.py`)
- RAG Orchestration → Evidence Visualization: renders evidence (evidence: `apps/agentic_rag/nodes.py`)
- RAG Orchestration → Document Ingestion: uses knowledge corpus (evidence: `apps/agentic_rag/nodes.py`)
- RAG Data Tools → PostgreSQL: reads records (evidence: `domain/agentic_rag/tools/database_tools.py`)
- Graph Tools → Neo4j Graph: queries graph (evidence: `domain/agentic_rag/tools/graph_tools.py`)
- Document Ingestion → PostgreSQL: stores indexed chunks (evidence: `infrastructure/knowledge/ingest.py`)
- MCP Tool Servers → PostgreSQL: serves banking tools
- MCP Tool Servers → Neo4j Graph: serves graph tools
- Investigation Workflow → LLM Provider: uses model (evidence: `apps/investigator/account_workflow.py`)
- RAG Orchestration → LLM Provider: uses model (evidence: `apps/agentic_rag/nodes.py`)
- FastAPI Gateway → PostgreSQL: persists results (evidence: `apps/api/main.py`)
