# going-doer/paper2code architecture

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

- Interactive diagram: https://gitdiagram.com/going-doer/paper2code
- Repository: https://github.com/going-doer/paper2code

## Overview

PaperCoder turns a scientific paper into a generated code repository through planning, analysis, and code generation, with debugging and model-based evaluation as additional capabilities. The README documents PDF-to-JSON conversion and JSON or LaTeX inputs; the sampled planning and coding modules show both OpenAI and vLLM implementations. Evaluation supports reference-based and reference-free modes. Some pipeline wiring is documented rather than visible in the sampled source, so documented links are identified as such; unsampled subsystem internals are not inferred.

Main entry points: [`codes/1.1_extract_config.py`](https://github.com/going-doer/paper2code/blob/master/codes/1.1_extract_config.py) (Planning artifacts), [`codes/eval.py`](https://github.com/going-doer/paper2code/blob/master/codes/eval.py) (Repository evaluation), [`codes/1_planning.py`](https://github.com/going-doer/paper2code/blob/master/codes/1_planning.py) (LLM planning), [`codes/2_analyzing.py`](https://github.com/going-doer/paper2code/blob/master/codes/2_analyzing.py) (LLM analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Paper Inputs"]
  node_paper["Paper input"]
  node_pdfprocess["PDF conversion<br/>[0_pdf_process.py]"]
end

subgraph group_plan["Planning"]
  node_plan_api["LLM planning<br/>[1_planning.py]"]
  node_plan_local["vLLM planning<br/>[1_planning_llm.py]"]
  node_config_extract["Planning artifacts"]
  node_rag_config["RAG configuration<br/>[1.2_rag_config.py]"]
  node_analysis_api["LLM analysis<br/>[2_analyzing.py]"]
  node_analysis_local["vLLM analysis<br/>[2_analyzing_llm.py]"]
end

subgraph group_implement["Implementation"]
  node_code_api["LLM code generation<br/>[3_coding.py]"]
  node_code_local["vLLM code generation<br/>[3_coding_llm.py]"]
  node_code_script["Script generation<br/>[3.1_coding_sh.py]"]
  node_debug["Generated-code debugging<br/>[4_debugging.py]"]
  node_generated_repo["Generated repository"]
end

subgraph group_quality["Quality and Evaluation"]
  node_evaluation["Repository evaluation<br/>[eval.py]"]
  node_prompts["Evaluation prompts"]
  node_benchmark[("Paper2Code benchmark")]
  node_utilities["Shared parsing and logging<br/>[utils.py]"]
end

node_user(("PaperCoder user"))

node_user -->|"provides paper"| node_paper
node_paper -.->|"PDF conversion"| node_pdfprocess
node_paper -->|"starts workflow"| node_plan_api
node_paper -->|"starts workflow"| node_plan_local
node_plan_api -->|"writes artifacts"| node_config_extract
node_plan_api -->|"plans then analyzes"| node_analysis_api
node_plan_local -->|"plans then analyzes"| node_analysis_local
node_config_extract -->|"provides config"| node_analysis_api
node_config_extract -->|"provides planning"| node_analysis_local
node_analysis_api -->|"analyzes then generates"| node_code_api
node_analysis_local -->|"analyzes then generates"| node_code_local
node_config_extract -->|"provides config"| node_code_api
node_config_extract -->|"provides planning"| node_code_local
node_code_api -->|"writes files"| node_generated_repo
node_code_local -->|"writes files"| node_generated_repo
node_generated_repo -->|"debug target"| node_debug
node_debug -->|"applies fixes"| node_generated_repo
node_user -->|"evaluates repository"| node_evaluation
node_generated_repo -->|"reads target code"| node_evaluation
node_paper -->|"supplies paper context"| node_evaluation
node_prompts -->|"loads evaluation prompt"| node_evaluation
node_benchmark -.->|"benchmark data"| node_user
node_plan_api -->|"uses helpers"| node_utilities
node_analysis_api -->|"uses helpers"| node_utilities
node_code_api -->|"uses helpers"| node_utilities
node_evaluation -->|"uses helpers"| node_utilities

click node_pdfprocess "https://github.com/going-doer/paper2code/blob/master/codes/0_pdf_process.py"
click node_plan_api "https://github.com/going-doer/paper2code/blob/master/codes/1_planning.py"
click node_plan_local "https://github.com/going-doer/paper2code/blob/master/codes/1_planning_llm.py"
click node_config_extract "https://github.com/going-doer/paper2code/blob/master/codes/1.1_extract_config.py"
click node_rag_config "https://github.com/going-doer/paper2code/blob/master/codes/1.2_rag_config.py"
click node_analysis_api "https://github.com/going-doer/paper2code/blob/master/codes/2_analyzing.py"
click node_analysis_local "https://github.com/going-doer/paper2code/blob/master/codes/2_analyzing_llm.py"
click node_code_api "https://github.com/going-doer/paper2code/blob/master/codes/3_coding.py"
click node_code_local "https://github.com/going-doer/paper2code/blob/master/codes/3_coding_llm.py"
click node_code_script "https://github.com/going-doer/paper2code/blob/master/codes/3.1_coding_sh.py"
click node_debug "https://github.com/going-doer/paper2code/blob/master/codes/4_debugging.py"
click node_evaluation "https://github.com/going-doer/paper2code/blob/master/codes/eval.py"
click node_prompts "https://github.com/going-doer/paper2code/tree/master/data/prompts"
click node_benchmark "https://github.com/going-doer/paper2code/tree/master/data/paper2code"
click node_utilities "https://github.com/going-doer/paper2code/blob/master/codes/utils.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_paper,node_pdfprocess,node_user toneBlue
class node_plan_api,node_plan_local,node_config_extract,node_rag_config,node_analysis_api,node_analysis_local toneAmber
class node_code_api,node_code_local,node_code_script,node_debug,node_generated_repo toneMint
class node_evaluation,node_prompts,node_benchmark,node_utilities toneRose
```

## Components

### Paper Inputs

- **Paper input**
- [PDF conversion](https://github.com/going-doer/paper2code/blob/master/codes/0_pdf_process.py): `codes/0_pdf_process.py`

### Planning

- [LLM planning](https://github.com/going-doer/paper2code/blob/master/codes/1_planning.py): `codes/1_planning.py`
- [vLLM planning](https://github.com/going-doer/paper2code/blob/master/codes/1_planning_llm.py): `codes/1_planning_llm.py`
- [Planning artifacts](https://github.com/going-doer/paper2code/blob/master/codes/1.1_extract_config.py): `codes/1.1_extract_config.py`
- [RAG configuration](https://github.com/going-doer/paper2code/blob/master/codes/1.2_rag_config.py): `codes/1.2_rag_config.py`
- [LLM analysis](https://github.com/going-doer/paper2code/blob/master/codes/2_analyzing.py): `codes/2_analyzing.py`
- [vLLM analysis](https://github.com/going-doer/paper2code/blob/master/codes/2_analyzing_llm.py): `codes/2_analyzing_llm.py`

### Implementation

- [LLM code generation](https://github.com/going-doer/paper2code/blob/master/codes/3_coding.py): `codes/3_coding.py`
- [vLLM code generation](https://github.com/going-doer/paper2code/blob/master/codes/3_coding_llm.py): `codes/3_coding_llm.py`
- [Script generation](https://github.com/going-doer/paper2code/blob/master/codes/3.1_coding_sh.py): `codes/3.1_coding_sh.py`
- [Generated-code debugging](https://github.com/going-doer/paper2code/blob/master/codes/4_debugging.py): `codes/4_debugging.py`
- **Generated repository**

### Quality and Evaluation

- [Repository evaluation](https://github.com/going-doer/paper2code/blob/master/codes/eval.py): `codes/eval.py`
- [Evaluation prompts](https://github.com/going-doer/paper2code/tree/master/data/prompts): `data/prompts`
- [Paper2Code benchmark](https://github.com/going-doer/paper2code/tree/master/data/paper2code): `data/paper2code`
- [Shared parsing and logging](https://github.com/going-doer/paper2code/blob/master/codes/utils.py): `codes/utils.py`

### Other components

- **PaperCoder user**

## Connections

- PaperCoder user → Paper input: provides paper (evidence: `README.md`)
- Paper input → PDF conversion: PDF conversion (evidence: `README.md`)
- Paper input → LLM planning: starts workflow (evidence: `README.md`)
- Paper input → vLLM planning: starts workflow (evidence: `README.md`)
- LLM planning → Planning artifacts: writes artifacts (evidence: `codes/1.1_extract_config.py`)
- LLM planning → LLM analysis: plans then analyzes (evidence: `README.md`)
- vLLM planning → vLLM analysis: plans then analyzes (evidence: `README.md`)
- Planning artifacts → LLM analysis: provides config (evidence: `codes/2_analyzing.py`)
- Planning artifacts → vLLM analysis: provides planning (evidence: `codes/2_analyzing_llm.py`)
- LLM analysis → LLM code generation: analyzes then generates (evidence: `README.md`)
- vLLM analysis → vLLM code generation: analyzes then generates (evidence: `README.md`)
- Planning artifacts → LLM code generation: provides config (evidence: `codes/3_coding.py`)
- Planning artifacts → vLLM code generation: provides planning (evidence: `codes/3_coding_llm.py`)
- LLM code generation → Generated repository: writes files (evidence: `codes/3_coding.py`)
- vLLM code generation → Generated repository: writes files (evidence: `codes/3_coding_llm.py`)
- Generated repository → Generated-code debugging: debug target (evidence: `codes/4_debugging.py`)
- Generated-code debugging → Generated repository: applies fixes (evidence: `codes/4_debugging.py`)
- PaperCoder user → Repository evaluation: evaluates repository (evidence: `README.md`)
- Generated repository → Repository evaluation: reads target code (evidence: `codes/eval.py`)
- Paper input → Repository evaluation: supplies paper context (evidence: `codes/eval.py`)
- Evaluation prompts → Repository evaluation: loads evaluation prompt (evidence: `codes/eval.py`)
- Paper2Code benchmark → PaperCoder user: benchmark data (evidence: `README.md`)
- LLM planning → Shared parsing and logging: uses helpers (evidence: `codes/1_planning.py`)
- LLM analysis → Shared parsing and logging: uses helpers (evidence: `codes/2_analyzing.py`)
- LLM code generation → Shared parsing and logging: uses helpers (evidence: `codes/3_coding.py`)
- Repository evaluation → Shared parsing and logging: uses helpers (evidence: `codes/eval.py`)
