# forward-future/folio architecture

> Architecture diagram of the GitHub repository forward-future/folio, 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/forward-future/folio
- Repository: https://github.com/forward-future/folio

## Overview

Folio is a cross-platform desktop PDF reader. The main workflow is opening a PDF (or converting a supported Word document or webpage), reading and navigating it, then searching, annotating, signing, or asking AI about its contents. The graph also preserves OCR, document editing/history, and desktop integrations. Several feature modules are identified by the tree and README but were not sampled; those branches are included at directory or module paths, with relationships shown only where the README or excerpts support them.

Main entry points: [`src/App.tsx`](https://github.com/forward-future/folio/blob/main/src/App.tsx) (Reader interface), [`src/lib/ocr/session/OcrSession.ts`](https://github.com/forward-future/folio/blob/main/src/lib/ocr/session/OcrSession.ts) (OCR sessions), [`electron/ai.cjs`](https://github.com/forward-future/folio/blob/main/electron/ai.cjs) (AI orchestration), [`electron/main.cjs`](https://github.com/forward-future/folio/blob/main/electron/main.cjs) (Electron shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and input"]
  node_shell["Electron shell<br/>[main.cjs]"]
  node_webpage["Webpage conversion<br/>[webpage.cjs]"]
  node_word["Word conversion<br/>[convert.cjs]"]
  node_word_worker["DOCX parser<br/>[docx-worker.cjs]"]
  node_pdf_input["PDF input<br/>[pdfInput.ts]"]
  node_network["Network safeguards<br/>[network.cjs]"]
end

subgraph group_reading["Reading and navigation"]
  node_tabs["Document tabs<br/>[documentTabs.ts]"]
  node_reader_app["Reader interface<br/>[App.tsx]"]
  node_pdf_viewer["PDF viewer<br/>[viewer.ts]"]
  node_library[("Recent library<br/>[recent.ts]")]
end

subgraph group_documents["Document tools"]
  node_markup["Highlights and notes<br/>[markup.ts]"]
  node_editor["Text and image editing"]
  node_signatures["Signatures<br/>[signatures.ts]"]
  node_history["Version history<br/>[versionHistory.ts]"]
  node_printing["Print workflow<br/>[printing.cjs]"]
end

subgraph group_recognition["OCR and search"]
  node_ocr_session["OCR sessions<br/>[OcrSession.ts]"]
  node_ocr_scan["Scan detection<br/>[scan.ts]"]
  node_ocr_worker["OCR recognition<br/>[ocrWorker.ts]"]
  node_ocr_store[("OCR cache<br/>[ocrStore.ts]")]
  node_search["Document search<br/>[index.ts]"]
end

subgraph group_assistant["AI assistance"]
  node_ai_panel["Ask AI panel<br/>[AiPanel.tsx]"]
  node_ai_service["AI orchestration<br/>[ai.cjs]"]
  node_ai_providers["AI providers<br/>[openrouter.cjs]"]
end

node_user(("Reader"))
node_ai_services_external(("AI services"))

node_user -->|"opens documents"| node_shell
node_user -->|"reads and edits"| node_reader_app
node_shell -->|"routes Word files"| node_word
node_word -->|"delegates parsing"| node_word_worker
node_user -->|"opens webpage URL"| node_webpage
node_reader_app -->|"uses viewer"| node_pdf_viewer
node_reader_app -->|"opens PDFs"| node_pdf_input
node_reader_app -->|"manages document tabs"| node_tabs
node_reader_app -->|"reads saved view"| node_library
node_reader_app -->|"annotates PDFs"| node_markup
node_reader_app -->|"edits PDF content"| node_editor
node_reader_app -->|"signs documents"| node_signatures
node_reader_app -->|"reviews changes"| node_history
node_reader_app -->|"prints documents"| node_printing
node_reader_app -->|"creates OCR session"| node_ocr_session
node_ocr_session -->|"loads and saves pages"| node_ocr_store
node_ocr_session -.->|"identifies scanned pages"| node_ocr_scan
node_ocr_session -.->|"requests recognition"| node_ocr_worker
node_reader_app -->|"searches document"| node_search
node_ai_panel -->|"sends questions"| node_ai_service
node_ai_service -->|"dispatches requests"| node_ai_providers
node_ai_service -->|"uses network controls"| node_network
node_ai_providers -->|"requests answers"| node_ai_services_external

click node_shell "https://github.com/forward-future/folio/blob/main/electron/main.cjs"
click node_webpage "https://github.com/forward-future/folio/blob/main/electron/webpage.cjs"
click node_word "https://github.com/forward-future/folio/blob/main/electron/convert.cjs"
click node_word_worker "https://github.com/forward-future/folio/blob/main/electron/docx-worker.cjs"
click node_tabs "https://github.com/forward-future/folio/blob/main/src/documentTabs.ts"
click node_reader_app "https://github.com/forward-future/folio/blob/main/src/App.tsx"
click node_pdf_viewer "https://github.com/forward-future/folio/blob/main/src/viewer.ts"
click node_pdf_input "https://github.com/forward-future/folio/blob/main/src/pdfInput.ts"
click node_library "https://github.com/forward-future/folio/blob/main/src/recent.ts"
click node_markup "https://github.com/forward-future/folio/blob/main/src/markup.ts"
click node_editor "https://github.com/forward-future/folio/blob/main/src/contentEditor.worker.ts"
click node_signatures "https://github.com/forward-future/folio/blob/main/src/signatures.ts"
click node_history "https://github.com/forward-future/folio/blob/main/src/versionHistory.ts"
click node_printing "https://github.com/forward-future/folio/blob/main/electron/printing.cjs"
click node_ocr_session "https://github.com/forward-future/folio/blob/main/src/lib/ocr/session/OcrSession.ts"
click node_ocr_scan "https://github.com/forward-future/folio/blob/main/src/lib/ocr/text/scan.ts"
click node_ocr_worker "https://github.com/forward-future/folio/blob/main/src/ocrWorker.ts"
click node_ocr_store "https://github.com/forward-future/folio/blob/main/src/lib/ocr/storage/ocrStore.ts"
click node_search "https://github.com/forward-future/folio/blob/main/src/lib/search/index.ts"
click node_ai_panel "https://github.com/forward-future/folio/blob/main/src/AiPanel.tsx"
click node_ai_service "https://github.com/forward-future/folio/blob/main/electron/ai.cjs"
click node_ai_providers "https://github.com/forward-future/folio/blob/main/electron/openrouter.cjs"
click node_network "https://github.com/forward-future/folio/blob/main/electron/network.cjs"

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_shell,node_webpage,node_word,node_word_worker,node_pdf_input,node_network toneBlue
class node_tabs,node_reader_app,node_pdf_viewer,node_library toneAmber
class node_markup,node_editor,node_signatures,node_history,node_printing toneMint
class node_ocr_session,node_ocr_scan,node_ocr_worker,node_ocr_store,node_search toneRose
class node_ai_panel,node_ai_service,node_ai_providers,node_user,node_ai_services_external toneIndigo
```

## Components

### Desktop and input

- [Electron shell](https://github.com/forward-future/folio/blob/main/electron/main.cjs): `electron/main.cjs`
- [Webpage conversion](https://github.com/forward-future/folio/blob/main/electron/webpage.cjs): `electron/webpage.cjs`
- [Word conversion](https://github.com/forward-future/folio/blob/main/electron/convert.cjs): `electron/convert.cjs`
- [DOCX parser](https://github.com/forward-future/folio/blob/main/electron/docx-worker.cjs): `electron/docx-worker.cjs`
- [PDF input](https://github.com/forward-future/folio/blob/main/src/pdfInput.ts): `src/pdfInput.ts`
- [Network safeguards](https://github.com/forward-future/folio/blob/main/electron/network.cjs): `electron/network.cjs`

### Reading and navigation

- [Document tabs](https://github.com/forward-future/folio/blob/main/src/documentTabs.ts): `src/documentTabs.ts`
- [Reader interface](https://github.com/forward-future/folio/blob/main/src/App.tsx): `src/App.tsx`
- [PDF viewer](https://github.com/forward-future/folio/blob/main/src/viewer.ts): `src/viewer.ts`
- [Recent library](https://github.com/forward-future/folio/blob/main/src/recent.ts): `src/recent.ts`

### Document tools

- [Highlights and notes](https://github.com/forward-future/folio/blob/main/src/markup.ts): `src/markup.ts`
- [Text and image editing](https://github.com/forward-future/folio/blob/main/src/contentEditor.worker.ts): `src/contentEditor.worker.ts`
- [Signatures](https://github.com/forward-future/folio/blob/main/src/signatures.ts): `src/signatures.ts`
- [Version history](https://github.com/forward-future/folio/blob/main/src/versionHistory.ts): `src/versionHistory.ts`
- [Print workflow](https://github.com/forward-future/folio/blob/main/electron/printing.cjs): `electron/printing.cjs`

### OCR and search

- [OCR sessions](https://github.com/forward-future/folio/blob/main/src/lib/ocr/session/OcrSession.ts): `src/lib/ocr/session/OcrSession.ts`
- [Scan detection](https://github.com/forward-future/folio/blob/main/src/lib/ocr/text/scan.ts): `src/lib/ocr/text/scan.ts`
- [OCR recognition](https://github.com/forward-future/folio/blob/main/src/ocrWorker.ts): `src/ocrWorker.ts`
- [OCR cache](https://github.com/forward-future/folio/blob/main/src/lib/ocr/storage/ocrStore.ts): `src/lib/ocr/storage/ocrStore.ts`
- [Document search](https://github.com/forward-future/folio/blob/main/src/lib/search/index.ts): `src/lib/search/index.ts`

### AI assistance

- [Ask AI panel](https://github.com/forward-future/folio/blob/main/src/AiPanel.tsx): `src/AiPanel.tsx`
- [AI orchestration](https://github.com/forward-future/folio/blob/main/electron/ai.cjs): `electron/ai.cjs`
- [AI providers](https://github.com/forward-future/folio/blob/main/electron/openrouter.cjs): `electron/openrouter.cjs`

### Other components

- **Reader**
- **AI services**

## Connections

- Reader → Electron shell: opens documents
- Reader → Reader interface: reads and edits
- Electron shell → Word conversion: routes Word files (evidence: `electron/main.cjs`)
- Word conversion → DOCX parser: delegates parsing (evidence: `electron/docx-worker.cjs`)
- Reader → Webpage conversion: opens webpage URL
- Reader interface → PDF viewer: uses viewer (evidence: `src/App.tsx`)
- Reader interface → PDF input: opens PDFs (evidence: `src/App.tsx`)
- Reader interface → Document tabs: manages document tabs (evidence: `src/App.tsx`)
- Reader interface → Recent library: reads saved view (evidence: `src/App.tsx`)
- Reader interface → Highlights and notes: annotates PDFs (evidence: `src/App.tsx`)
- Reader interface → Text and image editing: edits PDF content
- Reader interface → Signatures: signs documents (evidence: `src/App.tsx`)
- Reader interface → Version history: reviews changes (evidence: `src/App.tsx`)
- Reader interface → Print workflow: prints documents
- Reader interface → OCR sessions: creates OCR session (evidence: `src/App.tsx`)
- OCR sessions → OCR cache: loads and saves pages (evidence: `src/lib/ocr/session/OcrSession.ts`)
- OCR sessions → Scan detection: identifies scanned pages
- OCR sessions → OCR recognition: requests recognition
- Reader interface → Document search: searches document
- Ask AI panel → AI orchestration: sends questions
- AI orchestration → AI providers: dispatches requests (evidence: `electron/ai.cjs`)
- AI orchestration → Network safeguards: uses network controls (evidence: `electron/ai.cjs`)
- AI providers → AI services: requests answers (evidence: `electron/openrouter.cjs`)