# federicodeponte/opendraft architecture

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

- Interactive diagram: https://gitdiagram.com/federicodeponte/opendraft
- Repository: https://github.com/federicodeponte/opendraft

## Overview

OpenDraft is a research-paper and thesis drafting system, with a separate agent skill for autonomous research. Its principal workflow accepts a topic through the CLI, orchestrates research and writing phases, verifies citations, and produces documents for export. The README documents the six-phase pipeline and citation policy; sampled source and the SOURCE INDEX support the orchestration, research, citation, and CLI relationships shown. Several phase implementations and export details were not sampled, so their internal wiring is left out or attributed only to documented workflow.

Main entry points: [`engine/draft_generator.py`](https://github.com/federicodeponte/opendraft/blob/master/engine/draft_generator.py) (Draft orchestrator), [`engine/utils/api_citations/orchestrator.py`](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/orchestrator.py) (Citation research), [`engine/opendraft/cli.py`](https://github.com/federicodeponte/opendraft/blob/master/engine/opendraft/cli.py) (OpenDraft CLI), [`engine/phases/research.py`](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/research.py) (Research phase)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["OpenDraft CLI<br/>[cli.py]"]
end

subgraph group_workflow["Draft workflow"]
  node_generator["Draft orchestrator<br/>[draft_generator.py]"]
  node_context["Shared draft context<br/>[context.py]"]
  node_agents["Agent runner<br/>[agent_runner.py]"]
  node_structure["Structure phase<br/>[structure.py]"]
  node_compose["Compose phase<br/>[compose.py]"]
end

subgraph group_research["Research and citations"]
  node_research_phase["Research phase<br/>[research.py]"]
  node_citations_phase["Citation phase<br/>[citations.py]"]
  node_citation_orchestrator["Citation research<br/>[orchestrator.py]"]
  node_query_router["Query routing<br/>[query_router.py]"]
  node_crossref["Crossref search<br/>[crossref.py]"]
  node_openalex["OpenAlex search<br/>[openalex.py]"]
  node_semantic["Semantic Scholar"]
  node_grounded["Grounded web search<br/>[gemini_grounded.py]"]
  node_serper["Serper search<br/>[serper_client.py]"]
  node_citation_db[("Citation database")]
end

subgraph group_output["Validation and output"]
  node_validate["Validation phase<br/>[validate.py]"]
  node_compile["Document compilation<br/>[compile.py]"]
  node_pdf["PDF engines"]
end

subgraph group_extras["Additional capabilities"]
  node_revise["Draft revision<br/>[revise.py]"]
  node_tldr["Paper summary<br/>[tldr.py]"]
  node_reader["Document reader<br/>[document_reader.py]"]
  node_skill["Autonomous research skill"]
end

node_user(("Researcher"))

node_user -->|"provides topic"| node_cli
node_cli -->|"starts drafting"| node_generator
node_generator -->|"runs phases"| node_research_phase
node_generator -->|"runs phases"| node_structure
node_generator -->|"runs phases"| node_citations_phase
node_generator -->|"runs phases"| node_compose
node_generator -->|"runs phases"| node_validate
node_generator -->|"runs phases"| node_compile
node_research_phase -->|"uses agents"| node_agents
node_compose -->|"uses agents"| node_agents
node_agents -->|"creates researcher"| node_citation_orchestrator
node_citation_orchestrator -->|"routes queries"| node_query_router
node_citation_orchestrator -->|"searches"| node_crossref
node_citation_orchestrator -->|"searches"| node_openalex
node_citation_orchestrator -->|"searches"| node_semantic
node_citation_orchestrator -->|"searches"| node_grounded
node_citation_orchestrator -->|"searches"| node_serper
node_research_phase -->|"adds supplied sources"| node_citation_db
node_generator -->|"uses citation data"| node_citation_db
node_compile -.->|"exports documents"| node_pdf
node_cli -->|"starts revision"| node_revise
node_cli -->|"requests summary"| node_tldr
node_tldr -->|"reads document"| node_reader
node_user -->|"uses skill"| node_skill

click node_cli "https://github.com/federicodeponte/opendraft/blob/master/engine/opendraft/cli.py"
click node_generator "https://github.com/federicodeponte/opendraft/blob/master/engine/draft_generator.py"
click node_context "https://github.com/federicodeponte/opendraft/blob/master/engine/phases/context.py"
click node_agents "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/agent_runner.py"
click node_research_phase "https://github.com/federicodeponte/opendraft/blob/master/engine/phases/research.py"
click node_structure "https://github.com/federicodeponte/opendraft/blob/master/engine/phases/structure.py"
click node_compose "https://github.com/federicodeponte/opendraft/blob/master/engine/phases/compose.py"
click node_citations_phase "https://github.com/federicodeponte/opendraft/blob/master/engine/phases/citations.py"
click node_citation_orchestrator "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/orchestrator.py"
click node_query_router "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/query_router.py"
click node_crossref "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/crossref.py"
click node_openalex "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/openalex.py"
click node_semantic "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/semantic_scholar.py"
click node_grounded "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/gemini_grounded.py"
click node_serper "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/serper_client.py"
click node_citation_db "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/citation_database.py"
click node_validate "https://github.com/federicodeponte/opendraft/blob/master/engine/phases/validate.py"
click node_compile "https://github.com/federicodeponte/opendraft/blob/master/engine/phases/compile.py"
click node_pdf "https://github.com/federicodeponte/opendraft/tree/master/engine/utils/pdf_engines"
click node_revise "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/revise.py"
click node_tldr "https://github.com/federicodeponte/opendraft/blob/master/engine/tldr.py"
click node_reader "https://github.com/federicodeponte/opendraft/blob/master/engine/utils/document_reader.py"
click node_skill "https://github.com/federicodeponte/opendraft/tree/master/skills/autonomous-research/scripts"

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_cli toneBlue
class node_generator,node_context,node_agents,node_structure,node_compose toneAmber
class node_research_phase,node_citations_phase,node_citation_orchestrator,node_query_router,node_crossref,node_openalex,node_semantic,node_grounded,node_serper,node_citation_db toneMint
class node_validate,node_compile,node_pdf toneRose
class node_revise,node_tldr,node_reader,node_skill,node_user toneIndigo
```

## Components

### User entry

- [OpenDraft CLI](https://github.com/federicodeponte/opendraft/blob/master/engine/opendraft/cli.py): `engine/opendraft/cli.py`

### Draft workflow

- [Draft orchestrator](https://github.com/federicodeponte/opendraft/blob/master/engine/draft_generator.py): `engine/draft_generator.py`
- [Shared draft context](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/context.py): `engine/phases/context.py`
- [Agent runner](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/agent_runner.py): `engine/utils/agent_runner.py`
- [Structure phase](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/structure.py): `engine/phases/structure.py`
- [Compose phase](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/compose.py): `engine/phases/compose.py`

### Research and citations

- [Research phase](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/research.py): `engine/phases/research.py`
- [Citation phase](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/citations.py): `engine/phases/citations.py`
- [Citation research](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/orchestrator.py): `engine/utils/api_citations/orchestrator.py`
- [Query routing](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/query_router.py): `engine/utils/api_citations/query_router.py`
- [Crossref search](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/crossref.py): `engine/utils/api_citations/crossref.py`
- [OpenAlex search](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/openalex.py): `engine/utils/api_citations/openalex.py`
- [Semantic Scholar](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/semantic_scholar.py): `engine/utils/api_citations/semantic_scholar.py`
- [Grounded web search](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/gemini_grounded.py): `engine/utils/api_citations/gemini_grounded.py`
- [Serper search](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/api_citations/serper_client.py): `engine/utils/api_citations/serper_client.py`
- [Citation database](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/citation_database.py): `engine/utils/citation_database.py`

### Validation and output

- [Validation phase](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/validate.py): `engine/phases/validate.py`
- [Document compilation](https://github.com/federicodeponte/opendraft/blob/master/engine/phases/compile.py): `engine/phases/compile.py`
- [PDF engines](https://github.com/federicodeponte/opendraft/tree/master/engine/utils/pdf_engines): `engine/utils/pdf_engines`

### Additional capabilities

- [Draft revision](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/revise.py): `engine/utils/revise.py`
- [Paper summary](https://github.com/federicodeponte/opendraft/blob/master/engine/tldr.py): `engine/tldr.py`
- [Document reader](https://github.com/federicodeponte/opendraft/blob/master/engine/utils/document_reader.py): `engine/utils/document_reader.py`
- [Autonomous research skill](https://github.com/federicodeponte/opendraft/tree/master/skills/autonomous-research/scripts): `skills/autonomous-research/scripts`

### Other components

- **Researcher**

## Connections

- Researcher → OpenDraft CLI: provides topic (evidence: `README.md`)
- OpenDraft CLI → Draft orchestrator: starts drafting (evidence: `engine/opendraft/cli.py`)
- Draft orchestrator → Research phase: runs phases (evidence: `README.md`)
- Draft orchestrator → Structure phase: runs phases (evidence: `README.md`)
- Draft orchestrator → Citation phase: runs phases (evidence: `README.md`)
- Draft orchestrator → Compose phase: runs phases (evidence: `README.md`)
- Draft orchestrator → Validation phase: runs phases (evidence: `README.md`)
- Draft orchestrator → Document compilation: runs phases (evidence: `README.md`)
- Research phase → Agent runner: uses agents (evidence: `engine/phases/research.py`)
- Compose phase → Agent runner: uses agents (evidence: `engine/phases/compose.py`)
- Agent runner → Citation research: creates researcher (evidence: `engine/utils/agent_runner.py`)
- Citation research → Query routing: routes queries (evidence: `engine/utils/api_citations/orchestrator.py`)
- Citation research → Crossref search: searches (evidence: `engine/utils/api_citations/orchestrator.py`)
- Citation research → OpenAlex search: searches (evidence: `engine/utils/api_citations/orchestrator.py`)
- Citation research → Semantic Scholar: searches (evidence: `engine/utils/api_citations/orchestrator.py`)
- Citation research → Grounded web search: searches (evidence: `engine/utils/api_citations/orchestrator.py`)
- Citation research → Serper search: searches (evidence: `engine/utils/api_citations/orchestrator.py`)
- Research phase → Citation database: adds supplied sources (evidence: `engine/phases/research.py`)
- Draft orchestrator → Citation database: uses citation data (evidence: `engine/draft_generator.py`)
- Document compilation → PDF engines: exports documents
- OpenDraft CLI → Draft revision: starts revision (evidence: `engine/opendraft/cli.py`)
- OpenDraft CLI → Paper summary: requests summary (evidence: `engine/opendraft/cli.py`)
- Paper summary → Document reader: reads document (evidence: `engine/tldr.py`)
- Researcher → Autonomous research skill: uses skill (evidence: `README.md`)