# debanjan110d/pdf-toolbox architecture

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

- Interactive diagram: https://gitdiagram.com/debanjan110d/pdf-toolbox
- Repository: https://github.com/debanjan110d/pdf-toolbox

## Overview

PDF Toolbox serves browser and Telegram users through a shared document-processing engine. In the web workflow, a user selects a PDF, the workspace reads metadata locally, and tool-specific hooks process and return files in the browser; compression is routed to the worker. In Telegram, updates reach the bot, which manages commands, uploads and action state, then returns processed documents. The README documents image conversion and other tools; unsampled wiring is shown only where supported by that documentation. The worker and webhook details are based on sampled routes and server code.

Main entry points: [`apps/web/src/components/DashboardHome.tsx`](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/components/DashboardHome.tsx) (Dashboard tools), [`packages/pdf-core/src/index.ts`](https://github.com/debanjan110d/pdf-toolbox/blob/main/packages/pdf-core/src/index.ts) (PDF operations), [`apps/telegram-bot/src/bot.ts`](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/bot.ts) (Bot runtime), [`services/pdf-worker/src/server.ts`](https://github.com/debanjan110d/pdf-toolbox/blob/main/services/pdf-worker/src/server.ts) (PDF worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser app"]
  node_web_app["Tool interface<br/>[page.tsx]"]
  node_dashboard["Dashboard tools<br/>[DashboardHome.tsx]"]
  node_workspace["File workspace<br/>[usePDFWorkspace.ts]"]
  node_compress_hook["Compression tool<br/>[usePDFCompress.ts]"]
  node_convert_hook["Conversion tool<br/>[usePDFConvert.ts]"]
  node_merge_hook["Merge tool<br/>[usePDFMerge.ts]"]
  node_split_hook["Split tool<br/>[usePDFSplit.ts]"]
  node_organize_hook["Page organizer<br/>[usePDFOrganize.ts]"]
  node_extract_hook["Text extraction"]
  node_compress_api["Compression proxy<br/>[route.ts]"]
  node_telegram_webhook["Update relay<br/>[route.ts]"]
end

subgraph group_bot["Telegram bot"]
  node_bot_runtime["Bot runtime<br/>[bot.ts]"]
  node_commands["Command handlers<br/>[commandHandlers.ts]"]
  node_actions["Action handlers<br/>[actionHandlers.ts]"]
  node_messages["Document handlers<br/>[messageHandlers.ts]"]
end

subgraph group_engine["PDF engine"]
  node_pdf_core["PDF operations<br/>[index.ts]"]
  node_shared_types["Shared types<br/>[index.ts]"]
end

subgraph group_worker["Worker service"]
  node_worker["PDF worker<br/>[server.ts]"]
end

node_browser_user(("Browser user"))
node_telegram_user(("Telegram user"))
node_telegram["Telegram service"]
node_ghostscript["Ghostscript"]
node_poppler["Poppler tools"]

node_browser_user -->|"uses"| node_web_app
node_web_app -->|"shows"| node_dashboard
node_dashboard -->|"loads files"| node_workspace
node_workspace -->|"reads metadata"| node_pdf_core
node_dashboard -->|"selects tool"| node_compress_hook
node_dashboard -->|"selects tool"| node_convert_hook
node_dashboard -->|"selects tool"| node_merge_hook
node_dashboard -->|"selects tool"| node_split_hook
node_dashboard -->|"selects tool"| node_organize_hook
node_dashboard -->|"selects tool"| node_extract_hook
node_convert_hook -->|"converts locally"| node_pdf_core
node_organize_hook -->|"organizes locally"| node_pdf_core
node_compress_hook -->|"submits file"| node_compress_api
node_compress_api -->|"forwards file"| node_worker
node_telegram_user -->|"sends updates"| node_telegram
node_telegram -->|"posts update"| node_telegram_webhook
node_telegram_webhook -->|"forwards update"| node_bot_runtime
node_bot_runtime -->|"dispatches commands"| node_commands
node_bot_runtime -->|"dispatches actions"| node_actions
node_bot_runtime -->|"dispatches messages"| node_messages
node_messages -->|"processes locally"| node_pdf_core
node_commands -->|"merges documents"| node_pdf_core
node_messages -->|"requests image export"| node_worker
node_worker -.->|"compresses with"| node_ghostscript
node_worker -.->|"renders with"| node_poppler

click node_web_app "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/app/page.tsx"
click node_dashboard "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/components/DashboardHome.tsx"
click node_workspace "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFWorkspace.ts"
click node_compress_hook "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFCompress.ts"
click node_convert_hook "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFConvert.ts"
click node_merge_hook "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFMerge.ts"
click node_split_hook "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFSplit.ts"
click node_organize_hook "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFOrganize.ts"
click node_extract_hook "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFExtractText.ts"
click node_compress_api "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/app/api/compress/route.ts"
click node_telegram_webhook "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/app/api/telegram-webhook/route.ts"
click node_bot_runtime "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/bot.ts"
click node_commands "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/handlers/commandHandlers.ts"
click node_actions "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/handlers/actionHandlers.ts"
click node_messages "https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/handlers/messageHandlers.ts"
click node_pdf_core "https://github.com/debanjan110d/pdf-toolbox/blob/main/packages/pdf-core/src/index.ts"
click node_shared_types "https://github.com/debanjan110d/pdf-toolbox/blob/main/packages/shared/src/index.ts"
click node_worker "https://github.com/debanjan110d/pdf-toolbox/blob/main/services/pdf-worker/src/server.ts"

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_web_app,node_dashboard,node_workspace,node_compress_hook,node_convert_hook,node_merge_hook,node_split_hook,node_organize_hook,node_extract_hook,node_compress_api,node_telegram_webhook,node_browser_user,node_telegram_user toneBlue
class node_bot_runtime,node_commands,node_actions,node_messages toneAmber
class node_pdf_core,node_shared_types toneMint
class node_worker toneRose
class node_telegram,node_ghostscript,node_poppler toneIndigo
```

## Components

### Browser app

- [Tool interface](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [Dashboard tools](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/components/DashboardHome.tsx): `apps/web/src/components/DashboardHome.tsx`
- [File workspace](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFWorkspace.ts): `apps/web/src/hooks/usePDFWorkspace.ts`
- [Compression tool](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFCompress.ts): `apps/web/src/hooks/usePDFCompress.ts`
- [Conversion tool](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFConvert.ts): `apps/web/src/hooks/usePDFConvert.ts`
- [Merge tool](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFMerge.ts): `apps/web/src/hooks/usePDFMerge.ts`
- [Split tool](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFSplit.ts): `apps/web/src/hooks/usePDFSplit.ts`
- [Page organizer](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFOrganize.ts): `apps/web/src/hooks/usePDFOrganize.ts`
- [Text extraction](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/hooks/usePDFExtractText.ts): `apps/web/src/hooks/usePDFExtractText.ts`
- [Compression proxy](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/app/api/compress/route.ts): `apps/web/src/app/api/compress/route.ts`
- [Update relay](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/web/src/app/api/telegram-webhook/route.ts): `apps/web/src/app/api/telegram-webhook/route.ts`

### Telegram bot

- [Bot runtime](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/bot.ts): `apps/telegram-bot/src/bot.ts`
- [Command handlers](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/handlers/commandHandlers.ts): `apps/telegram-bot/src/handlers/commandHandlers.ts`
- [Action handlers](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/handlers/actionHandlers.ts): `apps/telegram-bot/src/handlers/actionHandlers.ts`
- [Document handlers](https://github.com/debanjan110d/pdf-toolbox/blob/main/apps/telegram-bot/src/handlers/messageHandlers.ts): `apps/telegram-bot/src/handlers/messageHandlers.ts`

### PDF engine

- [PDF operations](https://github.com/debanjan110d/pdf-toolbox/blob/main/packages/pdf-core/src/index.ts): `packages/pdf-core/src/index.ts`
- [Shared types](https://github.com/debanjan110d/pdf-toolbox/blob/main/packages/shared/src/index.ts): `packages/shared/src/index.ts`

### Worker service

- [PDF worker](https://github.com/debanjan110d/pdf-toolbox/blob/main/services/pdf-worker/src/server.ts): `services/pdf-worker/src/server.ts`

### Other components

- **Browser user**
- **Telegram user**
- **Telegram service**
- **Ghostscript**
- **Poppler tools**

## Connections

- Browser user → Tool interface: uses
- Tool interface → Dashboard tools: shows
- Dashboard tools → File workspace: loads files
- File workspace → PDF operations: reads metadata
- Dashboard tools → Compression tool: selects tool
- Dashboard tools → Conversion tool: selects tool
- Dashboard tools → Merge tool: selects tool
- Dashboard tools → Split tool: selects tool
- Dashboard tools → Page organizer: selects tool
- Dashboard tools → Text extraction: selects tool
- Conversion tool → PDF operations: converts locally
- Page organizer → PDF operations: organizes locally
- Compression tool → Compression proxy: submits file
- Compression proxy → PDF worker: forwards file
- Telegram user → Telegram service: sends updates
- Telegram service → Update relay: posts update
- Update relay → Bot runtime: forwards update
- Bot runtime → Command handlers: dispatches commands
- Bot runtime → Action handlers: dispatches actions
- Bot runtime → Document handlers: dispatches messages
- Document handlers → PDF operations: processes locally
- Command handlers → PDF operations: merges documents
- Document handlers → PDF worker: requests image export
- PDF worker → Ghostscript: compresses with
- PDF worker → Poppler tools: renders with