# xuligexu/convert-file architecture

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

- Interactive diagram: https://gitdiagram.com/xuligexu/convert-file
- Repository: https://github.com/xuligexu/convert-file

## Overview

Universal File Converter is a local desktop app that turns selected or dropped files into Markdown or JSON. The principal workflow is: choose a target and files, validate supported formats, select an output folder, extract structured content, serialize it, then save and report results. The graph separates the GUI/controller, extraction, and output-format layers. README claims and the sampled source support the major format families; unsampled implementation details are not expanded into separate components.

Main entry points: [`main.py`](https://github.com/xuligexu/convert-file/blob/main/main.py) (Conversion controller), [`core/extractor.py`](https://github.com/xuligexu/convert-file/blob/main/core/extractor.py) (Format extractors), [`core/to_markdown.py`](https://github.com/xuligexu/convert-file/blob/main/core/to_markdown.py) (Markdown serializer), [`core/to_json.py`](https://github.com/xuligexu/convert-file/blob/main/core/to_json.py) (JSON serializer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop app"]
  node_gui["Drop zones<br/>[main.py]"]
  node_file_input["File selection<br/>[main.py]"]
  node_validation["Format validation<br/>[main.py]"]
  node_controller["Conversion controller<br/>[main.py]"]
  node_destination["Output folder<br/>[main.py]"]
  node_completion["Completion status<br/>[main.py]"]
end

subgraph group_extract["Content extraction"]
  node_extractor["Format extractors<br/>[extractor.py]"]
  node_structured["Structured paragraphs<br/>[extractor.py]"]
end

subgraph group_outputs["Output formats"]
  node_markdown["Markdown serializer<br/>[to_markdown.py]"]
  node_json["JSON serializer<br/>[to_json.py]"]
end

node_user(("User"))
node_source_files["Local files"]
node_output_files["Markdown / JSON files"]

node_user -->|"chooses target"| node_gui
node_user -->|"adds files"| node_file_input
node_gui -->|"starts conversion"| node_controller
node_file_input -->|"provides paths"| node_validation
node_validation -->|"passes valid files"| node_controller
node_user -->|"chooses folder"| node_destination
node_controller -->|"extracts content"| node_extractor
node_source_files -->|"reads files"| node_extractor
node_extractor -->|"produces paragraphs"| node_structured
node_controller -->|"serializes as Markdown"| node_markdown
node_controller -->|"serializes as JSON"| node_json
node_markdown -->|"reads paragraphs"| node_structured
node_json -->|"reads paragraphs"| node_structured
node_controller -->|"writes results"| node_output_files
node_destination -->|"sets output location"| node_output_files
node_controller -->|"reports results"| node_completion
node_completion -->|"shows status"| node_user

click node_gui "https://github.com/xuligexu/convert-file/blob/main/main.py"
click node_file_input "https://github.com/xuligexu/convert-file/blob/main/main.py"
click node_validation "https://github.com/xuligexu/convert-file/blob/main/main.py"
click node_controller "https://github.com/xuligexu/convert-file/blob/main/main.py"
click node_destination "https://github.com/xuligexu/convert-file/blob/main/main.py"
click node_completion "https://github.com/xuligexu/convert-file/blob/main/main.py"
click node_extractor "https://github.com/xuligexu/convert-file/blob/main/core/extractor.py"
click node_structured "https://github.com/xuligexu/convert-file/blob/main/core/extractor.py"
click node_markdown "https://github.com/xuligexu/convert-file/blob/main/core/to_markdown.py"
click node_json "https://github.com/xuligexu/convert-file/blob/main/core/to_json.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_gui,node_file_input,node_validation,node_controller,node_destination,node_completion,node_user toneBlue
class node_extractor,node_structured toneAmber
class node_markdown,node_json toneMint
class node_source_files,node_output_files toneIndigo
```

## Components

### Desktop app

- [Drop zones](https://github.com/xuligexu/convert-file/blob/main/main.py): `main.py`
- [File selection](https://github.com/xuligexu/convert-file/blob/main/main.py): `main.py`
- [Format validation](https://github.com/xuligexu/convert-file/blob/main/main.py): `main.py`
- [Conversion controller](https://github.com/xuligexu/convert-file/blob/main/main.py): `main.py`
- [Output folder](https://github.com/xuligexu/convert-file/blob/main/main.py): `main.py`
- [Completion status](https://github.com/xuligexu/convert-file/blob/main/main.py): `main.py`

### Content extraction

- [Format extractors](https://github.com/xuligexu/convert-file/blob/main/core/extractor.py): `core/extractor.py`
- [Structured paragraphs](https://github.com/xuligexu/convert-file/blob/main/core/extractor.py): `core/extractor.py`

### Output formats

- [Markdown serializer](https://github.com/xuligexu/convert-file/blob/main/core/to_markdown.py): `core/to_markdown.py`
- [JSON serializer](https://github.com/xuligexu/convert-file/blob/main/core/to_json.py): `core/to_json.py`

### Other components

- **User**
- **Local files**
- **Markdown / JSON files**

## Connections

- User → Drop zones: chooses target (evidence: `README.md`)
- User → File selection: adds files (evidence: `README.md`)
- Drop zones → Conversion controller: starts conversion (evidence: `main.py`)
- File selection → Format validation: provides paths (evidence: `main.py`)
- Format validation → Conversion controller: passes valid files (evidence: `main.py`)
- User → Output folder: chooses folder (evidence: `README.md`)
- Conversion controller → Format extractors: extracts content (evidence: `main.py`)
- Local files → Format extractors: reads files (evidence: `core/extractor.py`)
- Format extractors → Structured paragraphs: produces paragraphs (evidence: `core/extractor.py`)
- Conversion controller → Markdown serializer: serializes as Markdown (evidence: `main.py`)
- Conversion controller → JSON serializer: serializes as JSON (evidence: `main.py`)
- Markdown serializer → Structured paragraphs: reads paragraphs (evidence: `core/to_markdown.py`)
- JSON serializer → Structured paragraphs: reads paragraphs (evidence: `core/to_json.py`)
- Conversion controller → Markdown / JSON files: writes results (evidence: `main.py`)
- Output folder → Markdown / JSON files: sets output location (evidence: `README.md`)
- Conversion controller → Completion status: reports results (evidence: `main.py`)
- Completion status → User: shows status (evidence: `main.py`)
