mustafamerchant21/anomalyiq

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.