# mustafamerchant21/anomalyiq architecture

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

- Interactive diagram: https://gitdiagram.com/mustafamerchant21/anomalyiq
- Repository: https://github.com/mustafamerchant21/anomalyiq

## Overview

#### Purpose and Entry Points
AnomalyIQ is a full-stack fraud/anomaly intelligence demo that combines ML, deterministic rules, relationship-graph analysis, and explanations into investigation workflows. The backend API starts in `backend/main.py`; the browser application is served from `frontend/index.html` and initialized through `frontend/js/app.js`.

#### Backend Orchestration Pipeline
`backend/pipeline.py` is the likely coordination boundary for turning uploaded or submitted records into scored results. It composes preprocessing, model/signal stages, aggregation, and explanations rather than exposing those concerns directly to the UI. API request/response and lifecycle concerns belong in `backend/main.py`.

#### Data Preparation and Signal Generation
Input normalization and feature preparation are separated in `backend/preprocessor.py`, providing a boundary between variable source datasets and downstream detection logic. ML-oriented anomaly detection is supported by the Python stack declared in `backend/requirements.txt`, including scikit-learn and TensorFlow per the project description. Demo data can be generated through `backend/demo_generator.py`.

#### Risk Decision Layer
`backend/rule_engine.py` produces interpretable rule-based fraud indicators, while `backend/risk_aggregator.py` combines rule, model, and graph-derived signals into an overall risk result. This separation is architecture-defining: individual detectors retain their own evidence, and aggregation creates the common score used by dashboards, prediction, and investigations.

#### Relationship and Investigation Analysis
`backend/graph_engine.py` handles account/transaction relationship analysis, including fraud-ring or cluster-oriented intelligence. NetworkX is a material runtime dependency for this stage. Its graph results are a separate evidence source feeding the aggregate risk and investigation-facing views.

#### Explainability and State
`backend/explainer.py` converts risk evidence into human-readable insights or narratives for analysts. `backend/session_manager.py` maintains session-scoped workflow state, allowing multi-step interactions such as upload, training/testing, prediction, and investigation without embedding UI state into detection engines.

#### Frontend Workflows and Visualization
The vanilla-JavaScript frontend calls backend APIs through `frontend/js/api.js`. Feature modules map to major analyst workflows: ingestion/training in `frontend/js/upload.js`, scoring in `frontend/js/predictor.js`, scenario analysis in `frontend/js/simulator.js`, and case exploration in `frontend/js/investigation.js`. Dashboard and audit presentations reside in `frontend/js/dashboard.js` and `frontend/js/audit.js`; Chart.js supports charts and Three.js supports graph/3D visualization such as `frontend/js/globe.js`.

#### Runtime Boundaries
The application has a Python/FastAPI service boundary (`backend/main.py`) and a static browser-client boundary (`frontend/index.html`). No persistent database, message broker, cloud deployment target, or third-party operational service is represented in the supplied tree. Client-side PDF/report capability is indicated by jsPDF in the README; detection and graph computation execute in the backend Python runtime.

Main entry points: [`frontend/js/app.js`](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/app.js) (Client Bootstrap), [`backend/main.py`](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/main.py) (FastAPI Service), [`backend/preprocessor.py`](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/preprocessor.py) (Preprocessor), [`backend/pipeline.py`](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/pipeline.py) (Analysis Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_web["Static Web App<br/>browser entry<br/>[index.html]"]
  node_app["Client Bootstrap<br/>JavaScript app<br/>[app.js]"]
  node_client_api["API Client<br/>HTTP client<br/>[api.js]"]
  node_upload["Ingestion &amp; Training<br/>workflow module<br/>[upload.js]"]
  node_predictor["Scoring<br/>workflow module<br/>[predictor.js]"]
  node_simulator["Scenario Analysis<br/>workflow module<br/>[simulator.js]"]
  node_investigation["Case Exploration<br/>workflow module<br/>[investigation.js]"]
  node_dashboard["Dashboard &amp; Audit<br/>presentation modules<br/>[dashboard.js]"]
  node_globe["Graph Visualization<br/>Three.js visualization<br/>[globe.js]"]
end

subgraph group_api["Python API"]
  node_main{{"FastAPI Service<br/>API entry point<br/>[main.py]"}}
  node_sessions["Session Manager<br/>workflow state<br/>[session_manager.py]"]
end

subgraph group_analysis["Risk Analysis Pipeline"]
  node_pipeline{{"Analysis Pipeline<br/>orchestrator<br/>[pipeline.py]"}}
  node_preprocessor["Preprocessor<br/>data preparation<br/>[preprocessor.py]"]
  node_ml["ML Anomaly Detection<br/>model signals<br/>[requirements.txt]"]
  node_rules["Rule Engine<br/>interpretable signals<br/>[rule_engine.py]"]
  node_graph["Relationship Analysis<br/>graph signals<br/>[graph_engine.py]"]
  node_risk["Risk Aggregator<br/>decision layer<br/>[risk_aggregator.py]"]
  node_explainer["Explainer<br/>analyst insights<br/>[explainer.py]"]
  node_demo["Demo Data Generator<br/>sample data source<br/>[demo_generator.py]"]
end

node_web -->|"loads"| node_app
node_app -->|"initializes"| node_client_api
node_app -->|"hosts"| node_upload
node_app -->|"hosts"| node_predictor
node_app -->|"hosts"| node_simulator
node_app -->|"hosts"| node_investigation
node_app -->|"hosts"| node_dashboard
node_investigation -->|"visualizes relationships"| node_globe
node_client_api -->|"HTTP API calls"| node_main
node_main -->|"manages workflow state"| node_sessions
node_main -->|"submits records"| node_pipeline
node_demo -.->|"supplies sample records"| node_pipeline
node_pipeline -->|"prepares input"| node_preprocessor
node_preprocessor -->|"features"| node_ml
node_preprocessor -->|"normalized records"| node_rules
node_preprocessor -->|"relationship data"| node_graph
node_ml -->|"anomaly evidence"| node_risk
node_rules -->|"rule evidence"| node_risk
node_graph -->|"graph evidence"| node_risk
node_risk -->|"risk evidence"| node_explainer
node_pipeline -->|"scores and explanations"| node_main
node_main -->|"workflow results"| node_client_api

click node_web "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/index.html"
click node_app "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/app.js"
click node_client_api "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/api.js"
click node_upload "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/upload.js"
click node_predictor "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/predictor.js"
click node_simulator "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/simulator.js"
click node_investigation "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/investigation.js"
click node_dashboard "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/dashboard.js"
click node_globe "https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/globe.js"
click node_main "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/main.py"
click node_sessions "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/session_manager.py"
click node_pipeline "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/pipeline.py"
click node_preprocessor "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/preprocessor.py"
click node_ml "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/requirements.txt"
click node_rules "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/rule_engine.py"
click node_graph "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/graph_engine.py"
click node_risk "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/risk_aggregator.py"
click node_explainer "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/explainer.py"
click node_demo "https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/demo_generator.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_app,node_client_api,node_upload,node_predictor,node_simulator,node_investigation,node_dashboard,node_globe toneBlue
class node_main,node_sessions toneAmber
class node_pipeline,node_preprocessor,node_ml,node_rules,node_graph,node_risk,node_explainer,node_demo toneMint
```

## Components

### Browser Client

Static analyst application and workflow modules.

- [Static Web App](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/index.html): browser entry · `frontend/index.html`
- [Client Bootstrap](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/app.js): JavaScript app · `frontend/js/app.js`
- [API Client](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/api.js): HTTP client · `frontend/js/api.js`
- [Ingestion & Training](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/upload.js): workflow module · `frontend/js/upload.js`
- [Scoring](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/predictor.js): workflow module · `frontend/js/predictor.js`
- [Scenario Analysis](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/simulator.js): workflow module · `frontend/js/simulator.js`
- [Case Exploration](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/investigation.js): workflow module · `frontend/js/investigation.js`
- [Dashboard & Audit](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/dashboard.js): presentation modules · `frontend/js/dashboard.js`
- [Graph Visualization](https://github.com/mustafamerchant21/anomalyiq/blob/main/frontend/js/globe.js): Three.js visualization · `frontend/js/globe.js`

### Python API

FastAPI entry point and session workflow boundary.

- [FastAPI Service](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/main.py): API entry point · Owns API lifecycle and request/response handling. · `backend/main.py`
- [Session Manager](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/session_manager.py): workflow state · Maintains state across analyst workflow steps. · `backend/session_manager.py`

### Risk Analysis Pipeline

Backend preparation, evidence generation, and decision stages.

- [Analysis Pipeline](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/pipeline.py): orchestrator · Coordinates preparation, evidence stages, risk, and explanations. · `backend/pipeline.py`
- [Preprocessor](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/preprocessor.py): data preparation · `backend/preprocessor.py`
- [ML Anomaly Detection](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/requirements.txt): model signals · Uses the scikit-learn and TensorFlow backend stack. · `backend/requirements.txt`
- [Rule Engine](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/rule_engine.py): interpretable signals · `backend/rule_engine.py`
- [Relationship Analysis](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/graph_engine.py): graph signals · Finds relationship clusters and fraud-ring evidence using NetworkX. · `backend/graph_engine.py`
- [Risk Aggregator](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/risk_aggregator.py): decision layer · Combines detector evidence into the shared risk result. · `backend/risk_aggregator.py`
- [Explainer](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/explainer.py): analyst insights · `backend/explainer.py`
- [Demo Data Generator](https://github.com/mustafamerchant21/anomalyiq/blob/main/backend/demo_generator.py): sample data source · `backend/demo_generator.py`

## Connections

- Static Web App → Client Bootstrap: loads
- Client Bootstrap → API Client: initializes
- Client Bootstrap → Ingestion & Training: hosts
- Client Bootstrap → Scoring: hosts
- Client Bootstrap → Scenario Analysis: hosts
- Client Bootstrap → Case Exploration: hosts
- Client Bootstrap → Dashboard & Audit: hosts
- Case Exploration → Graph Visualization: visualizes relationships
- API Client → FastAPI Service: HTTP API calls
- FastAPI Service → Session Manager: manages workflow state
- FastAPI Service → Analysis Pipeline: submits records
- Demo Data Generator → Analysis Pipeline: supplies sample records
- Analysis Pipeline → Preprocessor: prepares input
- Preprocessor → ML Anomaly Detection: features
- Preprocessor → Rule Engine: normalized records
- Preprocessor → Relationship Analysis: relationship data
- ML Anomaly Detection → Risk Aggregator: anomaly evidence
- Rule Engine → Risk Aggregator: rule evidence
- Relationship Analysis → Risk Aggregator: graph evidence
- Risk Aggregator → Explainer: risk evidence
- Analysis Pipeline → FastAPI Service: scores and explanations
- FastAPI Service → API Client: workflow results