# gokul-cybersec/ai_malware_analyser architecture

> Architecture diagram of the GitHub repository gokul-cybersec/ai_malware_analyser, 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/gokul-cybersec/ai_malware_analyser
- Repository: https://github.com/gokul-cybersec/ai_malware_analyser

## Overview

AI Malware Analyzer accepts suspicious files, validates and hashes them, then processes them asynchronously through static analysis, feature extraction, ML classification, threat-intelligence enrichment, and report generation. Results and sample metadata are persisted for API retrieval and displayed in a Next.js SOC dashboard. The README documents the Redis/Celery processing architecture and major analysis capabilities; some subsystem wiring is only documented, so those links are marked accordingly.

Main entry points: [`backend/app/api/routes.py`](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/api/routes.py) (API Routes), [`backend/app/tasks.py`](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/tasks.py) (Analysis Pipeline), [`backend/app/worker.py`](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/worker.py) (Celery Task), [`frontend/src/lib/api.ts`](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/frontend/src/lib/api.ts) (Frontend API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Analysis Dashboard<br/>[page.tsx]"]
  node_analysis_view["Sample Details<br/>[page.tsx]"]
  node_api_client["Frontend API Client<br/>[api.ts]"]
end

subgraph group_api["API and Intake"]
  node_api_server["FastAPI App<br/>[main.py]"]
  node_routes["API Routes<br/>[routes.py]"]
  node_validation["File Validation<br/>[validator.py]"]
  node_hashing["File Hashing<br/>[hasher.py]"]
end

subgraph group_analysis["Analysis Pipeline"]
  node_pipeline["Analysis Pipeline<br/>[tasks.py]"]
  node_static["Static PE Analysis<br/>[static_analyzer.py]"]
  node_features["Feature Extraction"]
  node_classifier["ML Classification<br/>[predict.py]"]
  node_training["Model Training<br/>[train.py]"]
  node_vt["VirusTotal Enrichment<br/>[vt_client.py]"]
  node_report["AI Report Generation"]
  node_sandbox["Sandbox Interface"]
end

subgraph group_infra["Persistence and Workers"]
  node_queue["Redis Broker"]
  node_celery["Celery Task<br/>[worker.py]"]
  node_db[("Analysis Database<br/>[database.py]")]
end

node_analyst(("Security Analyst"))
node_vt_service["VirusTotal"]
node_gemini["Gemini LLM"]

node_analyst -->|"uploads sample"| node_dashboard
node_dashboard -.->|"requests data"| node_api_client
node_analysis_view -.->|"requests details"| node_api_client
node_api_client -->|"calls API"| node_api_server
node_api_server -->|"registers routes"| node_routes
node_routes -->|"validates upload"| node_validation
node_routes -->|"hashes upload"| node_hashing
node_routes -->|"stores sample"| node_db
node_routes -->|"dispatches task"| node_celery
node_celery -->|"uses broker"| node_queue
node_queue -->|"delivers task"| node_celery
node_celery -->|"runs pipeline"| node_pipeline
node_pipeline -->|"analyzes file"| node_static
node_pipeline -->|"extracts features"| node_features
node_pipeline -->|"classifies sample"| node_classifier
node_classifier -->|"loads model from"| node_training
node_pipeline -->|"enriches analysis"| node_vt
node_vt -->|"queries"| node_vt_service
node_pipeline -->|"generates report"| node_report
node_report -.->|"may delegate"| node_gemini
node_pipeline -->|"persists results"| node_db
node_routes -->|"runs sandbox analysis"| node_sandbox
node_routes -->|"reads sample and reports"| node_db
node_analyst -->|"views findings"| node_analysis_view

click node_dashboard "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/frontend/src/app/page.tsx"
click node_analysis_view "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/frontend/src/app/analysis/%5Bid%5D/page.tsx"
click node_api_client "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/frontend/src/lib/api.ts"
click node_api_server "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/main.py"
click node_routes "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/api/routes.py"
click node_validation "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/validator.py"
click node_hashing "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/hasher.py"
click node_celery "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/worker.py"
click node_pipeline "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/tasks.py"
click node_static "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/analysis/static_analyzer.py"
click node_features "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/analysis/feature_extractor.py"
click node_classifier "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/ml/predict.py"
click node_training "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/ml/train.py"
click node_vt "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/vt_client.py"
click node_report "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/report_generator.py"
click node_sandbox "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/sandbox/sandbox_controller.py"
click node_db "https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/models/database.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_dashboard,node_analysis_view,node_api_client toneBlue
class node_api_server,node_routes,node_validation,node_hashing toneAmber
class node_pipeline,node_static,node_features,node_classifier,node_training,node_vt,node_report,node_sandbox toneMint
class node_queue,node_celery,node_db toneRose
class node_analyst,node_vt_service,node_gemini toneIndigo
```

## Components

### Dashboard

- [Analysis Dashboard](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Sample Details](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/frontend/src/app/analysis/%5Bid%5D/page.tsx): `frontend/src/app/analysis/[id]/page.tsx`
- [Frontend API Client](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and Intake

- [FastAPI App](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/main.py): `backend/app/main.py`
- [API Routes](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [File Validation](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/validator.py): `backend/app/services/validator.py`
- [File Hashing](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/hasher.py): `backend/app/services/hasher.py`

### Analysis Pipeline

- [Analysis Pipeline](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/tasks.py): `backend/app/tasks.py`
- [Static PE Analysis](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/analysis/static_analyzer.py): `backend/app/analysis/static_analyzer.py`
- [Feature Extraction](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/analysis/feature_extractor.py): `backend/app/analysis/feature_extractor.py`
- [ML Classification](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/ml/predict.py): `backend/app/ml/predict.py`
- [Model Training](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/ml/train.py): `backend/app/ml/train.py`
- [VirusTotal Enrichment](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/vt_client.py): `backend/app/services/vt_client.py`
- [AI Report Generation](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/services/report_generator.py): `backend/app/services/report_generator.py`
- [Sandbox Interface](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/sandbox/sandbox_controller.py): `backend/app/sandbox/sandbox_controller.py`

### Persistence and Workers

- **Redis Broker**
- [Celery Task](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/worker.py): `backend/app/worker.py`
- [Analysis Database](https://github.com/gokul-cybersec/ai_malware_analyser/blob/main/backend/app/models/database.py): `backend/app/models/database.py`

### Other components

- **Security Analyst**
- **VirusTotal**
- **Gemini LLM**

## Connections

- Security Analyst → Analysis Dashboard: uploads sample
- Analysis Dashboard → Frontend API Client: requests data
- Sample Details → Frontend API Client: requests details
- Frontend API Client → FastAPI App: calls API
- FastAPI App → API Routes: registers routes (evidence: `backend/app/main.py`)
- API Routes → File Validation: validates upload (evidence: `backend/app/api/routes.py`)
- API Routes → File Hashing: hashes upload (evidence: `backend/app/api/routes.py`)
- API Routes → Analysis Database: stores sample (evidence: `backend/app/api/routes.py`)
- API Routes → Celery Task: dispatches task (evidence: `backend/app/api/routes.py`)
- Celery Task → Redis Broker: uses broker
- Redis Broker → Celery Task: delivers task
- Celery Task → Analysis Pipeline: runs pipeline (evidence: `backend/app/worker.py`)
- Analysis Pipeline → Static PE Analysis: analyzes file (evidence: `backend/app/tasks.py`)
- Analysis Pipeline → Feature Extraction: extracts features (evidence: `backend/app/tasks.py`)
- Analysis Pipeline → ML Classification: classifies sample (evidence: `backend/app/tasks.py`)
- ML Classification → Model Training: loads model from (evidence: `backend/app/ml/predict.py`)
- Analysis Pipeline → VirusTotal Enrichment: enriches analysis (evidence: `backend/app/tasks.py`)
- VirusTotal Enrichment → VirusTotal: queries (evidence: `backend/app/services/vt_client.py`)
- Analysis Pipeline → AI Report Generation: generates report (evidence: `backend/app/tasks.py`)
- AI Report Generation → Gemini LLM: may delegate
- Analysis Pipeline → Analysis Database: persists results (evidence: `backend/app/tasks.py`)
- API Routes → Sandbox Interface: runs sandbox analysis (evidence: `backend/app/api/routes.py`)
- API Routes → Analysis Database: reads sample and reports (evidence: `backend/app/api/routes.py`)
- Security Analyst → Sample Details: views findings
