# vishnuviez/smartpdf architecture

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

- Interactive diagram: https://gitdiagram.com/vishnuviez/smartpdf
- Repository: https://github.com/vishnuviez/smartpdf

## Overview

#### Purpose and Runtime
This is a Next.js App Router application for browser-based PDF utilities, conversion tools, and related marketing content. The primary entry point is `app/page.js`; global document structure and styling originate in `app/layout.js` and `app/globals.css`. It runs as a Node.js/Next.js application and includes Netlify deployment configuration in `netlify.toml`.

#### Route Structure
Tool capabilities are exposed as route segments under `app/tools`, each with a page and route-local layout. Major user-facing workflows include compression (`app/tools/compress/page.js`), merging (`app/tools/merge/page.js`), editing (`app/tools/edit/page.js`), image conversion (`app/tools/images-to-pdf/page.js`), OCR (`app/tools/ocr/page.js`), and document export formats such as `app/tools/pdf-to-word/page.js` and `app/tools/pdf-to-excel/page.js`.

#### Shared Upload and File Interaction Layer
The reusable UI boundary for file-oriented workflows is concentrated in:
- `app/components/Dropzone.js`
- `app/components/FileList.js`
- `app/lib/pdf-utils.js`

Tool pages likely compose the drop zone and file-list components, while PDF-oriented transformations are centralized behind the PDF utility module rather than embedded in every page. This separates browser interaction/state from document manipulation behavior.

#### Tool Processing Flows
The core flow is: user navigates to a tool route, selects or drops one or more files, configures a tool-specific operation, invokes client-side or API-backed processing, then receives a transformed/downloadable artifact. Multi-file operations are represented by merge (`app/tools/merge/page.js`), organize (`app/tools/organize/page.js`), and split (`app/tools/split/page.js`); document mutation tools include rotate, watermark, protect, unlock, page numbering, and signing under `app/tools/*/page.js`.

#### Server API Boundaries
Two Next.js route handlers define server-side integration points:
- `app/api/checkout/route.js`
- `app/api/gemini/route.js`

Checkout is the payment/subscription boundary associated with the pricing surface in `app/pricing/page.js`. Gemini is an external AI-service boundary, likely used for AI-assisted document functionality; its credentials and provider invocation should remain server-side within this handler rather than in tool pages.

#### Content and Acquisition Surface
The application includes static SEO/editorial routes under `app/blog`, with a blog index at `app/blog/page.js` and PDF-task articles such as `app/blog/how-to-merge-pdf-files-free/page.js`. Shared site navigation is represented by `app/components/Header.js`. These routes feed users toward the interactive tool routes rather than participating in document processing.

#### Infrastructure and Key Boundaries
Next.js configuration is in `next.config.mjs`; package/runtime dependencies are defined by `package.json`. Deployment is explicitly prepared for Netlify via `netlify.toml`, despite the generic README mentioning Vercel. The principal trust boundaries are browser file input versus processing code, client pages versus server API routes, and internal checkout/Gemini handlers versus their external payment and AI providers.

Main entry points: [`app/tools/compress/page.js`](https://github.com/vishnuviez/smartpdf/blob/main/app/tools/compress/page.js) (Tool route pages), [`app/tools/merge/page.js`](https://github.com/vishnuviez/smartpdf/blob/main/app/tools/merge/page.js) (Multi-file tools), [`app/layout.js`](https://github.com/vishnuviez/smartpdf/blob/main/app/layout.js) (Root layout & globals), [`app/page.js`](https://github.com/vishnuviez/smartpdf/blob/main/app/page.js) (Home page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site & acquisition"]
  node_root_layout["Root layout &amp; globals<br/>app shell<br/>[layout.js]"]
  node_home["Home page<br/>landing route<br/>[page.js]"]
  node_header["Shared header<br/>navigation component<br/>[Header.js]"]
  node_pricing["Pricing<br/>purchase route<br/>[page.js]"]
  node_blog["Blog &amp; SEO articles<br/>content routes<br/>[page.js]"]
end

subgraph group_tools["PDF tool workflows"]
  node_tool_routes["Tool route pages<br/>interactive routes<br/>[page.js]"]
  node_multifile_tools["Multi-file tools<br/>interactive routes<br/>[page.js]"]
end

subgraph group_shared["Shared file interaction"]
  node_dropzone["Dropzone<br/>file input component<br/>[Dropzone.js]"]
  node_file_list["File list<br/>file state component<br/>[FileList.js]"]
  node_pdf_utils["PDF utilities<br/>document processing<br/>[pdf-utils.js]"]
end

subgraph group_server["Server integrations"]
  node_checkout_api["Checkout handler<br/>Next.js API route<br/>[route.js]"]
  node_gemini_api["Gemini handler<br/>Next.js API route<br/>[route.js]"]
  node_payment_provider{{"Payment provider<br/>external service"}}
  node_gemini_provider{{"Gemini AI provider<br/>external service"}}
end

node_next_app{{"Next.js App Router<br/>application runtime"}}
node_netlify{{"Netlify deployment<br/>hosting platform<br/>[netlify.toml]"}}

node_next_app -->|"renders"| node_root_layout
node_root_layout -->|"includes"| node_header
node_next_app -->|"serves"| node_home
node_next_app -->|"serves"| node_tool_routes
node_next_app -->|"serves"| node_multifile_tools
node_next_app -->|"serves"| node_pricing
node_next_app -->|"serves"| node_blog
node_home -->|"drives to"| node_tool_routes
node_blog -->|"acquires users for"| node_tool_routes
node_tool_routes -->|"accepts files through"| node_dropzone
node_tool_routes -->|"shows selected files"| node_file_list
node_tool_routes -->|"processes with"| node_pdf_utils
node_multifile_tools -->|"accepts files through"| node_dropzone
node_multifile_tools -->|"manages file sets"| node_file_list
node_multifile_tools -->|"processes with"| node_pdf_utils
node_pricing -->|"starts checkout"| node_checkout_api
node_checkout_api -->|"calls"| node_payment_provider
node_tool_routes -.->|"uses AI operations"| node_gemini_api
node_gemini_api -->|"invokes"| node_gemini_provider
node_netlify -->|"deploys"| node_next_app

click node_root_layout "https://github.com/vishnuviez/smartpdf/blob/main/app/layout.js"
click node_home "https://github.com/vishnuviez/smartpdf/blob/main/app/page.js"
click node_header "https://github.com/vishnuviez/smartpdf/blob/main/app/components/Header.js"
click node_pricing "https://github.com/vishnuviez/smartpdf/blob/main/app/pricing/page.js"
click node_blog "https://github.com/vishnuviez/smartpdf/blob/main/app/blog/page.js"
click node_tool_routes "https://github.com/vishnuviez/smartpdf/blob/main/app/tools/compress/page.js"
click node_multifile_tools "https://github.com/vishnuviez/smartpdf/blob/main/app/tools/merge/page.js"
click node_dropzone "https://github.com/vishnuviez/smartpdf/blob/main/app/components/Dropzone.js"
click node_file_list "https://github.com/vishnuviez/smartpdf/blob/main/app/components/FileList.js"
click node_pdf_utils "https://github.com/vishnuviez/smartpdf/blob/main/app/lib/pdf-utils.js"
click node_checkout_api "https://github.com/vishnuviez/smartpdf/blob/main/app/api/checkout/route.js"
click node_gemini_api "https://github.com/vishnuviez/smartpdf/blob/main/app/api/gemini/route.js"
click node_netlify "https://github.com/vishnuviez/smartpdf/blob/main/netlify.toml"

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_root_layout,node_home,node_header,node_pricing,node_blog toneBlue
class node_tool_routes,node_multifile_tools toneAmber
class node_dropzone,node_file_list,node_pdf_utils toneMint
class node_checkout_api,node_gemini_api,node_payment_provider,node_gemini_provider toneRose
class node_next_app,node_netlify toneNeutral
```

## Components

### Site & acquisition

- [Root layout & globals](https://github.com/vishnuviez/smartpdf/blob/main/app/layout.js): app shell · `app/layout.js`
- [Home page](https://github.com/vishnuviez/smartpdf/blob/main/app/page.js): landing route · `app/page.js`
- [Shared header](https://github.com/vishnuviez/smartpdf/blob/main/app/components/Header.js): navigation component · `app/components/Header.js`
- [Pricing](https://github.com/vishnuviez/smartpdf/blob/main/app/pricing/page.js): purchase route · `app/pricing/page.js`
- [Blog & SEO articles](https://github.com/vishnuviez/smartpdf/blob/main/app/blog/page.js): content routes · Includes PDF-task acquisition content. · `app/blog/page.js`

### PDF tool workflows

- [Tool route pages](https://github.com/vishnuviez/smartpdf/blob/main/app/tools/compress/page.js): interactive routes · Compression, edit, conversion, OCR, and document-mutation workflows. · `app/tools/compress/page.js`
- [Multi-file tools](https://github.com/vishnuviez/smartpdf/blob/main/app/tools/merge/page.js): interactive routes · Merge, organize, and split workflows. · `app/tools/merge/page.js`

### Shared file interaction

- [Dropzone](https://github.com/vishnuviez/smartpdf/blob/main/app/components/Dropzone.js): file input component · `app/components/Dropzone.js`
- [File list](https://github.com/vishnuviez/smartpdf/blob/main/app/components/FileList.js): file state component · `app/components/FileList.js`
- [PDF utilities](https://github.com/vishnuviez/smartpdf/blob/main/app/lib/pdf-utils.js): document processing · Centralizes PDF-oriented transformations. · `app/lib/pdf-utils.js`

### Server integrations

- [Checkout handler](https://github.com/vishnuviez/smartpdf/blob/main/app/api/checkout/route.js): Next.js API route · Keeps payment integration server-side. · `app/api/checkout/route.js`
- [Gemini handler](https://github.com/vishnuviez/smartpdf/blob/main/app/api/gemini/route.js): Next.js API route · Keeps AI credentials and provider calls server-side. · `app/api/gemini/route.js`
- **Payment provider**: external service
- **Gemini AI provider**: external service

### Other components

- **Next.js App Router**: application runtime · Browser-based PDF utility application.
- [Netlify deployment](https://github.com/vishnuviez/smartpdf/blob/main/netlify.toml): hosting platform · `netlify.toml`

## Connections

- Next.js App Router → Root layout & globals: renders
- Root layout & globals → Shared header: includes
- Next.js App Router → Home page: serves
- Next.js App Router → Tool route pages: serves
- Next.js App Router → Multi-file tools: serves
- Next.js App Router → Pricing: serves
- Next.js App Router → Blog & SEO articles: serves
- Home page → Tool route pages: drives to
- Blog & SEO articles → Tool route pages: acquires users for
- Tool route pages → Dropzone: accepts files through
- Tool route pages → File list: shows selected files
- Tool route pages → PDF utilities: processes with
- Multi-file tools → Dropzone: accepts files through
- Multi-file tools → File list: manages file sets
- Multi-file tools → PDF utilities: processes with
- Pricing → Checkout handler: starts checkout
- Checkout handler → Payment provider: calls
- Tool route pages → Gemini handler: uses AI operations
- Gemini handler → Gemini AI provider: invokes
- Netlify deployment → Next.js App Router: deploys