# sharone-12/mulenet architecture

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

- Interactive diagram: https://gitdiagram.com/sharone-12/mulenet
- Repository: https://github.com/sharone-12/mulenet

## Overview

MuleNet is an anti-money-laundering investigation application: analysts explore suspicious transaction rings, inspect their flows and account roles, and can use an AI assistant to investigate and draft SAR narratives. The UI talks to a FastAPI service; backend tools expose detection results and ring investigations. The excerpts document API delegation, tool behavior, and several UI relationships, but omit the detection engine, data-loading implementation, and most frontend API wiring, so those internal links are shown only where supported or marked unverified.

Main entry points: [`backend/main.py`](https://github.com/sharone-12/mulenet/blob/main/backend/main.py) (HTTP and WebSocket API), [`frontend/src/App.jsx`](https://github.com/sharone-12/mulenet/blob/main/frontend/src/App.jsx) (Application Shell), [`backend/mulenet/engine.py`](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/engine.py) (Detection Engine), [`backend/mulenet/tools.py`](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/tools.py) (Investigation Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Investigator UI"]
  node_app["Application Shell<br/>[App.jsx]"]
  node_chat["Chat Panel<br/>[ChatPanel.jsx]"]
  node_queue["Ring Queue<br/>[RingQueue.jsx]"]
  node_graphpanel["Network Graph<br/>[GraphPanel.jsx]"]
  node_inspector["Ring Inspector<br/>[RingInspector.jsx]"]
  node_topology["Ring Topology<br/>[RingTopology.jsx]"]
  node_timeline["Ring Timeline<br/>[RingTimeline.jsx]"]
  node_stats["Investigation Stats<br/>[StatCards.jsx]"]
  node_clientapi["Frontend API<br/>[api.js]"]
end

subgraph group_api["Service API"]
  node_service["HTTP and WebSocket API<br/>[main.py]"]
end

subgraph group_analysis["Detection Analysis"]
  node_engine["Detection Engine<br/>[engine.py]"]
  node_detectors["Ring Detectors<br/>[detectors.py]"]
  node_patterns["Pattern Library<br/>[patterns.py]"]
  node_ranker["Ring Ranker<br/>[ranker.py]"]
  node_scoring["Detection Scoring<br/>[scoring.py]"]
  node_graph["Transaction Graph<br/>[graph.py]"]
  node_rings["Ring Results<br/>[rings.py]"]
  node_rules["Threshold Baseline<br/>[rule_engine.py]"]
end

subgraph group_investigation["Investigation Tools"]
  node_tools["Investigation Tools<br/>[tools.py]"]
  node_agent["Chat Agent<br/>[agent.py]"]
  node_guard["Prompt Guard<br/>[guard.py]"]
  node_sar["SAR Generation<br/>[main.py]"]
  node_viz["Graph and Ring Views<br/>[viz.py]"]
end

subgraph group_support["Data and Models"]
  node_loader["Dataset Loader<br/>[loader.py]"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_keys["LLM Key Pool<br/>[keys.py]"]
end

node_analyst(("Analyst"))
node_groq["Groq LLM"]

node_analyst -->|"uses"| node_app
node_app -->|"loads bundle"| node_clientapi
node_app -->|"renders"| node_chat
node_app -->|"renders"| node_queue
node_app -->|"renders"| node_inspector
node_app -->|"renders"| node_graphpanel
node_app -->|"renders"| node_stats
node_inspector -->|"requests ring data"| node_service
node_inspector -->|"renders"| node_topology
node_inspector -->|"renders"| node_timeline
node_service -->|"delegates investigations"| node_tools
node_service -->|"loads engine"| node_engine
node_service -->|"requests views"| node_viz
node_service -->|"evaluates baseline"| node_rules
node_service -->|"runs chat"| node_agent
node_service -->|"investigates ring"| node_tools
node_service -->|"classifies roles"| node_tools
node_tools -->|"reads results"| node_engine
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"screens message"| node_guard
node_agent -->|"requests completion"| node_keys
node_keys -->|"calls model"| node_groq
node_service -->|"builds SAR context"| node_tools
node_service -.->|"writes SAR"| node_keys
node_engine -.->|"loads transactions"| node_loader
node_engine -.->|"uses transaction graph"| node_graph
node_engine -.->|"runs detection"| node_detectors
node_engine -.->|"ranks candidates"| node_ranker
node_engine -.->|"produces ring results"| node_rings
node_detectors -.->|"uses patterns"| node_patterns
node_rules -->|"loads data"| node_loader
node_scoring -.->|"scores labels"| node_loader
node_viz -.->|"renders ring data"| node_rings
node_service -->|"reads settings"| node_config

click node_app "https://github.com/sharone-12/mulenet/blob/main/frontend/src/App.jsx"
click node_chat "https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/ChatPanel.jsx"
click node_queue "https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingQueue.jsx"
click node_graphpanel "https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/GraphPanel.jsx"
click node_inspector "https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingInspector.jsx"
click node_topology "https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingTopology.jsx"
click node_timeline "https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingTimeline.jsx"
click node_stats "https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/StatCards.jsx"
click node_clientapi "https://github.com/sharone-12/mulenet/blob/main/frontend/src/api.js"
click node_service "https://github.com/sharone-12/mulenet/blob/main/backend/main.py"
click node_tools "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/tools.py"
click node_agent "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/agent.py"
click node_guard "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/guard.py"
click node_sar "https://github.com/sharone-12/mulenet/blob/main/backend/main.py"
click node_engine "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/engine.py"
click node_detectors "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/detectors.py"
click node_patterns "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/patterns.py"
click node_ranker "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/ranker.py"
click node_scoring "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/scoring.py"
click node_graph "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/graph.py"
click node_rings "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/rings.py"
click node_loader "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/loader.py"
click node_config "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/config.py"
click node_keys "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/keys.py"
click node_viz "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/viz.py"
click node_rules "https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/rule_engine.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_app,node_chat,node_queue,node_graphpanel,node_inspector,node_topology,node_timeline,node_stats,node_clientapi toneBlue
class node_service toneAmber
class node_engine,node_detectors,node_patterns,node_ranker,node_scoring,node_graph,node_rings,node_rules toneMint
class node_tools,node_agent,node_guard,node_sar,node_viz toneRose
class node_loader,node_config,node_keys,node_analyst,node_groq toneIndigo
```

## Components

### Investigator UI

- [Application Shell](https://github.com/sharone-12/mulenet/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat Panel](https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/ChatPanel.jsx): `frontend/src/components/ChatPanel.jsx`
- [Ring Queue](https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingQueue.jsx): `frontend/src/components/RingQueue.jsx`
- [Network Graph](https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/GraphPanel.jsx): `frontend/src/components/GraphPanel.jsx`
- [Ring Inspector](https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingInspector.jsx): `frontend/src/components/RingInspector.jsx`
- [Ring Topology](https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingTopology.jsx): `frontend/src/components/RingTopology.jsx`
- [Ring Timeline](https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/RingTimeline.jsx): `frontend/src/components/RingTimeline.jsx`
- [Investigation Stats](https://github.com/sharone-12/mulenet/blob/main/frontend/src/components/StatCards.jsx): `frontend/src/components/StatCards.jsx`
- [Frontend API](https://github.com/sharone-12/mulenet/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Service API

- [HTTP and WebSocket API](https://github.com/sharone-12/mulenet/blob/main/backend/main.py): `backend/main.py`

### Detection Analysis

- [Detection Engine](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/engine.py): `backend/mulenet/engine.py`
- [Ring Detectors](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/detectors.py): `backend/mulenet/detectors.py`
- [Pattern Library](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/patterns.py): `backend/mulenet/patterns.py`
- [Ring Ranker](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/ranker.py): `backend/mulenet/ranker.py`
- [Detection Scoring](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/scoring.py): `backend/mulenet/scoring.py`
- [Transaction Graph](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/graph.py): `backend/mulenet/graph.py`
- [Ring Results](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/rings.py): `backend/mulenet/rings.py`
- [Threshold Baseline](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/rule_engine.py): `backend/mulenet/rule_engine.py`

### Investigation Tools

- [Investigation Tools](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/tools.py): `backend/mulenet/tools.py`
- [Chat Agent](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/agent.py): `backend/mulenet/agent.py`
- [Prompt Guard](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/guard.py): `backend/mulenet/guard.py`
- [SAR Generation](https://github.com/sharone-12/mulenet/blob/main/backend/main.py): `backend/main.py`
- [Graph and Ring Views](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/viz.py): `backend/mulenet/viz.py`

### Data and Models

- [Dataset Loader](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/loader.py): `backend/mulenet/loader.py`
- [Runtime Configuration](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/config.py): `backend/mulenet/config.py`
- [LLM Key Pool](https://github.com/sharone-12/mulenet/blob/main/backend/mulenet/keys.py): `backend/mulenet/keys.py`

### Other components

- **Analyst**
- **Groq LLM**

## Connections

- Analyst → Application Shell: uses
- Application Shell → Frontend API: loads bundle (evidence: `frontend/src/App.jsx`)
- Application Shell → Chat Panel: renders (evidence: `frontend/src/App.jsx`)
- Application Shell → Ring Queue: renders (evidence: `frontend/src/App.jsx`)
- Application Shell → Ring Inspector: renders (evidence: `frontend/src/App.jsx`)
- Application Shell → Network Graph: renders (evidence: `frontend/src/App.jsx`)
- Application Shell → Investigation Stats: renders (evidence: `frontend/src/App.jsx`)
- Ring Inspector → HTTP and WebSocket API: requests ring data (evidence: `frontend/src/components/RingInspector.jsx`)
- Ring Inspector → Ring Topology: renders (evidence: `frontend/src/components/RingInspector.jsx`)
- Ring Inspector → Ring Timeline: renders (evidence: `frontend/src/components/RingInspector.jsx`)
- HTTP and WebSocket API → Investigation Tools: delegates investigations (evidence: `backend/main.py`)
- HTTP and WebSocket API → Detection Engine: loads engine (evidence: `backend/main.py`)
- HTTP and WebSocket API → Graph and Ring Views: requests views (evidence: `backend/main.py`)
- HTTP and WebSocket API → Threshold Baseline: evaluates baseline (evidence: `backend/main.py`)
- HTTP and WebSocket API → Chat Agent: runs chat (evidence: `backend/main.py`)
- HTTP and WebSocket API → Investigation Tools: investigates ring (evidence: `backend/main.py`)
- HTTP and WebSocket API → Investigation Tools: classifies roles (evidence: `backend/main.py`)
- Investigation Tools → Detection Engine: reads results (evidence: `backend/mulenet/tools.py`)
- Chat Agent → Investigation Tools: dispatches tools (evidence: `backend/mulenet/agent.py`)
- Chat Agent → Prompt Guard: screens message (evidence: `backend/mulenet/agent.py`)
- Chat Agent → LLM Key Pool: requests completion (evidence: `backend/mulenet/agent.py`)
- LLM Key Pool → Groq LLM: calls model (evidence: `backend/mulenet/keys.py`)
- HTTP and WebSocket API → Investigation Tools: builds SAR context (evidence: `backend/main.py`)
- HTTP and WebSocket API → LLM Key Pool: writes SAR (evidence: `backend/main.py`)
- Detection Engine → Dataset Loader: loads transactions
- Detection Engine → Transaction Graph: uses transaction graph
- Detection Engine → Ring Detectors: runs detection
- Detection Engine → Ring Ranker: ranks candidates
- Detection Engine → Ring Results: produces ring results
- Ring Detectors → Pattern Library: uses patterns
- Threshold Baseline → Dataset Loader: loads data (evidence: `backend/mulenet/rule_engine.py`)
- Detection Scoring → Dataset Loader: scores labels
- Graph and Ring Views → Ring Results: renders ring data
- HTTP and WebSocket API → Runtime Configuration: reads settings (evidence: `backend/main.py`)
