# dassougoto/pdfmint architecture

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

- Interactive diagram: https://gitdiagram.com/dassougoto/pdfmint
- Repository: https://github.com/dassougoto/pdfmint

## Overview

1. **Project shape**
   - This is a **Next.js App Router** application in **TypeScript**.
   - The repo is organized as a small **PDF tools suite**: marketing/home pages plus individual tool workflows for PDF compression, merging, and splitting.

2. **Route-level structure**
   - `app/(home)` contains the public landing experience, with its own layout and the top-level home page.
   - `app/tools/*` contains the actual product/tool pages:
     - `/tools/compress-pdf`
     - `/tools/merge-pdf`
     - `/tools/split-pdf`
   - `app/api/*` contains server-side endpoints for PDF processing:
     - `/api/compress-pdf`
     - `/api/merge-pdf`

3. **Main user-facing flow**
   - Users likely start on the home page, browse the tool catalog, then enter a specific tool page.
   - Tool pages appear to host the interactive workspace for file selection, configuration, and downloading results.
   - For operations that require server-side processing, the UI calls the corresponding API route.

4. **Server-side processing boundary**
   - The API routes are the key backend boundary in this app.
   - PDF transformation logic is not embedded in the pages; it is centralized in `lib/` helpers and invoked by the route handlers.
   - This keeps the UI layer separate from the file-processing layer, which is important for drawing the architecture diagram.

5. **Core domain logic**
   - `lib/process-pdf.ts`, `lib/pdf-utils.ts`, and `lib/compression-settings.ts` are the likely core processing modules.
   - `lib/all-pdf-tools.ts`, `lib/features.ts`, and `lib/steps.ts` appear to hold tool metadata, feature copy, and workflow step definitions used by the UI.
   - `lib/types.ts` defines shared TypeScript types across the app.

6. **Shared UI system**
   - `components/common` holds cross-cutting layout and workflow components such as:
     - navigation/footer/theme toggle
     - tool cards and file cards
     - workspace and tool page shells
     - download-page variants
   - `components/ui` contains reusable primitive UI components, likely used throughout the app shell and tool interfaces.

7. **Home/marketing subsystem**
   - `components/home/*` and `app/(home)/*` make up the public marketing landing page.
   - These sections provide the hero, feature explanation, “how it works,” tools overview, and call-to-action content.
   - This part of the app is presentation-heavy and separate from the actual PDF execution path.

8. **Tool workspace subsystem**
   - `components/common/tool-page.tsx`, `tool-client.tsx`, `workspace.tsx`, and `file-card.tsx` suggest a dedicated interactive workspace for each tool.
   - This layer manages user interaction: file upload/selection, tool-specific controls, and presenting output/download state.
   - The workspace is the main client-side boundary between the user and PDF processing.

9. **Output/download flow**
   - `components/common/download-page.tsx` and `download-page-01.tsx` indicate a dedicated result screen or result section after processing.
   - The flow likely ends with a generated download link or downloadable artifact returned from the API or processing layer.

10. **Theming and global shell**
    - `app/layout.tsx`, `app/globals.css`, `components/ui/theme-provider.tsx`, and `components/common/theme-toggle.tsx` show that the app has a global shell with theme support.
    - `components/common/navbar.tsx`, `mobile_menu.tsx`, and `footer.tsx` form the shared site chrome around both marketing and tool pages.

11. **Likely deployment/runtime model**
    - Because it uses Next.js App Router with route handlers, the app is designed to run in the standard Next.js runtime, with API routes deployed alongside the UI.
    - There is no evidence of a separate database, queue, or external service; the architecture appears to be **self-contained** and oriented around file-based PDF transformations.

12. **What to draw in an architecture diagram**
    - A good diagram would show:
      - **Browser/UI layer**: home pages, tool pages, workspace, download view
      - **Shared presentation layer**: common components and UI primitives
      - **Server/API layer**: compress and merge route handlers
      - **Domain/library layer**: PDF utilities, compression settings, tool metadata, workflow steps
    - The main arrows should go from the tool workspace to the API routes, then to `lib/` processing helpers, and back to the UI as downloadable results.

Main entry points: [`components/common`](https://github.com/dassougoto/pdfmint/tree/main/components/common) (Tool shell), [`app/(home)/page.tsx`](https://github.com/dassougoto/pdfmint/blob/main/app/(home)/page.tsx) (Home page), [`app/tools/layout.tsx`](https://github.com/dassougoto/pdfmint/blob/main/app/tools/layout.tsx) (Tools layout), [`lib/process-pdf.ts`](https://github.com/dassougoto/pdfmint/blob/main/lib/process-pdf.ts) (PDF engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_app_layout["Root layout<br/>next layout<br/>[layout.tsx]"]
  node_home_layout["Home layout<br/>route layout<br/>[layout.tsx]"]
  node_home_page["Home page<br/>landing page<br/>[page.tsx]"]
  node_tools_layout["Tools layout<br/>route layout<br/>[layout.tsx]"]
  node_compress_page["Compress page<br/>tool page<br/>[page.tsx]"]
  node_merge_page["Merge page<br/>tool page<br/>[page.tsx]"]
  node_split_page["Split page<br/>tool page<br/>[page.tsx]"]
  node_compress_api["Compress API<br/>route handler<br/>[route.ts]"]
  node_merge_api["Merge API<br/>route handler<br/>[route.ts]"]
end

subgraph group_components["Components"]
  node_home_sections["Home sections<br/>marketing ui"]
  node_site_chrome["Site chrome<br/>shared shell"]
  node_tool_shell["Tool shell<br/>workspace ui"]
  node_file_ui["File UI<br/>upload/result ui"]
  node_tool_cards["Tool cards<br/>catalog ui<br/>[tool-card.tsx]"]
  node_ui_primitives["UI primitives<br/>design system"]
end

subgraph group_lib["Domain lib"]
  node_pdf_engine{{"PDF engine<br/>processing lib<br/>[process-pdf.ts]"}}
  node_pdf_utils{{"PDF utils<br/>processing lib<br/>[pdf-utils.ts]"}}
  node_pdf_config["Compression config<br/>settings"]
  node_tool_meta["Tool metadata<br/>catalog data<br/>[all-pdf-tools.ts]"]
  node_shared_types["Shared types<br/>[types.ts]"]
end

node_app_layout -->|"wraps"| node_home_layout
node_app_layout -->|"wraps"| node_tools_layout
node_app_layout -->|"uses"| node_site_chrome
node_home_layout -->|"hosts"| node_home_page
node_home_page -->|"composes"| node_home_sections
node_home_page -->|"shows"| node_tool_cards
node_home_page -->|"reads"| node_tool_meta
node_tools_layout -->|"hosts"| node_compress_page
node_tools_layout -->|"hosts"| node_merge_page
node_tools_layout -->|"hosts"| node_split_page
node_compress_page -->|"uses"| node_tool_shell
node_merge_page -->|"uses"| node_tool_shell
node_split_page -->|"uses"| node_tool_shell
node_tool_shell -->|"renders"| node_file_ui
node_tool_shell -->|"builds on"| node_ui_primitives
node_file_ui -->|"builds on"| node_ui_primitives
node_compress_page -->|"calls"| node_compress_api
node_merge_page -->|"calls"| node_merge_api
node_compress_api -->|"invokes"| node_pdf_engine
node_merge_api -->|"invokes"| node_pdf_engine
node_pdf_engine -->|"depends on"| node_pdf_utils
node_pdf_engine -->|"uses"| node_pdf_config
node_tool_shell -->|"uses"| node_shared_types
node_tool_meta -->|"defines"| node_shared_types
node_home_sections -->|"references"| node_tool_meta
node_site_chrome -->|"builds on"| node_ui_primitives

click node_app_layout "https://github.com/dassougoto/pdfmint/blob/main/app/layout.tsx"
click node_home_layout "https://github.com/dassougoto/pdfmint/blob/main/app/(home)/layout.tsx"
click node_home_page "https://github.com/dassougoto/pdfmint/blob/main/app/(home)/page.tsx"
click node_tools_layout "https://github.com/dassougoto/pdfmint/blob/main/app/tools/layout.tsx"
click node_compress_page "https://github.com/dassougoto/pdfmint/blob/main/app/tools/compress-pdf/page.tsx"
click node_merge_page "https://github.com/dassougoto/pdfmint/blob/main/app/tools/merge-pdf/page.tsx"
click node_split_page "https://github.com/dassougoto/pdfmint/blob/main/app/tools/split-pdf/page.tsx"
click node_compress_api "https://github.com/dassougoto/pdfmint/blob/main/app/api/compress-pdf/route.ts"
click node_merge_api "https://github.com/dassougoto/pdfmint/blob/main/app/api/merge-pdf/route.ts"
click node_home_sections "https://github.com/dassougoto/pdfmint/tree/main/components/home"
click node_site_chrome "https://github.com/dassougoto/pdfmint/tree/main/components/common"
click node_tool_shell "https://github.com/dassougoto/pdfmint/tree/main/components/common"
click node_file_ui "https://github.com/dassougoto/pdfmint/tree/main/components/common"
click node_tool_cards "https://github.com/dassougoto/pdfmint/blob/main/components/common/tool-card.tsx"
click node_ui_primitives "https://github.com/dassougoto/pdfmint/tree/main/components/ui"
click node_pdf_engine "https://github.com/dassougoto/pdfmint/blob/main/lib/process-pdf.ts"
click node_pdf_utils "https://github.com/dassougoto/pdfmint/blob/main/lib/pdf-utils.ts"
click node_pdf_config "https://github.com/dassougoto/pdfmint/blob/main/lib/compression-settings.ts"
click node_tool_meta "https://github.com/dassougoto/pdfmint/blob/main/lib/all-pdf-tools.ts"
click node_shared_types "https://github.com/dassougoto/pdfmint/blob/main/lib/types.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_app_layout,node_home_layout,node_home_page,node_tools_layout,node_compress_page,node_merge_page,node_split_page,node_compress_api,node_merge_api toneBlue
class node_home_sections,node_site_chrome,node_tool_shell,node_file_ui,node_tool_cards,node_ui_primitives toneAmber
class node_pdf_engine,node_pdf_utils,node_pdf_config,node_tool_meta,node_shared_types toneMint
```

## Components

### App routes

Next.js App Router entrypoints for the public site, tools, and API routes.

- [Root layout](https://github.com/dassougoto/pdfmint/blob/main/app/layout.tsx): next layout · Global app shell and providers. · `app/layout.tsx`
- [Home layout](https://github.com/dassougoto/pdfmint/blob/main/app/(home)/layout.tsx): route layout · Public marketing route layout. · `app/(home)/layout.tsx`
- [Home page](https://github.com/dassougoto/pdfmint/blob/main/app/(home)/page.tsx): landing page · Top-level public landing experience. · `app/(home)/page.tsx`
- [Tools layout](https://github.com/dassougoto/pdfmint/blob/main/app/tools/layout.tsx): route layout · Shared shell for tool pages. · `app/tools/layout.tsx`
- [Compress page](https://github.com/dassougoto/pdfmint/blob/main/app/tools/compress-pdf/page.tsx): tool page · Interactive PDF compression workspace. · `app/tools/compress-pdf/page.tsx`
- [Merge page](https://github.com/dassougoto/pdfmint/blob/main/app/tools/merge-pdf/page.tsx): tool page · Interactive PDF merge workspace. · `app/tools/merge-pdf/page.tsx`
- [Split page](https://github.com/dassougoto/pdfmint/blob/main/app/tools/split-pdf/page.tsx): tool page · Interactive PDF split workspace. · `app/tools/split-pdf/page.tsx`
- [Compress API](https://github.com/dassougoto/pdfmint/blob/main/app/api/compress-pdf/route.ts): route handler · Server-side PDF compression endpoint. · `app/api/compress-pdf/route.ts`
- [Merge API](https://github.com/dassougoto/pdfmint/blob/main/app/api/merge-pdf/route.ts): route handler · Server-side PDF merge endpoint. · `app/api/merge-pdf/route.ts`

### Components

Shared presentation and workspace building blocks.

- [Home sections](https://github.com/dassougoto/pdfmint/tree/main/components/home): marketing ui · Hero, features, workflow, tools, and CTA sections. · `components/home`
- [Site chrome](https://github.com/dassougoto/pdfmint/tree/main/components/common): shared shell · Navbar, footer, mobile menu, and theme toggle. · `components/common`
- [Tool shell](https://github.com/dassougoto/pdfmint/tree/main/components/common): workspace ui · Tool page wrapper, client controller, and workspace layout. · `components/common`
- [File UI](https://github.com/dassougoto/pdfmint/tree/main/components/common): upload/result ui · File cards and download/result page variants. · `components/common`
- [Tool cards](https://github.com/dassougoto/pdfmint/blob/main/components/common/tool-card.tsx): catalog ui · Tool listing and selection cards. · `components/common/tool-card.tsx`
- [UI primitives](https://github.com/dassougoto/pdfmint/tree/main/components/ui): design system · Reusable low-level UI components and theme provider. · `components/ui`

### Domain lib

PDF processing logic, metadata, and shared types.

- [PDF engine](https://github.com/dassougoto/pdfmint/blob/main/lib/process-pdf.ts): processing lib · Core PDF transformation helpers. · `lib/process-pdf.ts`
- [PDF utils](https://github.com/dassougoto/pdfmint/blob/main/lib/pdf-utils.ts): processing lib · Lower-level PDF utility helpers. · `lib/pdf-utils.ts`
- [Compression config](https://github.com/dassougoto/pdfmint/blob/main/lib/compression-settings.ts): settings · Compression settings and tuning values. · `lib/compression-settings.ts`
- [Tool metadata](https://github.com/dassougoto/pdfmint/blob/main/lib/all-pdf-tools.ts): catalog data · Tool list, feature copy, and workflow steps. · `lib/all-pdf-tools.ts`
- [Shared types](https://github.com/dassougoto/pdfmint/blob/main/lib/types.ts): types · Common TypeScript types for tools and workflows. · `lib/types.ts`

## Connections

- Root layout → Home layout: wraps · Global shell wraps the public route group.
- Root layout → Tools layout: wraps · Global shell also wraps tool routes.
- Root layout → Site chrome: uses · Root layout pulls in shared site chrome and providers.
- Home layout → Home page: hosts · Public route layout renders the landing page.
- Home page → Home sections: composes · Landing page is built from marketing sections.
- Home page → Tool cards: shows · Landing page surfaces the tool catalog.
- Home page → Tool metadata: reads · Landing experience is driven by tool metadata and copy.
- Tools layout → Compress page: hosts · Shared tools shell wraps the compression page.
- Tools layout → Merge page: hosts · Shared tools shell wraps the merge page.
- Tools layout → Split page: hosts · Shared tools shell wraps the split page.
- Compress page → Tool shell: uses · Tool page delegates workspace structure to shared shell components.
- Merge page → Tool shell: uses · Tool page delegates workspace structure to shared shell components.
- Split page → Tool shell: uses · Tool page delegates workspace structure to shared shell components.
- Tool shell → File UI: renders · Workspace manages file selection, state, and download views.
- Tool shell → UI primitives: builds on · Workspace UI is composed from reusable primitives.
- File UI → UI primitives: builds on · File and result views use shared primitives.
- Compress page → Compress API: calls · Compression workspace submits jobs to the API route.
- Merge page → Merge API: calls · Merge workspace submits jobs to the API route.
- Compress API → PDF engine: invokes · Compression endpoint centralizes processing in library code.
- Merge API → PDF engine: invokes · Merge endpoint centralizes processing in library code.
- PDF engine → PDF utils: depends on · Core processing relies on lower-level PDF helpers.
- PDF engine → Compression config: uses · Compression logic is parameterized by settings.
- Tool shell → Shared types: uses · Workspace components share typed tool state and results.
- Tool metadata → Shared types: defines · Catalog and workflow definitions are typed against shared models.
- Home sections → Tool metadata: references · Marketing sections reuse the same tool catalog data.
- Site chrome → UI primitives: builds on · Navigation, footer, and theme controls use primitives.