# cyberkaida/reverse-engineering-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/cyberkaida/reverse-engineering-assistant
- Repository: https://github.com/cyberkaida/reverse-engineering-assistant

## Overview

##### Project type and purpose
- This is an open-source, tool-driven AI assistant for reverse engineering (ReVA), composed of:
- A Java-based Ghidra extension (“ghidra-assistant”)
- A Python service/CLI suite (“reverse-engineering-assistant”)
- A gRPC protocol layer for bi-directional communication
- Integration with LLM providers (OpenAI, Ollama)

##### File-structure analysis
- Top-level:
- CI/CD workflows (.github/workflows)
- Makefile for building protocol stubs
- protocol/: .proto definitions (Reva*.proto)
- ghidra-assistant/: Gradle Java plugin for Ghidra
- reverse-engineering-assistant/: Python package, CLI tools, server logic
- requirements.txt & pyproject.toml for Python dependencies
- Patterns:
- Plugin microservice (Java) ↔ Core AI service (Python) via gRPC
- Python side uses LangChain for LLM orchestration and tool‐driven approach
- Build scripts generate gRPC clients/servers in both languages

##### Key README insights
- Two-step workflow:
1) Ghidra plugin launches/attaches to Python “reva-server”
2) CLI “reva-chat” starts interactive chat session
- Configuration via Ghidra Tool Options (provider, follow, auto-allow)
- gRPC underpins extension ↔ server communication
- LLM support pluggable via LangChain (OpenAI, Ollama, others)

a. Main components
- Ghidra Extension (Java)
- Python Service (“reva-server”)
- CLI Chat Client (“reva-chat”)
- LLM Providers (OpenAI API or Ollama server)
- Protocol buffers & gRPC layer
- Build toolchain (Makefile, protoc, Gradle, pipx)
b. Relationships & interactions
- Java plugin ↔ Python service: gRPC calls to request decompilation, bookmarks, symbols, etc.
- CLI “reva-chat” ↔ Python service: chat I/O over local IPC (could be gRPC or stdin/stdout)
- Python service ↔ LLM provider: HTTP or local RPC for model inference
- Build: .proto → protoc → generated stubs in Java & Python
c. Architectural patterns & principles
- Microservices / separation of concerns (UI plugin vs. AI engine)
- Tool-driven AI orchestration (small, self-contained RE tools exposed to LLM)
- Chain-of-reasoning pattern: each action broken into atomic steps with feedback
d. Technologies & frameworks
- Java/Gradle for Ghidra plugin
- Python/pyproject + pipx + LangChain
- gRPC / Protocol Buffers
- Makefile / protoc for codegen
- OpenAI REST API or Ollama local server for LLM inference

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% IDE / Ghidra Plugin
    subgraph "IDE Layer (Ghidra Plugin)"
        direction TB
        PluginEntry["RevaPlugin"]:::ide
        ChatService["RevaChatService"]:::ide
        Handlers["Handlers"]:::ide
        Analysis["Analysis Modules"]:::ide
        ActionsUI["Actions & UI Components"]:::ide
    end

    %% Build / Toolchain
    subgraph "Build Toolchain"
        direction TB
        Protos[".proto Definitions"]:::build
        Protoc["protoc (Codegen)"]:::build
        StubsJava["Generated Java Stubs"]:::build
        StubsPython["Generated Python Stubs"]:::build
        MakefileNode["Makefile"]:::build
        GradleBuild["Gradle Build"]:::build
        PyDeps["Python Dependencies"]:::build
    end

    %% Python AI Service
    subgraph "Python AI Service"
        direction TB
        APIServer["assistant_api_server.py"]:::server
        AIOrch["assistant.py"]:::server
        APITools["API Server Tools"]:::server
        ConnLogic["connection.py"]:::server
        LLMTools["llm_tools.py"]:::server
        RETools["re_tool_box"]:::server
    end

    %% CLI Client
    subgraph "CLI Chat Client"
        direction TB
        ChatClient["chat_client.py"]:::server
    end

    %% LLM Providers
    subgraph "External LLM Providers"
        direction TB
        OpenAI["OpenAI API"]:::ext
        Ollama["Ollama Server"]:::ext
    end

    %% Interactions
    Protos -->|generate stubs| Protoc
    Protoc --> StubsJava
    Protoc --> StubsPython
    MakefileNode --> Protoc
    GradleBuild --> StubsJava
    PyDeps --> StubsPython

    PluginEntry -->|uses gRPC stubs| StubsJava
    ChatService -->|binds gRPC| StubsJava
    Handlers -->|implements RPC| StubsJava
    Analysis -->|calls RPC| StubsJava
    ActionsUI -->|menu hooks| PluginEntry

    StubsPython --> APIServer
    APIServer -->|orchestrates| AIOrch
    AIOrch -->|loads tools| APITools
    APITools --> ConnLogic
    APITools --> LLMTools
    APITools --> RETools

    ChatClient -->|CLI IPC/gRPC| APIServer

    APIServer -->|HTTP/RPC| OpenAI
    APIServer -->|HTTP/RPC| Ollama

    %% Click Events
    click PluginEntry "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/ghidra-assistant/src/main/java/reva/RevaPlugin.java"
    click ChatService "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/ghidra-assistant/src/main/java/reva/RevaChatService.java"
    click Handlers "https://github.com/cyberkaida/reverse-engineering-assistant/tree/main/ghidra-assistant/src/main/java/reva/Handlers/"
    click Analysis "https://github.com/cyberkaida/reverse-engineering-assistant/tree/main/ghidra-assistant/src/main/java/reva/Analysis/"
    click ActionsUI "https://github.com/cyberkaida/reverse-engineering-assistant/tree/main/ghidra-assistant/src/main/java/reva/Actions/"
    click APIServer "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/reverse-engineering-assistant/reverse_engineering_assistant/assistant_api_server.py"
    click AIOrch "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/reverse-engineering-assistant/reverse_engineering_assistant/assistant.py"
    click APITools "https://github.com/cyberkaida/reverse-engineering-assistant/tree/main/reverse-engineering-assistant/reverse_engineering_assistant/api_server_tools/"
    click ConnLogic "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/reverse-engineering-assistant/reverse_engineering_assistant/api_server_tools/connection.py"
    click LLMTools "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/reverse-engineering-assistant/reverse_engineering_assistant/api_server_tools/llm_tools.py"
    click RETools "https://github.com/cyberkaida/reverse-engineering-assistant/tree/main/reverse-engineering-assistant/reverse_engineering_assistant/api_server_tools/re_tool_box/"
    click ChatClient "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/reverse-engineering-assistant/reverse_engineering_assistant/chat_client.py"
    click Protos "https://github.com/cyberkaida/reverse-engineering-assistant/tree/main/protocol/"
    click MakefileNode "https://github.com/cyberkaida/reverse-engineering-assistant/tree/main/Makefile"
    click GradleBuild "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/ghidra-assistant/build.gradle"
    click PyDeps "https://github.com/cyberkaida/reverse-engineering-assistant/blob/main/reverse-engineering-assistant/pyproject.toml"

    %% Styles
    classDef ide fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef server fill:#DFFFE0,stroke:#228B22,color:#228B22,stroke-width:1px;
    classDef ext fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00,stroke-width:1px;
    classDef build fill:#F0F0F0,stroke:#696969,color:#696969,stroke-width:1px;
```
