# cods-gcs/resequel architecture

> Architecture diagram of the GitHub repository cods-gcs/resequel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cods-gcs/resequel
- Repository: https://github.com/cods-gcs/resequel
- Video tour (about a minute): https://gitdiagram.com/cods-gcs/resequel/video

## Overview

ReSequel is an LLM-assisted SQL rewrite optimizer layered over existing DBMSs. Its documented workflow uses catalog metadata and query templatization to guide rewrite generation, verifies candidates on sampled data, then ranks variants for correctness and runtime. The repository also contains baseline workload execution and verification tools used in evaluation. Core Python implementation details are not excerpted, so those subsystem paths and workflow links follow the README; baseline links use the shown excerpts or SOURCE INDEX references.

Main entry points: [`Experiments/baselines/Workload/RunWorkload.py`](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/RunWorkload.py) (Workload runner), [`Experiments/baselines/Workload/Verify_main.py`](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Verify_main.py) (Candidate verifier), [`Experiments/baselines/Workload/Verify_LR.py`](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Verify_LR.py) (LR verifier), [`Experiments/baselines/Workload/Database.py`](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Database.py) (DBMS adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rewrite["Rewrite workflow"]
  node_entry["ReSequel entry"]
  node_templatize["Query templatization"]
  node_rewrites["Rewrite variants"]
  node_verify["Correctness verification"]
  node_rank["Variant ranking"]
  node_result["Selected rewrite"]
end

subgraph group_data["Database and sampling"]
  node_catalog["Catalog extraction"]
  node_sampling["Downsampling engine"]
  node_dbms[("Host DBMS")]
end

subgraph group_support["Prompt and LLM"]
  node_prompt["Prompt builder"]
  node_llm["LLM integration"]
end

subgraph group_baseline["Baseline evaluation"]
  node_baseline_config["Workload config<br/>[Config.py]"]
  node_baseline_runner["Workload runner<br/>[RunWorkload.py]"]
  node_baseline_db["DBMS adapters<br/>[Database.py]"]
  node_file_handler["File handling<br/>[FileHandler.py]"]
  node_workload_log["Workload results<br/>[LogResults.py]"]
  node_verify_main["Candidate verifier<br/>[Verify_main.py]"]
  node_verify_lr["LR verifier<br/>[Verify_LR.py]"]
  node_sqlsolver["SQLSolver equivalence<br/>[Main.java]"]
  node_sqlsolver_util["Solver file utilities<br/>[Util.java]"]
  node_run_cli["Workload CLI<br/>[main.py]"]
  node_verify_cli["Verification CLI<br/>[main_verify.py]"]
end

node_user(("Workload user"))

node_user -->|"submits workload"| node_entry
node_entry -->|"uses metadata"| node_catalog
node_entry -->|"templatizes queries"| node_templatize
node_entry -->|"builds prompts"| node_prompt
node_prompt -->|"guides rewriting"| node_llm
node_llm -->|"generates variants"| node_rewrites
node_entry -->|"uses sampled data"| node_sampling
node_verify -->|"executes candidates"| node_dbms
node_verify -->|"checks sampled data"| node_sampling
node_entry -->|"verifies variants"| node_verify
node_entry -->|"ranks variants"| node_rank
node_rank -->|"selects rewrite"| node_result
node_run_cli -->|"loads settings"| node_baseline_config
node_run_cli -->|"starts runner"| node_baseline_runner
node_baseline_runner -->|"executes queries"| node_baseline_db
node_baseline_runner -->|"reads query files"| node_file_handler
node_baseline_runner -->|"records timings"| node_workload_log
node_verify_cli -->|"loads settings"| node_baseline_config
node_verify_cli -->|"starts verification"| node_verify_main
node_verify_main -->|"executes queries"| node_baseline_db
node_verify_main -->|"reads query files"| node_file_handler
node_verify_main -->|"logs results"| node_workload_log
node_verify_lr -->|"executes queries"| node_baseline_db
node_verify_lr -->|"reads query files"| node_file_handler
node_verify_lr -->|"logs results"| node_workload_log
node_sqlsolver -->|"reads and logs"| node_sqlsolver_util

click node_baseline_config "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Config.py"
click node_baseline_runner "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/RunWorkload.py"
click node_baseline_db "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Database.py"
click node_file_handler "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/FileHandler.py"
click node_workload_log "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/LogResults.py"
click node_verify_main "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Verify_main.py"
click node_verify_lr "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Verify_LR.py"
click node_sqlsolver "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/SQLSolver/src/main/java/org/resequel/Main.java"
click node_sqlsolver_util "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/SQLSolver/src/main/java/org/resequel/Util.java"
click node_run_cli "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/main.py"
click node_verify_cli "https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/main_verify.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_templatize,node_rewrites,node_verify,node_rank,node_result,node_user toneBlue
class node_catalog,node_sampling,node_dbms toneAmber
class node_prompt,node_llm toneMint
class node_baseline_config,node_baseline_runner,node_baseline_db,node_file_handler,node_workload_log,node_verify_main,node_verify_lr,node_sqlsolver,node_sqlsolver_util,node_run_cli,node_verify_cli toneRose
```

## Components

### Rewrite workflow

- **ReSequel entry**
- **Query templatization**
- **Rewrite variants**
- **Correctness verification**
- **Variant ranking**
- **Selected rewrite**

### Database and sampling

- **Catalog extraction**
- **Downsampling engine**
- **Host DBMS**

### Prompt and LLM

- **Prompt builder**
- **LLM integration**

### Baseline evaluation

- [Workload config](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Config.py): `Experiments/baselines/Workload/Config.py`
- [Workload runner](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/RunWorkload.py): `Experiments/baselines/Workload/RunWorkload.py`
- [DBMS adapters](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Database.py): `Experiments/baselines/Workload/Database.py`
- [File handling](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/FileHandler.py): `Experiments/baselines/Workload/FileHandler.py`
- [Workload results](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/LogResults.py): `Experiments/baselines/Workload/LogResults.py`
- [Candidate verifier](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Verify_main.py): `Experiments/baselines/Workload/Verify_main.py`
- [LR verifier](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/Verify_LR.py): `Experiments/baselines/Workload/Verify_LR.py`
- [SQLSolver equivalence](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/SQLSolver/src/main/java/org/resequel/Main.java): `Experiments/baselines/SQLSolver/src/main/java/org/resequel/Main.java`
- [Solver file utilities](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/SQLSolver/src/main/java/org/resequel/Util.java): `Experiments/baselines/SQLSolver/src/main/java/org/resequel/Util.java`
- [Workload CLI](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/main.py): `Experiments/baselines/Workload/main.py`
- [Verification CLI](https://github.com/cods-gcs/resequel/blob/main/Experiments/baselines/Workload/main_verify.py): `Experiments/baselines/Workload/main_verify.py`

### Other components

- **Workload user**

## Connections

- Workload user → ReSequel entry: submits workload (evidence: `README.md`)
- ReSequel entry → Catalog extraction: uses metadata (evidence: `README.md`)
- ReSequel entry → Query templatization: templatizes queries (evidence: `README.md`)
- ReSequel entry → Prompt builder: builds prompts (evidence: `README.md`)
- Prompt builder → LLM integration: guides rewriting (evidence: `README.md`)
- LLM integration → Rewrite variants: generates variants (evidence: `README.md`)
- ReSequel entry → Downsampling engine: uses sampled data (evidence: `README.md`)
- Correctness verification → Host DBMS: executes candidates (evidence: `README.md`)
- Correctness verification → Downsampling engine: checks sampled data (evidence: `README.md`)
- ReSequel entry → Correctness verification: verifies variants (evidence: `README.md`)
- ReSequel entry → Variant ranking: ranks variants (evidence: `README.md`)
- Variant ranking → Selected rewrite: selects rewrite (evidence: `README.md`)
- Workload CLI → Workload config: loads settings (evidence: `Experiments/baselines/Workload/main.py`)
- Workload CLI → Workload runner: starts runner (evidence: `Experiments/baselines/Workload/main.py`)
- Workload runner → DBMS adapters: executes queries (evidence: `Experiments/baselines/Workload/RunWorkload.py`)
- Workload runner → File handling: reads query files (evidence: `Experiments/baselines/Workload/RunWorkload.py`)
- Workload runner → Workload results: records timings (evidence: `Experiments/baselines/Workload/RunWorkload.py`)
- Verification CLI → Workload config: loads settings (evidence: `Experiments/baselines/Workload/main_verify.py`)
- Verification CLI → Candidate verifier: starts verification (evidence: `Experiments/baselines/Workload/main_verify.py`)
- Candidate verifier → DBMS adapters: executes queries (evidence: `Experiments/baselines/Workload/Verify_main.py`)
- Candidate verifier → File handling: reads query files (evidence: `Experiments/baselines/Workload/Verify_main.py`)
- Candidate verifier → Workload results: logs results (evidence: `Experiments/baselines/Workload/Verify_main.py`)
- LR verifier → DBMS adapters: executes queries (evidence: `Experiments/baselines/Workload/Verify_LR.py`)
- LR verifier → File handling: reads query files (evidence: `Experiments/baselines/Workload/Verify_LR.py`)
- LR verifier → Workload results: logs results (evidence: `Experiments/baselines/Workload/Verify_LR.py`)
- SQLSolver equivalence → Solver file utilities: reads and logs (evidence: `Experiments/baselines/SQLSolver/src/main/java/org/resequel/Main.java`)