Technical Architecture

Developer documentation covering the codebase design, framework choices, state management, tool registry, and PDF processing engines.

Technology Stack

KissThePDF is built using modern web architecture designed for maximum execution performance and small bundle sizes:

Next.js 16App Router & Turbopack

React 19Server & Client Components

TypeScript 5Strict Type Safety

Tailwind CSS v4PostCSS Engine

pdf-lib 1.17PDF Binary Manipulation

pdfjs-dist 6.3Mozilla Canvas Renderer

Codebase Structure

The project adheres to standard Next.js App Router conventions:

Directory Hierarchy

src/
├── app/                  # Next.js App Router Pages & Layouts
│   ├── (app)/            # Application shell group
│   │   ├── [tool]/       # Dynamic tool routing handler
│   │   ├── tools/        # Tool directory pages
│   │   └── open-source/  # Open-source landing page
│   ├── (landing)/        # Marketing homepage
│   ├── docs/             # Documentation System (This Portal)
│   ├── sitemap.ts        # Dynamic XML Sitemap Generator
│   ├── robots.ts         # Robots.txt handler
│   └── llms.txt/         # Machine-readable LLM documentation index
├── components/           # Reusable UI Components
│   ├── docs/             # Documentation layout, sidebar, search modal, TOC
│   ├── layout/           # Main application header, sidebar, mobile menu
│   ├── pdf/              # Shared PDF canvas renderers & dropzone components
│   └── tools/            # Individual tool interface controls
├── config/               # Centralized Application Configuration
│   ├── site.ts           # Site metadata, GitHub URLs, SEO defaults
│   ├── tools.ts          # Central Tool Registry (100 Tool Definitions)
│   └── docs.ts           # Documentation navigation & category maps
├── lib/                  # Helper Utilities & Core Engines
│   ├── docs-utils.ts     # Search, TOC, and category helpers
│   └── pdf-utils.ts      # Shared pdf-lib & PDF.js manipulation wrappers
└── types/                # TypeScript Interfaces & Type Declarations

Centralized Tool Registry

To manage 100+ PDF tools cleanly without repeating UI boilerplate, tool definitions are stored centrally in src/config/tools.ts. The application sidebar, homepage grid, sitemap, documentation system, and LLM indices consume this single registry.

src/types/index.ts

export interface ToolDefinition {
  id: string;
  name: string;
  description: string;
  category: "Organization" | "Pages" | "Convert" | "Edit" | "Security" | "Forms" | "Enhancement" | "Reading";
  href: string;
  icon: string;
  status: "implemented" | "placeholder";
  seoTitle: string;
  seoDescription: string;
  keywords: string[];
}

PDF Engines & WASM Integration

PDF manipulation is divided into two primary processing layers:

Structural Modification Layer (pdf-lib): Handles binary modification of PDF object trees, page copying, rotation attributes, page removal, field flattening, and password encryption.
Rendering & Preview Layer (PDF.js): Uses Web Workers to compile PDF streams into PNG/JPEG image blobs or HTML5 Canvas layers for page previews.

Architecture Data Flow Diagram

Data Flow Architecture

+-----------------------------------------------------------------------+
|                            USER BROWSER                               |
|                                                                       |
|  +-----------------------------------------------------------------+  |
|  |                           NEXT.JS UI                            |  |
|  |        Application Shell / Tool Controls / Upload Dropzone      |  |
|  +-----------------------------------------------------------------+  |
|                                   |                                   |
|                          ArrayBuffer / Files                          |
|                                   v                                   |
|  +-----------------------------------------------------------------+  |
|  |                     BACKGROUND WEB WORKERS                      |  |
|  |     Isolated background thread preventing main UI freezes       |  |
|  +-----------------------------------------------------------------+  |
|                                   |                                   |
|                        Binary Streams / WASM                          |
|                                   v                                   |
|  +-----------------------------------------------------------------+  |
|  |                       CLIENT PDF ENGINES                        |  |
|  |          pdf-lib (Structure)  |  PDF.js (Rendering/Canvas)     |  |
|  +-----------------------------------------------------------------+  |
|                                   |                                   |
|                           Blob / Uint8Array                           |
|                                   v                                   |
|  +-----------------------------------------------------------------+  |
|  |                         LOCAL DOWNLOAD                          |  |
|  |                 URL.createObjectURL() Download                  |  |
|  +-----------------------------------------------------------------+  |
|                                                                       |
+-----------------------------------------------------------------------+

Open Source Project

KissThePDF is 100% Free & Open Source

All code runs locally in your browser. Contribute code, report bugs, add new tools, or star the repository to support privacy-first software.

Star on GitHub Contribute