# limseonghyeon/volatility3_ui architecture

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

- Interactive diagram: https://gitdiagram.com/limseonghyeon/volatility3_ui
- Repository: https://github.com/limseonghyeon/volatility3_ui

## Overview

##### Project Type and Purpose
- This is a single-repo, full-stack Python application using Streamlit to provide a web UI for Volatility3 memory forensics on Windows.
- The front-end (UI folder) handles user interactions, while the back-end (common folder + external Volatility3 CLI) executes forensic analysis asynchronously.

##### File Structure Analysis
- Top-level
- main.py: Streamlit entrypoint
- requirements.txt / fix_encoding.bat / .env (user-provided): environment & dependency config
- resources/: JSON config for plugins & welcome text
- UI/
- config.py: loads environment variables & JSON plugin files
- navbar.py, mainSection.py, components.py, async_components.py, explain.py: Streamlit UI widgets & layout
- common/
- async_manager.py: manages asyncio tasks & progress updates
- volatility.py (in README as volatility.py, named volatility.py in common): wraps calls to external Volatility3 CLI using subprocess
- cache_manager.py: caches intermediate results to avoid re-runs
- utils.py: shared helper functions (parsing, file I/O, CSV export)

##### Key Architecture Insights from README
- Asynchronous, non-blocking analysis with real-time progress updates
- Category-based plugin system (system info, process, network, malware, advanced, PID)
- Local file I/O for result dumps and CSV exports
- External dependency: Volatility3 CLI (configured via `VOL_PATH` in .env)

a. Main Components
1. Browser / Client: interacts with Streamlit front-end via HTTP/websocket
2. Streamlit Server (main.py)
3. UI Layer (UI/*.py)
4. Business Logic Layer (common/*.py)
5. Configuration Layer (resources/*.json, .env)
6. External Service: Volatility3 CLI (vol.py)
7. Local Storage: file system for dumps, CSV, cache
b. Relationships & Data Flow
1. User actions in browser → HTTP/WebSocket → Streamlit Server
2. UI Layer → calls async_manager to launch analysis tasks
3. async_manager → spawns subprocess to run Volatility3 CLI via volatility.py
4. Volatility3 → returns raw results → cache_manager stores parsed output → async_manager updates progress
5. Results → utils formats as tables/CSV → UI Layer updates UI in real time
6. On export → UI writes CSV/dump files to OUTPUT_PATH
c. Architectural Patterns & Principles
- Layered separation: Presentation (UI), Application (async manager + business logic), Infrastructure (file system, external CLI)
- Asynchronous/event-driven pattern for non-blocking analysis
- Plugin-based extensibility: JSON-driven categories for dynamic loading of commands
- Single process, modular Python package
d. Key Technologies
- Python 3.8+
- Streamlit 1.28+ for front-end
- asyncio & subprocess in async_manager & volatility.py
- JSON config files for plugin definitions
- Local FS I/O for caches, dumps, CSV exports

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Browser / Client"]:::presentation
        Streamlit["Streamlit Server\n(main.py)"]:::presentation
        UI_config["config.py"]:::presentation
        UI_nav["navbar.py"]:::presentation
        UI_main["mainSection.py"]:::presentation
        UI_comp["components.py"]:::presentation
        UI_async_comp["async_components.py"]:::presentation
        UI_explain["explain.py"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        AsyncManager["async_manager.py"]:::business
        CacheManager["cache_manager.py"]:::business
        VolWrapper["volatility.py"]:::business
        Utils["utils.py"]:::business
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Plugins1["plugins.json"]:::config
        Plugins2["pid_plugins.json"]:::config
        WelcomeMsg["welcome_message.md"]:::config
        Requirements["requirements.txt"]:::config
        FixEnc["fix_encoding.bat"]:::config
        Env[".env"]:::config
    end

    %% Infrastructure / External
    subgraph "Infrastructure / External"
        VolCLI["Volatility3 CLI"]:::infra
        FileSystem["Local File System"]:::infra
    end

    %% Data Flows
    Browser -->|"HTTP/WebSocket"| Streamlit
    Streamlit -->|"imports UI modules"| UI_config
    Streamlit --> UI_nav
    Streamlit --> UI_main
    Streamlit --> UI_comp
    Streamlit --> UI_async_comp
    Streamlit --> UI_explain
    UI_async_comp -->|"launch tasks"| AsyncManager
    AsyncManager -->|"subprocess call"| VolWrapper
    VolWrapper -->|"invoke CLI"| VolCLI
    VolCLI -->|"raw results"| VolWrapper
    VolWrapper -->|"return output"| AsyncManager
    AsyncManager -->|"cache data"| CacheManager
    CacheManager -->|"provide cached results"| AsyncManager
    AsyncManager -->|"format data"| Utils
    Utils -->|"formatted tables/CSV"| UI_main
    UI_main -->|"export CSV/dumps"| FileSystem

    %% Config flows
    Plugins1 --> UI_config
    Plugins2 --> UI_config
    WelcomeMsg --> UI_config
    Env --> UI_config
    Requirements --> Env
    FixEnc --> Env

    %% Click Events
    click Streamlit "https://github.com/limseonghyeon/volatility3_ui/blob/master/main.py"
    click UI_config "https://github.com/limseonghyeon/volatility3_ui/blob/master/UI/config.py"
    click UI_nav "https://github.com/limseonghyeon/volatility3_ui/blob/master/UI/navbar.py"
    click UI_main "https://github.com/limseonghyeon/volatility3_ui/blob/master/UI/mainSection.py"
    click UI_comp "https://github.com/limseonghyeon/volatility3_ui/blob/master/UI/components.py"
    click UI_async_comp "https://github.com/limseonghyeon/volatility3_ui/blob/master/UI/async_components.py"
    click UI_explain "https://github.com/limseonghyeon/volatility3_ui/blob/master/UI/explain.py"
    click AsyncManager "https://github.com/limseonghyeon/volatility3_ui/blob/master/common/async_manager.py"
    click CacheManager "https://github.com/limseonghyeon/volatility3_ui/blob/master/common/cache_manager.py"
    click VolWrapper "https://github.com/limseonghyeon/volatility3_ui/blob/master/common/volatility.py"
    click Utils "https://github.com/limseonghyeon/volatility3_ui/blob/master/common/utils.py"
    click Plugins1 "https://github.com/limseonghyeon/volatility3_ui/blob/master/resources/plugins.json"
    click Plugins2 "https://github.com/limseonghyeon/volatility3_ui/blob/master/resources/pid_plugins.json"
    click WelcomeMsg "https://github.com/limseonghyeon/volatility3_ui/blob/master/resources/welcome_message.md"
    click Requirements "https://github.com/limseonghyeon/volatility3_ui/blob/master/requirements.txt"
    click FixEnc "https://github.com/limseonghyeon/volatility3_ui/blob/master/fix_encoding.bat"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef business fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#F0E68C,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
```
