# sowieee/ids-web3 architecture

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

- Interactive diagram: https://gitdiagram.com/sowieee/ids-web3
- Repository: https://github.com/sowieee/ids-web3

## Overview

##### Project type and purpose
- This is a full-stack blockchain monitoring and visualization tool (named “IDS-WEB3”) built for a blockchain course project.
- It listens for specific system events (via Sysmon), hooks processes (via Frida), records or replays those events on an Ethereum smart contract, and renders the data in a web UI.

##### File structure
- Top‐level directories:
- backend/ – Python Flask application, event listeners, blockchain integration
- frontend/ – Vue 3 single-page application (Vite, Vuetify, Pinia)
- lib/, script/, test/, src/ – Foundry smart-contract toolkit, deployment scripts, contract code, and tests
- Configuration:
- foundry.toml – Foundry project settings
- backend/contract_abi.json – ABI for Python to interact with deployed contract
- backend/config.py, requirements.txt – Flask settings and dependencies
- CI:
- .github/workflows/test.yml – automated tests or linting pipeline
- Tooling:
- Sysmon (external) for low-level event monitoring
- Frida hooks (backend/frida_hook.py) to instrument apps at runtime
- backend/etw_listener.py for ETW event capture

##### README for additional insights
- Underlying tech: Foundry (Forge, Cast, Anvil) to compile, test, deploy smart contracts
- Python Flask for REST API or WebSocket endpoints
- Vue + Vite + Vuetify + Pinia for the web interface
- Sysmon must be running externally to feed the Python listeners

a. Main components
- Browser / Mobile Client
- Vue SPA (frontend)
- Flask API server (backend)
- ETW listener + Frida hook modules
- Blockchain adapter (Web3.py)
- Local Ethereum node (Anvil/Ganache)
- Smart contract (deployed on local node)
- External Sysmon agent
b. Relationships and data flows
1. User interacts with the SPA over HTTP/S or WebSocket.
2. SPA dispatches user actions to Flask API endpoints (e.g. fetch recorded events, trigger analysis).
3. Flask routes invoke:
– ETW listener (reads Sysmon event stream)
– Frida hook module (instruments target processes)
– Blockchain adapter (sends transactions or calls to the smart contract via JSON-RPC)
4. The local node (Anvil) processes transactions and emits events.
5. Flask processes these events, persists or forwards them back to the SPA.
c. Architectural patterns / design principles
- Layered architecture: presentation (Vue), application (Flask), infrastructure (Sysmon, blockchain)
- Event-driven flow: ETW → event handlers → blockchain transactions → UI updates
- Single codebase monolith on the backend, but separation of concerns by module
d. Key technologies
- Python Flask, Web3.py
- Sysmon (ETW) + Frida for low-level event capture
- Foundry (Forge/Cast/Anvil) for contract lifecycle
- Vue 3 + Vite + Vuetify + Pinia

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & UI Layer
    subgraph "User & UI Layer"
        direction TB
        Browser["Browser/Mobile Client"]:::external
        subgraph "Vue SPA" 
            direction TB
            MainJS["main.js"]:::frontend
            IndexHTML["index.html"]:::frontend
            ViteConfig["vite.config.js"]:::frontend
            AiButton["AiButton.vue"]:::frontend
            StoreAI["aiAnalysis.js"]:::frontend
            Router["router/index.js"]:::frontend
            Vuetify["vuetify.js"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Flask["Flask API Server\n(app.py)"]:::backend
        Config["config.py"]:::backend
        Requirements["requirements.txt"]:::backend
        ABI["contract_abi.json"]:::backend
        ETW["etw_listener.py"]:::backend
        Frida["frida_hook.py"]:::backend
        Adapter["blockchain_adapter.py"]:::backend
    end

    %% Infrastructure & Blockchain
    subgraph "Infrastructure & Blockchain"
        direction TB
        Sysmon["Sysmon Agent"]:::external
        Anvil["Local Ethereum Node\n(Anvil)"]:::external
        subgraph "Smart Contract"
            direction TB
            Contracts["Solidity Contracts (src/)"]:::smartcontract
            Tests["Contract Tests (test/)"]:::smartcontract
            DeployScript["Deploy.s.sol"]:::smartcontract
            FoundryCfg["foundry.toml"]:::smartcontract
        end
    end

    %% CI Pipeline
    CI["CI Workflow\n(.github/workflows/test.yml)"]:::external

    %% Connections
    Browser -->|"HTTP/WebSocket"| MainJS
    MainJS -->|"user actions"| Flask
    Flask -->|"reads ETW events"| ETW
    Sysmon -->|"ETW"| ETW
    Flask -->|"instruments via Frida"| Frida
    Flask -->|"Web3 calls"| Adapter
    Adapter -->|"JSON-RPC"| Anvil
    Anvil -->|"events"| Adapter
    Adapter -->|"response/events"| Flask
    Flask -->|"push updates"| MainJS

    %% Foundry Build & Deploy Flow
    DeployScript -->|"Forge build/deploy"| Anvil
    FoundryCfg -->|"configs"| DeployScript
    Contracts -->|"compiled/deployed"| Anvil
    Tests -->|"Forge test"| CI

    %% CI Integration
    CI -->|"runs tests/lint"| Contracts
    CI -->|"runs tests/lint"| Flask

    %% Click Events
    click MainJS "https://github.com/sowieee/ids-web3/blob/main/frontend/src/main.js"
    click IndexHTML "https://github.com/sowieee/ids-web3/blob/main/frontend/index.html"
    click ViteConfig "https://github.com/sowieee/ids-web3/blob/main/frontend/vite.config.js"
    click AiButton "https://github.com/sowieee/ids-web3/blob/main/frontend/src/components/AiButton.vue"
    click StoreAI "https://github.com/sowieee/ids-web3/blob/main/frontend/src/store/aiAnalysis.js"
    click Router "https://github.com/sowieee/ids-web3/blob/main/frontend/src/router/index.js"
    click Vuetify "https://github.com/sowieee/ids-web3/blob/main/frontend/src/vuetify.js"
    click Flask "https://github.com/sowieee/ids-web3/blob/main/backend/app.py"
    click Config "https://github.com/sowieee/ids-web3/blob/main/backend/config.py"
    click Requirements "https://github.com/sowieee/ids-web3/blob/main/backend/requirements.txt"
    click ABI "https://github.com/sowieee/ids-web3/blob/main/backend/contract_abi.json"
    click ETW "https://github.com/sowieee/ids-web3/blob/main/backend/etw_listener.py"
    click Frida "https://github.com/sowieee/ids-web3/blob/main/backend/frida_hook.py"
    click Adapter "https://github.com/sowieee/ids-web3/blob/main/backend/blockchain_adapter.py"
    click Contracts "https://github.com/sowieee/ids-web3/tree/main/src/"
    click Tests "https://github.com/sowieee/ids-web3/tree/main/test/"
    click DeployScript "https://github.com/sowieee/ids-web3/blob/main/script/Deploy.s.sol"
    click FoundryCfg "https://github.com/sowieee/ids-web3/blob/main/foundry.toml"
    click CI "https://github.com/sowieee/ids-web3/blob/main/.github/workflows/test.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef smartcontract fill:#e6ccff,stroke:#333,stroke-width:1px
```
