# bytedance/dolphin architecture

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

- Interactive diagram: https://gitdiagram.com/bytedance/dolphin
- Repository: https://github.com/bytedance/dolphin

## Overview

Dolphin is a document-image parsing application with page-level, layout-only, and element-level entry points. Its primary workflow detects layout and reading order, crops and classifies elements, parses their content, then saves structured and Markdown outputs. PDF handling and Markdown conversion are visible in sampled utilities; photographed-page handling and other model capabilities are documented, but their complete implementation is not shown in the excerpts.

Main entry points: [`demo_page.py`](https://github.com/bytedance/dolphin/blob/master/demo_page.py) (Page stages), [`demo_layout.py`](https://github.com/bytedance/dolphin/blob/master/demo_layout.py) (Layout stage), [`utils/utils.py`](https://github.com/bytedance/dolphin/blob/master/utils/utils.py) (Save outputs), [`demo_element.py`](https://github.com/bytedance/dolphin/blob/master/demo_element.py) (Element stage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Parsing workflows"]
  node_page["Page parser<br/>[demo_page.py]"]
  node_layout["Layout parser<br/>[demo_layout.py]"]
  node_element["Element parser<br/>[demo_element.py]"]
  node_page_stages["Page stages<br/>[demo_page.py]"]
  node_layout_stage["Layout stage<br/>[demo_layout.py]"]
  node_element_stage["Element stage<br/>[demo_element.py]"]
  node_layout_decode["Layout decoding<br/>[utils.py]"]
  node_crop_group["Crop and group<br/>[demo_page.py]"]
  node_batch_parse["Batch element parsing<br/>[demo_page.py]"]
end

subgraph group_inference["Model inference"]
  node_page_model["Page VLM inference<br/>[demo_page.py]"]
  node_layout_model["Layout VLM inference<br/>[demo_layout.py]"]
  node_element_model["Element VLM inference<br/>[demo_element.py]"]
end

subgraph group_utilities["Image and output utilities"]
  node_pdf_render["PDF rendering<br/>[utils.py]"]
  node_save_outputs["Save outputs<br/>[utils.py]"]
  node_markdown["Markdown conversion<br/>[markdown_utils.py]"]
end

subgraph group_results["Parsed results"]
  node_results["JSON and Markdown"]
end

node_user(("Document user"))
node_model_weights["Pretrained model"]

node_user -->|"runs page parse"| node_page
node_user -->|"runs layout parse"| node_layout
node_user -->|"runs element parse"| node_element
node_page -->|"processes documents"| node_page_stages
node_layout -->|"processes documents"| node_layout_stage
node_element -->|"processes images"| node_element_stage
node_page_stages -->|"renders PDF pages"| node_pdf_render
node_layout_stage -->|"renders PDF pages"| node_pdf_render
node_page_stages -->|"requests layout"| node_page_model
node_page_stages -->|"dispatches layout"| node_crop_group
node_crop_group -->|"parses layout string"| node_layout_decode
node_crop_group -->|"dispatches element batches"| node_batch_parse
node_batch_parse -->|"requests element text"| node_page_model
node_layout_stage -->|"requests layout"| node_layout_model
node_layout_stage -->|"parses layout string"| node_layout_decode
node_element_stage -->|"requests element text"| node_element_model
node_page_model -.->|"loads model"| node_model_weights
node_layout_model -.->|"loads model"| node_model_weights
node_element_model -.->|"loads model"| node_model_weights
node_page_stages -->|"saves parsed results"| node_save_outputs
node_layout_stage -->|"saves layout results"| node_save_outputs
node_element_stage -->|"saves element results"| node_save_outputs
node_save_outputs -->|"converts results"| node_markdown
node_save_outputs -->|"writes JSON and Markdown"| node_results
node_page_stages -->|"writes combined PDF results"| node_results

click node_page "https://github.com/bytedance/dolphin/blob/master/demo_page.py"
click node_layout "https://github.com/bytedance/dolphin/blob/master/demo_layout.py"
click node_element "https://github.com/bytedance/dolphin/blob/master/demo_element.py"
click node_page_stages "https://github.com/bytedance/dolphin/blob/master/demo_page.py"
click node_layout_stage "https://github.com/bytedance/dolphin/blob/master/demo_layout.py"
click node_element_stage "https://github.com/bytedance/dolphin/blob/master/demo_element.py"
click node_pdf_render "https://github.com/bytedance/dolphin/blob/master/utils/utils.py"
click node_layout_decode "https://github.com/bytedance/dolphin/blob/master/utils/utils.py"
click node_crop_group "https://github.com/bytedance/dolphin/blob/master/demo_page.py"
click node_batch_parse "https://github.com/bytedance/dolphin/blob/master/demo_page.py"
click node_page_model "https://github.com/bytedance/dolphin/blob/master/demo_page.py"
click node_layout_model "https://github.com/bytedance/dolphin/blob/master/demo_layout.py"
click node_element_model "https://github.com/bytedance/dolphin/blob/master/demo_element.py"
click node_save_outputs "https://github.com/bytedance/dolphin/blob/master/utils/utils.py"
click node_markdown "https://github.com/bytedance/dolphin/blob/master/utils/markdown_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_page,node_layout,node_element,node_page_stages,node_layout_stage,node_element_stage,node_layout_decode,node_crop_group,node_batch_parse,node_user toneBlue
class node_page_model,node_layout_model,node_element_model toneAmber
class node_pdf_render,node_save_outputs,node_markdown toneMint
class node_results toneRose
class node_model_weights toneIndigo
```

## Components

### Parsing workflows

- [Page parser](https://github.com/bytedance/dolphin/blob/master/demo_page.py): `demo_page.py`
- [Layout parser](https://github.com/bytedance/dolphin/blob/master/demo_layout.py): `demo_layout.py`
- [Element parser](https://github.com/bytedance/dolphin/blob/master/demo_element.py): `demo_element.py`
- [Page stages](https://github.com/bytedance/dolphin/blob/master/demo_page.py): `demo_page.py`
- [Layout stage](https://github.com/bytedance/dolphin/blob/master/demo_layout.py): `demo_layout.py`
- [Element stage](https://github.com/bytedance/dolphin/blob/master/demo_element.py): `demo_element.py`
- [Layout decoding](https://github.com/bytedance/dolphin/blob/master/utils/utils.py): `utils/utils.py`
- [Crop and group](https://github.com/bytedance/dolphin/blob/master/demo_page.py): `demo_page.py`
- [Batch element parsing](https://github.com/bytedance/dolphin/blob/master/demo_page.py): `demo_page.py`

### Model inference

- [Page VLM inference](https://github.com/bytedance/dolphin/blob/master/demo_page.py): `demo_page.py`
- [Layout VLM inference](https://github.com/bytedance/dolphin/blob/master/demo_layout.py): `demo_layout.py`
- [Element VLM inference](https://github.com/bytedance/dolphin/blob/master/demo_element.py): `demo_element.py`

### Image and output utilities

- [PDF rendering](https://github.com/bytedance/dolphin/blob/master/utils/utils.py): `utils/utils.py`
- [Save outputs](https://github.com/bytedance/dolphin/blob/master/utils/utils.py): `utils/utils.py`
- [Markdown conversion](https://github.com/bytedance/dolphin/blob/master/utils/markdown_utils.py): `utils/markdown_utils.py`

### Parsed results

- **JSON and Markdown**

### Other components

- **Document user**
- **Pretrained model**

## Connections

- Document user → Page parser: runs page parse
- Document user → Layout parser: runs layout parse
- Document user → Element parser: runs element parse
- Page parser → Page stages: processes documents
- Layout parser → Layout stage: processes documents
- Element parser → Element stage: processes images
- Page stages → PDF rendering: renders PDF pages
- Layout stage → PDF rendering: renders PDF pages
- Page stages → Page VLM inference: requests layout
- Page stages → Crop and group: dispatches layout
- Crop and group → Layout decoding: parses layout string
- Crop and group → Batch element parsing: dispatches element batches
- Batch element parsing → Page VLM inference: requests element text
- Layout stage → Layout VLM inference: requests layout
- Layout stage → Layout decoding: parses layout string
- Element stage → Element VLM inference: requests element text
- Page VLM inference → Pretrained model: loads model
- Layout VLM inference → Pretrained model: loads model
- Element VLM inference → Pretrained model: loads model
- Page stages → Save outputs: saves parsed results
- Layout stage → Save outputs: saves layout results
- Element stage → Save outputs: saves element results
- Save outputs → Markdown conversion: converts results
- Save outputs → JSON and Markdown: writes JSON and Markdown
- Page stages → JSON and Markdown: writes combined PDF results