# akshay-malolan/glitchcon architecture

> Architecture diagram of the GitHub repository akshay-malolan/glitchcon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshay-malolan/glitchcon
- Repository: https://github.com/akshay-malolan/glitchcon

## Overview

##### Project Type and Purpose
- This is a full-stack malware-scanning application combining:
- A Python-based backend API (ai-malware-scanner/api)
- A React/Vite/Tailwind frontend (ai-malware-scanner/frontend/site)
- A CLI tool (scanner/full_scan.py)
- Static analysis (static_analysis) + dynamic analysis (dynamic_analysis) + a deep-learning model (models)
- Optional integrations: VirusTotal threat intel, Cuckoo sandbox

##### File Structure Analysis
- Top-level:
- api/ – Python web server (app.py, server.py) exposing REST endpoints
- frontend/site/ – Static React/Vite site with TSX components, context, hooks
- static_analysis/ & dynamic_analysis/ – Core scanning modules
- scanner/ – CLI entrypoint for full system or file/directory scans
- models/ – Pretrained model files and loader (cloud_model.py)
- utils/ – Helpers (alerts, threat_intel)
- scripts/train_model.py – ML training pipeline
- logs/ – Centralized logging
- requirements.txt, .env configuration for API keys

##### Key README Insights
- Workflow: user uploads file via UI or invokes CLI → API server orchestrates scan → static features extracted (LIEF) → ML model (PyTorch) classifies → suspicious samples optionally sent to sandbox (Cuckoo) → queries VirusTotal → aggregates results → JSON report returned.
- No traditional database; persistence via logs and JSON outputs.

a. Main Components
- Client Layer:
- Web UI (React/Vite)
- CLI Tool (scanner.full_scan)
- API Layer: Python server (Flask/FastAPI style in app.py/server.py)
- Core Services:
- StaticAnalysis Module (extract PE features)
- MLModel Service (load/classify via cloud_model.py + .keras/.pt)
- DynamicAnalysis Module (sandbox.py, realtime_monitor.py)
- ThreatIntel Service (VirusTotal API via utils/threat_intel.py)
- Alerts/Reporting (utils/alerts.py → JSON outputs, logging)
- Infrastructure & External Services:
- Cuckoo Sandbox (optional)
- VirusTotal API
- Logging subsystem (logs/ai_malware_scanner.log)
- Training Pipeline (scripts/train_model.py → models/)

b. Relationships & Data Flow
1. Client (UI or CLI) → HTTP/REST or direct Python call → API Server
2. API Server → invokes StaticAnalysis → raw features
3. API Server → passes features to MLModel (inference) → classification result
4. If flagged or on demand → API Server → DynamicAnalysis → sandbox tracing
5. API Server → queries ThreatIntel → enriches result
6. API Server → logs events → returns JSON response to Client
7. Separate: Training Script → trains new model → writes to models/

c. Architectural Patterns & Principles
- Modular monolith with clear separation:
- Presentation (React) vs Business Logic (API) vs Domain Services (analysis/model)
- Single-responsibility modules: each analysis step in its own folder
- Pluggable components: optional sandbox, threat-intel, deep scan vs fast scan
- Concurrency: multithreaded scanning (scanner.full_scan)

d. Key Technologies & Frameworks
- Backend: Python 3.8+, Flask/FastAPI style, LIEF, psutil, python-magic
- ML: PyTorch (classic_mlp.pt/.keras)
- Frontend: React, TypeScript, Vite, Tailwind CSS
- External: VirusTotal REST API, Cuckoo sandbox

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        UI["Web UI"]:::client
        CLI["CLI Tool"]:::client
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        API["API Server"]:::service

        subgraph "Core Services"
            direction TB
            subgraph "Static Analysis Service"
                direction TB
                SA1["analyze.py"]:::service
                SA2["entropy.py"]:::service
            end
            subgraph "MLModel Service"
                direction TB
                ML1["cloud_model.py"]:::service
                ML2["classic_mlp.pt"]:::service
                ML3["classic_mlp.keras"]:::service
            end
            subgraph "Dynamic Analysis Service"
                direction TB
                DA1["realtime_monitor.py"]:::service
                DA2["sandbox.py"]:::service
            end
            ThreatIntel["threat_intel.py"]:::service
            Alerts["alerts.py"]:::service
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        VT["VirusTotal API"]:::external
        Cuckoo["Cuckoo Sandbox"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure & Config"
        direction TB
        Logs["ai_malware_scanner.log"]:::infra
        Config["requirements.txt"]:::infra
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        Train["train_model.py"]:::service
        ModelsDir["models/"]:::service
    end

    %% Connections
    UI -->|HTTP/REST| API
    CLI -->|direct call| API

    API -->|invoke| SA1
    API -->|invoke| SA2

    API -->|inference| ML1
    ML1 -->|loads artifact| ML2
    ML1 -->|loads artifact| ML3

    API -->|on demand| DA1
    API -->|on demand| DA2

    API -->|query| ThreatIntel
    API -->|alert/report| Alerts

    API -->|log events| Logs
    API -->|uses| Config

    API -->|response| UI
    API -->|response| CLI

    Train -->|writes new model| ModelsDir

    ThreatIntel -->|HTTP| VT
    DA2 -->|sandbox call| Cuckoo

    %% Click Events
    click UI "https://github.com/akshay-malolan/glitchcon/tree/main/ai-malware-scanner/frontend/site"
    click CLI "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/scanner/full_scan.py"
    click API "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/api/app.py"
    click API "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/api/server.py"
    click SA1 "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/static_analysis/analyze.py"
    click SA2 "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/static_analysis/entropy.py"
    click DA1 "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/dynamic_analysis/realtime_monitor.py"
    click DA2 "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/dynamic_analysis/sandbox.py"
    click ML1 "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/models/cloud_model.py"
    click ML2 "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/models/classic_mlp.pt"
    click ML3 "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/models/classic_mlp.keras"
    click ThreatIntel "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/utils/threat_intel.py"
    click Alerts "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/utils/alerts.py"
    click Train "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/scripts/train_model.py"
    click Logs "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/logs/ai_malware_scanner.log"
    click Config "https://github.com/akshay-malolan/glitchcon/blob/main/ai-malware-scanner/requirements.txt"

    %% Styles
    classDef client fill:#cce5ff,stroke:#4da3ff,color:#004085
    classDef service fill:#d4edda,stroke:#28a745,color:#155724
    classDef external fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#383d41
```
