# tithean/straight-convertor architecture

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

- Interactive diagram: https://gitdiagram.com/tithean/straight-convertor
- Repository: https://github.com/tithean/straight-convertor

## Overview

Straight is a temporary, request/response document converter: users select a supported format, upload one file, and download the converted result. The browser fetches backend capabilities, validates the selection, tracks upload/conversion state, and presents the download. The API validates and stages the upload, dispatches an isolated conversion worker, then removes its temporary workspace after delivery. Documented conversion engines include LibreOffice for Office-to-PDF and PDFium plus python-pptx for PDF-to-PPTX. Edges reflect shown source references or README documentation; engine wiring beyond those statements is not inferred.

Main entry points: [`frontend/src/app/App.tsx`](https://github.com/tithean/straight-convertor/blob/main/frontend/src/app/App.tsx) (Page flow), [`backend/app/services/conversion_service.py`](https://github.com/tithean/straight-convertor/blob/main/backend/app/services/conversion_service.py) (Conversion service), [`backend/app/api/routes/conversions.py`](https://github.com/tithean/straight-convertor/blob/main/backend/app/api/routes/conversions.py) (Conversion routes), [`backend/app/converters/registry.py`](https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/registry.py) (Conversion registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser interface"]
  node_app["Page flow<br/>[App.tsx]"]
  node_fileutils["Selection utilities<br/>[fileUtils.ts]"]
  node_dropzone["File dropzone<br/>[FileDropzone.tsx]"]
  node_formatselect["Format selector<br/>[FormatSelect.tsx]"]
  node_status["Conversion status"]
  node_hook["Conversion state<br/>[useConversion.ts]"]
  node_clientapi["HTTP client<br/>[api.ts]"]
end

subgraph group_api["HTTP API"]
  node_api_routes["Conversion routes<br/>[conversions.py]"]
  node_appmain["App setup<br/>[main.py]"]
end

subgraph group_conversion["Conversion runtime"]
  node_service["Conversion service"]
  node_registry["Conversion registry<br/>[registry.py]"]
  node_worker["Worker process<br/>[worker.py]"]
end

subgraph group_safety["Limits and lifecycle"]
  node_config["Runtime settings<br/>[config.py]"]
  node_bodylimit["Request body limit<br/>[limited_body.py]"]
  node_validation["File validation<br/>[file_validation.py]"]
  node_workspace["Temporary workspaces<br/>[temporary_files.py]"]
end

subgraph group_engines["Conversion engines"]
  node_office["Office converter<br/>[office_to_pdf.py]"]
  node_pdfpptx["PDF to slides<br/>[pdf_to_pptx.py]"]
end

node_user(("User"))
node_libreoffice["LibreOffice"]
node_pdfengines["PDFium + python-pptx"]

node_user -->|"selects file"| node_app
node_app -->|"validates selection"| node_fileutils
node_app -->|"renders"| node_dropzone
node_app -->|"renders"| node_formatselect
node_app -->|"renders"| node_status
node_app -->|"starts conversion"| node_hook
node_hook -->|"sends request"| node_clientapi
node_clientapi -->|"calls API"| node_api_routes
node_user -->|"downloads result"| node_status
node_appmain -->|"registers routes"| node_api_routes
node_appmain -->|"installs middleware"| node_bodylimit
node_appmain -->|"loads settings"| node_config
node_appmain -->|"cleans stale files"| node_workspace
node_api_routes -->|"invokes conversion"| node_service
node_api_routes -->|"lists formats"| node_registry
node_api_routes -->|"cleans after delivery"| node_workspace
node_service -->|"finds conversion"| node_registry
node_service -->|"validates upload"| node_validation
node_service -->|"stages and removes files"| node_workspace
node_service -->|"starts subprocess"| node_worker
node_registry -->|"selects converter"| node_office
node_registry -->|"selects converter"| node_pdfpptx
node_worker -->|"dispatches conversion"| node_registry
node_office -->|"converts Office files"| node_libreoffice
node_pdfpptx -->|"renders and builds slides"| node_pdfengines

click node_app "https://github.com/tithean/straight-convertor/blob/main/frontend/src/app/App.tsx"
click node_fileutils "https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/fileUtils.ts"
click node_dropzone "https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/components/FileDropzone.tsx"
click node_formatselect "https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/components/FormatSelect.tsx"
click node_status "https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/components/ConversionStatus.tsx"
click node_hook "https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/useConversion.ts"
click node_clientapi "https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/api.ts"
click node_api_routes "https://github.com/tithean/straight-convertor/blob/main/backend/app/api/routes/conversions.py"
click node_appmain "https://github.com/tithean/straight-convertor/blob/main/backend/app/main.py"
click node_service "https://github.com/tithean/straight-convertor/blob/main/backend/app/services/conversion_service.py"
click node_registry "https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/registry.py"
click node_worker "https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/worker.py"
click node_office "https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/office_to_pdf.py"
click node_pdfpptx "https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/pdf_to_pptx.py"
click node_config "https://github.com/tithean/straight-convertor/blob/main/backend/app/core/config.py"
click node_bodylimit "https://github.com/tithean/straight-convertor/blob/main/backend/app/utils/limited_body.py"
click node_validation "https://github.com/tithean/straight-convertor/blob/main/backend/app/utils/file_validation.py"
click node_workspace "https://github.com/tithean/straight-convertor/blob/main/backend/app/utils/temporary_files.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_app,node_fileutils,node_dropzone,node_formatselect,node_status,node_hook,node_clientapi,node_user toneBlue
class node_api_routes,node_appmain toneAmber
class node_service,node_registry,node_worker toneMint
class node_config,node_bodylimit,node_validation,node_workspace toneRose
class node_office,node_pdfpptx,node_libreoffice,node_pdfengines toneIndigo
```

## Components

### Browser interface

- [Page flow](https://github.com/tithean/straight-convertor/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Selection utilities](https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/fileUtils.ts): `frontend/src/features/conversion/fileUtils.ts`
- [File dropzone](https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/components/FileDropzone.tsx): `frontend/src/features/conversion/components/FileDropzone.tsx`
- [Format selector](https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/components/FormatSelect.tsx): `frontend/src/features/conversion/components/FormatSelect.tsx`
- [Conversion status](https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/components/ConversionStatus.tsx): `frontend/src/features/conversion/components/ConversionStatus.tsx`
- [Conversion state](https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/useConversion.ts): `frontend/src/features/conversion/useConversion.ts`
- [HTTP client](https://github.com/tithean/straight-convertor/blob/main/frontend/src/features/conversion/api.ts): `frontend/src/features/conversion/api.ts`

### HTTP API

- [Conversion routes](https://github.com/tithean/straight-convertor/blob/main/backend/app/api/routes/conversions.py): `backend/app/api/routes/conversions.py`
- [App setup](https://github.com/tithean/straight-convertor/blob/main/backend/app/main.py): `backend/app/main.py`

### Conversion runtime

- [Conversion service](https://github.com/tithean/straight-convertor/blob/main/backend/app/services/conversion_service.py): `backend/app/services/conversion_service.py`
- [Conversion registry](https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/registry.py): `backend/app/converters/registry.py`
- [Worker process](https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/worker.py): `backend/app/converters/worker.py`

### Limits and lifecycle

- [Runtime settings](https://github.com/tithean/straight-convertor/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Request body limit](https://github.com/tithean/straight-convertor/blob/main/backend/app/utils/limited_body.py): `backend/app/utils/limited_body.py`
- [File validation](https://github.com/tithean/straight-convertor/blob/main/backend/app/utils/file_validation.py): `backend/app/utils/file_validation.py`
- [Temporary workspaces](https://github.com/tithean/straight-convertor/blob/main/backend/app/utils/temporary_files.py): `backend/app/utils/temporary_files.py`

### Conversion engines

- [Office converter](https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/office_to_pdf.py): `backend/app/converters/office_to_pdf.py`
- [PDF to slides](https://github.com/tithean/straight-convertor/blob/main/backend/app/converters/pdf_to_pptx.py): `backend/app/converters/pdf_to_pptx.py`

### Other components

- **User**
- **LibreOffice**
- **PDFium + python-pptx**

## Connections

- User → Page flow: selects file (evidence: `README.md`)
- Page flow → Selection utilities: validates selection (evidence: `frontend/src/app/App.tsx`)
- Page flow → File dropzone: renders (evidence: `frontend/src/app/App.tsx`)
- Page flow → Format selector: renders (evidence: `frontend/src/app/App.tsx`)
- Page flow → Conversion status: renders (evidence: `frontend/src/app/App.tsx`)
- Page flow → Conversion state: starts conversion (evidence: `frontend/src/app/App.tsx`)
- Conversion state → HTTP client: sends request (evidence: `frontend/src/features/conversion/useConversion.ts`)
- HTTP client → Conversion routes: calls API (evidence: `README.md`)
- User → Conversion status: downloads result (evidence: `README.md`)
- App setup → Conversion routes: registers routes (evidence: `backend/app/main.py`)
- App setup → Request body limit: installs middleware (evidence: `backend/app/main.py`)
- App setup → Runtime settings: loads settings (evidence: `backend/app/main.py`)
- App setup → Temporary workspaces: cleans stale files (evidence: `backend/app/main.py`)
- Conversion routes → Conversion service: invokes conversion (evidence: `backend/app/api/routes/conversions.py`)
- Conversion routes → Conversion registry: lists formats (evidence: `backend/app/api/routes/conversions.py`)
- Conversion routes → Temporary workspaces: cleans after delivery (evidence: `backend/app/api/routes/conversions.py`)
- Conversion service → Conversion registry: finds conversion (evidence: `backend/app/services/conversion_service.py`)
- Conversion service → File validation: validates upload (evidence: `backend/app/services/conversion_service.py`)
- Conversion service → Temporary workspaces: stages and removes files (evidence: `backend/app/services/conversion_service.py`)
- Conversion service → Worker process: starts subprocess (evidence: `backend/app/services/conversion_service.py`)
- Conversion registry → Office converter: selects converter (evidence: `backend/app/converters/registry.py`)
- Conversion registry → PDF to slides: selects converter (evidence: `backend/app/converters/registry.py`)
- Worker process → Conversion registry: dispatches conversion (evidence: `backend/app/converters/worker.py`)
- Office converter → LibreOffice: converts Office files (evidence: `README.md`)
- PDF to slides → PDFium + python-pptx: renders and builds slides (evidence: `README.md`)