# qcri/llmxcpg architecture

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

- Interactive diagram: https://gitdiagram.com/qcri/llmxcpg
- Repository: https://github.com/qcri/llmxcpg

## Overview

##### Project Type and Purpose
- This is a research-oriented vulnerability‐detection pipeline that ties together Code Property Graph (CPG) analysis (via Joern) with two fine‐tuned LLMs.
- It is neither a traditional web app nor a pure library; it is a full end‐to‐end data‐processing and ML inference/training framework.

##### File‐Structure Overview
- **baselines/**: reference implementations for comparative evaluation (GNN, VulBERTa, VulSim, dx2021 code2vec).
- **data/**: JSONL files and test/train splits for vulnerability detection datasets.
- **inference/**: scripts to run LLMxCPG-Q (query generator) and LLMxCPG-D (detector) on unseen code.
- **prompts/**: system‐prompt templates for the two LLM phases.
- **queries/**:
- Components (c_parser, joern_manager, slice builder, enhancer)
- Dockerfile / docker‐compose for spinning up a Joern/CPG‐query service
- Orchestration scripts that generate and dispatch CPGQL queries
- **training/**: fine‐tuning code for LLMxCPG-Q and LLMxCPG-D (LoRA + Unsloth)
- **pipeline.sh**: end‐to‐end orchestration (CPG generation → query gen → slice extraction → detection)
- **requirements.txt**, **example.env**: environment and dependency definitions

##### Architecture Synopsis from README
- Two‐phase approach:
a. **Slice Construction**: LLMxCPG-Q generates targeted CPGQL queries
b. **Vulnerability Detection**: LLMxCPG-D classifies the extracted slice
- External dependency: **Joern** for CPG generation and query execution
- LLMs hosted on **Hugging Face**; fine‐tuned via Unsloth + LoRA

##### Key Components
a. **Input Layer**
- Raw code repositories (on local disk or Git URLs)
- Dataset files under **data/** for training/inference
b. **CPG Generation Service**
- **Joern** (Docker container)
- Generates in-memory/on-disk code property graphs
c. **Query Generation Service (LLMxCPG-Q)**
- Python script (training: `training/llmxcpg_query_finetune.py`; inference: `inference/detect_inference.py` or analogous)
- Reads CPG metadata and outputs CPGQL queries
d. **Query Executor & Slice Extractor**
- **queries/** components (joern_manager, c_parser, slice builder)
- Executes CPGQL, returns minimal code slice
e. **Vulnerability Detection Service (LLMxCPG-D)**
- Python script (training: `training/llmxcpg_detect_finetune.py`; inference: `inference/detect_inference.py`)
- Classifies extracted slice as vulnerable or safe
f. **Orchestration Layer**
- `pipeline.sh` or `docker-compose.yml`
- Manages service startup, data flow, and parameter injection (via example.env)
g. **Outputs & Baseline Evaluation**
- Classification results (JSONL or text)
- Side‐by‐side baseline results under **baselines/** for performance comparison

##### Relationships & Data Flow
- **Raw Code → Joern CPG Service**
→ **CPG Graph Data**
→ **LLMxCPG-Q** (reads CPG metadata, emits CPGQL)
→ **Query Executor** (executes CPGQL against Joern, returns slice)
→ **LLMxCPG-D** (classifies slice)
→ **Results** (aggregated vulnerability labels)

##### Architectural Patterns & Principles
- **Modular Microservices**: each major function runs as a separate Docker/Python service
- **Pipelines as Code**: `pipeline.sh`, `docker-compose.yml` encode end-to-end flow
- **Separation of Concerns**:
- CPG generation vs. query logic vs. detection logic vs. baseline comparators
- Training vs. inference code paths
- **Reproducibility**: environment pinned via `requirements.txt` and `example.env`

##### Technologies & Frameworks
- Python 3.8+, Docker & Docker Compose
- Joern (v4.x) for CPG generation & query
- Hugging Face Transformers + Unsloth for LoRA fine‐tuning
- JSONL, shell scripts for orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    data["data/ (JSONL, splits)"]:::storage
    click data "https://github.com/qcri/llmxcpg/tree/main/data/"

    %% CPG Generation Service
    cpg_dockerfile["Dockerfile (Joern CPG)"]:::cpg
    click cpg_dockerfile "https://github.com/qcri/llmxcpg/tree/main/queries/Dockerfile"
    cpg_compose["docker-compose.yml"]:::orches
    click cpg_compose "https://github.com/qcri/llmxcpg/blob/main/queries/docker-compose.yml"
    cpg_service["Joern CPG Service"]:::cpg

    %% Query Generation Service (LLMxCPG-Q)
    Q_train["LLMxCPG-Q Training\ntraining/llmxcpg_query_finetune.py"]:::llm
    click Q_train "https://github.com/qcri/llmxcpg/blob/main/training/llmxcpg_query_finetune.py"
    Q_prompt["Query Prompt\nprompts/query_system_prompt.txt"]:::llm
    click Q_prompt "https://github.com/qcri/llmxcpg/blob/main/prompts/query_system_prompt.txt"
    Q_infer["LLMxCPG-Q Inference\ninference/detect_inference.py"]:::llm
    click Q_infer "https://github.com/qcri/llmxcpg/blob/main/inference/detect_inference.py"

    %% Query Executor & Slice Extractor
    subgraph "Query Executor & Slice Extractor"
        c_parser["c_parser.py"] 
        click c_parser "https://github.com/qcri/llmxcpg/blob/main/queries/Components/c_parser.py"
        joern_manager["joern_manager.py"] 
        click joern_manager "https://github.com/qcri/llmxcpg/blob/main/queries/Components/joern_manager.py"
        slice_builder["slice.py"] 
        click slice_builder "https://github.com/qcri/llmxcpg/blob/main/queries/Components/slice.py"
        enhancer["enhancer.py"] 
        click enhancer "https://github.com/qcri/llmxcpg/blob/main/queries/Components/enhancer.py"
        construct_slice["construct_slice.py"] 
        click construct_slice "https://github.com/qcri/llmxcpg/blob/main/queries/construct_slice.py"
        gen_queries["generate_and_run_queries.py"] 
        click gen_queries "https://github.com/qcri/llmxcpg/blob/main/queries/generate_and_run_queries.py"
    end

    %% Vulnerability Detection Service (LLMxCPG-D)
    D_train["LLMxCPG-D Training\ntraining/llmxcpg_detect_finetune.py"]:::llm
    click D_train "https://github.com/qcri/llmxcpg/blob/main/training/llmxcpg_detect_finetune.py"
    D_prompt["Detect Prompt\nprompts/detect_system_prompt.txt"]:::llm
    click D_prompt "https://github.com/qcri/llmxcpg/blob/main/prompts/detect_system_prompt.txt"
    D_infer["LLMxCPG-D Inference\ninference/detect_inference.py"]:::llm
    click D_infer "https://github.com/qcri/llmxcpg/blob/main/inference/detect_inference.py"

    %% Orchestration Layer
    pipeline["pipeline.sh"]:::orches
    click pipeline "https://github.com/qcri/llmxcpg/blob/main/pipeline.sh"
    env["example.env"]:::orches
    click env "https://github.com/qcri/llmxcpg/blob/main/example.env"

    %% Baseline Evaluation
    baselines["baselines/"]:::baseline
    click baselines "https://github.com/qcri/llmxcpg/tree/main/baselines/"

    %% External Dependencies
    joern_ext["Joern (Docker)"]:::external
    hf_models["Hugging Face Models"]:::external

    %% Main Inference Flow
    data --> cpg_service
    cpg_dockerfile --> cpg_service
    cpg_compose --> cpg_service
    cpg_service --> Q_infer
    Q_prompt --> Q_infer
    Q_infer --> gen_queries
    gen_queries --> c_parser
    gen_queries --> joern_manager
    gen_queries --> slice_builder
    gen_queries --> enhancer
    c_parser --> construct_slice
    joern_manager --> construct_slice
    slice_builder --> construct_slice
    enhancer --> construct_slice
    construct_slice --> D_infer
    D_prompt --> D_infer
    D_infer --> baselines

    %% Training Paths
    data --> Q_train
    data --> D_train
    hf_models --> Q_train
    hf_models --> D_train

    %% Orchestration Connections
    pipeline --> cpg_service
    pipeline --> Q_infer
    pipeline --> gen_queries
    pipeline --> D_infer
    env --> pipeline

    %% Styles
    classDef llm fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef cpg fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orches fill:#FFA500,stroke:#333,stroke-width:1px
    classDef baseline fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#000,stroke-dasharray: 5 5,stroke-width:1px
```
