📄 PDF Tools - Complete PDF Management Solution

A powerful, easy-to-use application for all your PDF needs. Convert, edit, merge, split, compress, protect, and transform PDF documents with just a few clicks!

📑 Table of Contents

What is PDF Tools?
Features
Quick Start Guide
Installation
How to Use
API Documentation
Project Structure
Configuration
Troubleshooting
Contributing
License

🏗️ Architecture Diagram

                                    ┌─────────────────┐
                                    │     Clients     │
                                    │ (Browser / API) │
                                    └────────┬────────┘
                                             │
                         ┌───────────────────┼───────────────────┐
                         ▼                                       ▼
                ┌─────────────────┐                     ┌─────────────────┐
                │   Flask App     │                     │    FastAPI      │
                │  (Web UI)       │                     │   (REST API)    │
                └────────┬────────┘                     └────────┬────────┘
                         │                                       │
                         └───────────────────┬───────────────────┘
                                             ▼
                                  ┌─────────────────────┐
                                  │   Feature Manager   │
                                  │    (Blueprints)     │
                                  └──────────┬──────────┘
                                             │
                         ┌───────────────────┼───────────────────┐
                         ▼                   ▼                   ▼
               ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
               │  PDF Processing  │ │   Auth & User    │ │  File Management │
               │    Features      │ │    Features      │ │     Features     │
               └────────┬─────────┘ └──────────────────┘ └──────────────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │    PDF Processor    │
              │  (Mixin Classes)    │
              ├─────────────────────┤
              │ • Edit (merge/split)│
              │ • Security (encrypt)│
              │ • Transform (rotate)│
              │ • Convert (formats) │
              └──────────┬──────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
   ┌────────────┐ ┌────────────┐ ┌────────────┐
   │   Celery   │ │ PostgreSQL │ │ File System│
   │   + Redis  │ │  Database  │ │  Storage   │
   │  (Tasks)   │ │  (Users)   │ │  (PDFs)    │
   └────────────┘ └────────────┘ └────────────┘

Key Components:

Flask App: Web interface with HTML templates
FastAPI: REST API for programmatic access
Feature Manager: Organizes routes into modular blueprints
PDF Processor: Core processing engine using mixin architecture
Celery + Redis: Background task processing for large files
PostgreSQL: User data, file records, and conversion history
File System: Uploaded and processed PDF storage

🎯 What is PDF Tools?

PDF Tools is an all-in-one solution for working with PDF files. Whether you need to:

📝 Convert a PDF to Word for editing
🔗 Merge multiple PDFs into one document
✂️ Split a large PDF into smaller files
🔒 Add password protection to sensitive documents
💧 Add watermarks to your PDFs
🗜️ Compress PDFs to reduce file size

...this tool has you covered! It works through a web browser (no installation needed on user devices), provides a REST API for developers, and can also be used via command line.

✨ Features

🔄 PDF Conversion

Convert PDFs to and from various formats:

From PDF To	From Format To PDF
✅ Word (DOCX)	✅ Word (DOCX)
✅ Excel (XLSX)	✅ Excel (XLSX)
✅ PowerPoint (PPTX)	✅ PowerPoint (PPTX)
✅ HTML	✅ HTML
✅ Images (PNG, JPG)	✅ Images
✅ Plain Text	✅ Jupyter Notebooks

✂️ PDF Editing & Processing

Feature	Description
🔗 Merge PDFs	Combine multiple PDFs into a single document
✂️ Split PDF	Separate a PDF into individual pages or custom ranges
🗜️ Compress PDF	Reduce file size while maintaining quality
📑 Extract Pages	Pull out specific pages from a PDF
🔄 Rotate Pages	Rotate pages 90°, 180°, or 270°
📝 Extract Text	Get all text content from a PDF
🖼️ Extract Images	Save all images from a PDF
🔧 Repair PDF	Fix corrupted or damaged PDF files
🔍 Compare PDFs	Find differences between two PDF files

🔒 PDF Security

Feature	Description
🔐 Password Protection	Add open/edit passwords to PDFs
🔓 Remove Password	Unlock password-protected PDFs (with authorization)
💧 Watermarks	Add text or image watermarks
✍️ Digital Signatures	Add signature stamps to documents
🔏 Encryption	Secure PDFs with AES-256 encryption

📊 OCR & Advanced Features

Feature	Description
🔍 OCR (Optical Character Recognition)	Extract text from scanned documents
📋 Batch Processing	Process multiple files at once
📈 Progress Tracking	Monitor conversion progress in real-time
🔄 Background Tasks	Long operations run in the background

🚀 Quick Start Guide

Get up and running in 5 minutes!

Step 1: Prerequisites

Make sure you have these installed:

✅ Python 3.10 or higher - Download Python
✅ PostgreSQL - Download PostgreSQL
✅ Redis (for background tasks) - Download Redis
✅ Git - Download Git

Step 2: Clone & Setup

# 1. Clone the repository
git clone https://github.com/9046balaji/Pdf-Tools.git
cd Pdf-Tools

# 2. Create a virtual environment
python -m venv venv

# 3. Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

Step 3: Configure Environment

Create a .env file in the project root:

# Required Settings
SECRET_KEY=your-super-secret-key-change-this-in-production

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=pdf_tools

# File Settings
UPLOAD_FOLDER=uploads
PROCESSED_FOLDER=processed
MAX_CONTENT_LENGTH=1073741824

# Redis (for background tasks)
REDIS_URL=redis://localhost:6379/0

Step 4: Initialize Database

python
>>> from app import create_app
>>> from database.db import db
>>> app = create_app()
>>> with app.app_context():
...     db.create_all()
>>> exit()

Step 5: Run the Application

python run.py

🎉 Done! Open your browser and go to: http://localhost:5000

📦 Installation

Detailed Installation Guide

System Requirements

Component	Minimum	Recommended
Python	3.10	3.11+
PostgreSQL	13	15+
RAM	2 GB	4 GB+
Disk Space	500 MB	2 GB+
OS	Windows 10, macOS 10.15, Ubuntu 20.04	Latest versions

Optional Tools (for full functionality)

Tool	Purpose	Download
Tesseract	OCR functionality	Installation Guide
Poppler	PDF to image conversion	Download
Ghostscript	Advanced PDF compression	Download
Pandoc	Document format conversion	Download
LibreOffice	Office document conversion	Download

Installing on Windows

# 1. Install Python from python.org (check "Add to PATH")

# 2. Clone and setup
git clone https://github.com/9046balaji/Pdf-Tools.git
cd Pdf-Tools

# 3. Create virtual environment
python -m venv venv
.\venv\Scripts\Activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run application
python run.py

Installing on macOS

# 1. Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install Python and dependencies
brew install [email protected] postgresql redis

# 3. Clone and setup
git clone https://github.com/9046balaji/Pdf-Tools.git
cd Pdf-Tools

# 4. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 5. Install dependencies
pip install -r requirements.txt

# 6. Run application
python run.py

Installing on Ubuntu/Debian

# 1. Install system dependencies
sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip postgresql redis-server

# 2. Clone and setup
git clone https://github.com/9046balaji/Pdf-Tools.git
cd Pdf-Tools

# 3. Create virtual environment
python3.11 -m venv venv
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run application
python run.py

💻 How to Use

🌐 Web Interface (Easiest Method)

Start the application: Run python run.py
Open your browser: Go to http://localhost:5000
Choose an operation: Click on what you want to do (Convert, Merge, Split, etc.)
Upload your file(s): Drag and drop or click to select files
Configure options: Adjust settings if needed
Process: Click the action button
Download: Save your processed file

🐍 Python Script (For Developers)

# Example: Convert PDF to Word
from pdf_modules.pdf_word_conversion import PDFWordConversionMixin

class PDFConverter(PDFWordConversionMixin):
    pass

converter = PDFConverter()
result = converter.pdf_to_docx(
    input_path="document.pdf",
    output_path="document.docx"
)
print(f"Conversion successful: {result}")

# Example: Merge multiple PDFs
from pdf_modules.pdf_edit import PDFEditMixin

class PDFEditor(PDFEditMixin):
    pass

editor = PDFEditor()
result = editor.merge_pdfs(
    pdf_files=["file1.pdf", "file2.pdf", "file3.pdf"],
    output_path="merged_document.pdf"
)
print(f"Merged {result.files_merged} files into {result.output_path}")

# Example: Add password protection
from pdf_modules.pdf_security import PDFSecurityMixin

class PDFSecurity(PDFSecurityMixin):
    pass

security = PDFSecurity()
security.protect_pdf(
    input_path="document.pdf",
    output_path="protected_document.pdf",
    password="your-secure-password"
)
print("PDF protected successfully!")

🔌 REST API (For Integration)

The application provides a full REST API for integration with other systems.

Base URL: http://localhost:5000/api

Convert PDF to Word

curl -X POST http://localhost:5000/api/pdf/convert-to-word \
  -F "[email protected]" \
  -H "Content-Type: multipart/form-data"

Merge Multiple PDFs

curl -X POST http://localhost:5000/api/pdf/merge \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

Add Password Protection

curl -X POST http://localhost:5000/api/pdf/protect \
  -F "[email protected]" \
  -F "password=your-secure-password"

Compress PDF

curl -X POST http://localhost:5000/api/pdf/compress \
  -F "file=@large_document.pdf" \
  -F "quality=balanced"

📚 API Documentation

Interactive API Documentation

Once the application is running, access the interactive API documentation:

Swagger UI: http://localhost:5000/docs
ReDoc: http://localhost:5000/redoc
OpenAPI JSON: http://localhost:5000/openapi.json

API Endpoints Overview

Conversion Endpoints

Method	Endpoint	Description
POST	`/api/pdf/convert-to-word`	Convert PDF to Word (DOCX)
POST	`/api/pdf/convert-to-excel`	Convert PDF to Excel (XLSX)
POST	`/api/pdf/convert-to-pptx`	Convert PDF to PowerPoint
POST	`/api/pdf/convert-to-html`	Convert PDF to HTML
POST	`/api/pdf/convert-to-text`	Extract text from PDF
POST	`/api/pdf/convert-to-images`	Convert PDF to images

Processing Endpoints

Method	Endpoint	Description
POST	`/api/pdf/merge`	Merge multiple PDFs
POST	`/api/pdf/split`	Split PDF into pages
POST	`/api/pdf/compress`	Compress PDF file
POST	`/api/pdf/rotate`	Rotate PDF pages
GET	`/api/pdf/extract-images`	Extract images from PDF
POST	`/api/pdf/extract-pages`	Extract specific pages

Security Endpoints

Method	Endpoint	Description
POST	`/api/pdf/protect`	Add password protection
POST	`/api/pdf/unlock`	Remove password (with auth)
POST	`/api/pdf/watermark`	Add watermark
POST	`/api/pdf/sign`	Add signature stamp

Task Management

Method	Endpoint	Description
GET	`/tasks/{task_id}`	Get task status
GET	`/tasks/{task_id}/result`	Get task result
GET	`/health`	Health check

Response Format

Success Response:

{
  "status": "success",
  "message": "Operation completed successfully",
  "task_id": "conv_abc123def456",
  "result": {
    "output_file": "output.docx",
    "file_size": 1024000,
    "pages_processed": 10
  }
}

Error Response:

{
  "status": "error",
  "message": "Invalid PDF file",
  "error_code": "INVALID_PDF",
  "details": {
    "reason": "File is corrupted or not a valid PDF"
  }
}

📁 Project Structure

Pdf-Tools/
│
├── 🚀 Entry Points
│   ├── run.py                      # Application entry point
│   ├── app.py                      # Flask application factory
│   └── api.py                      # FastAPI endpoints
│
├── ⚙️ Configuration
│   ├── config.py                   # Application settings
│   ├── .env                        # Environment variables (create this)
│   └── .env.example                # Example configuration
│
├── 📚 Core PDF Modules
│   └── pdf_modules/
│       ├── pdf_base.py             # Base PDF operations
│       ├── pdf_convert.py          # Format conversions
│       ├── pdf_edit.py             # Merge, split, extract
│       ├── pdf_transform.py        # Rotate, compress
│       ├── pdf_security.py         # Passwords, watermarks
│       ├── pdf_validation.py       # File validation
│       ├── pdf_repair.py           # Fix corrupted PDFs
│       └── ...                     # More specialized modules
│
├── 🎯 Features
│   └── Feature/
│       ├── admin_features.py       # Admin operations
│       ├── authentication_features.py  # User login/logout
│       ├── conversion_features.py  # Conversion routes
│       ├── file_management_features.py # File handling
│       └── feature_manager.py      # Feature orchestration
│
├── 🔧 Utilities
│   └── common/
│       ├── file_validation.py      # File checks
│       ├── error_recovery.py       # Error handling
│       ├── health_check.py         # System monitoring
│       ├── progress.py             # Progress tracking
│       └── upload_handler.py       # Upload management
│
├── 🗄️ Database
│   └── database/
│       ├── db.py                   # Database connection
│       └── models.py               # Data models
│
├── 🎨 Frontend
│   ├── static/                     # CSS, JavaScript, images
│   └── templates/                  # HTML templates
│
├── 📂 File Storage
│   ├── uploads/                    # Uploaded files (auto-created)
│   └── processed/                  # Output files (auto-created)
│
├── 🧪 Tests
│   └── tests/                      # Test files
│
└── 📋 Documentation
    ├── README.md                   # This file
    ├── LICENSE                     # MIT License
    └── requirements.txt            # Python dependencies

⚙️ Configuration

Environment Variables

Create a .env file in the project root with these settings:

Required Settings

# Security - CHANGE THIS IN PRODUCTION!
SECRET_KEY=your-very-long-random-secret-key-at-least-32-characters

# Database Connection
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_database_password
DB_NAME=pdf_tools

Optional Settings

# Application Mode
FLASK_ENV=development          # Use 'production' for live deployments
FLASK_DEBUG=1                  # Set to 0 in production

# File Handling
UPLOAD_FOLDER=uploads          # Where uploads are stored
PROCESSED_FOLDER=processed     # Where output files are saved
MAX_CONTENT_LENGTH=1073741824  # Max file size (1GB default)

# Redis (for background tasks)
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/0

# Email Notifications (optional)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password

# Session Settings
SESSION_COOKIE_SECURE=True     # Enable in production with HTTPS

Running with Background Tasks (Celery)

For better performance with large files, enable background processing:

# Terminal 1: Start Redis (if not running)
redis-server

# Terminal 2: Start Celery worker
celery -A tasks worker --loglevel=info

# Terminal 3: Run the application
python run.py

🐛 Troubleshooting

Common Issues and Solutions

❌ "ModuleNotFoundError: No module named 'X'"

Problem: A required Python package is missing.

Solution:

# Make sure virtual environment is activated
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install all dependencies
pip install -r requirements.txt

❌ "Cannot connect to database"

Problem: PostgreSQL is not running or credentials are wrong.

Solution:

Check PostgreSQL is running:

# Windows
pg_isready

# macOS/Linux
sudo systemctl status postgresql

Verify your .env file has correct credentials

Make sure the database exists:

psql -U postgres -c "CREATE DATABASE pdf_tools;"

❌ "Port 5000 already in use"

Problem: Another application is using port 5000.

Solution: Change the port in your .env file:

FLASK_PORT=5001

Or run with a different port:

python run.py --port 5001

❌ "File too large" (413 Error)

Problem: The uploaded file exceeds the size limit.

Solution: Increase the limit in .env:

MAX_CONTENT_LENGTH=2147483648  # 2GB

❌ "PDF conversion failed"

Problem: The PDF file might be corrupted or protected.

Solution:

Check if the PDF opens in a regular PDF viewer
Try the repair function first
Check if the PDF is password-protected
Look at the logs for detailed error messages:
```
# View application logs
cat logs/app.log
```

❌ "OCR not working"

Problem: Tesseract OCR is not installed.

Solution: Install Tesseract:

# Windows (using Chocolatey)
choco install tesseract

# macOS
brew install tesseract

# Ubuntu/Debian
sudo apt install tesseract-ocr

Getting More Help

Check the logs: Look in the logs/ folder for detailed error messages
Enable debug mode: Set FLASK_DEBUG=1 in your .env file
Search issues: Check GitHub Issues
Create an issue: If you can't find a solution, create a new issue with:
- Your operating system
- Python version (python --version)
- Complete error message
- Steps to reproduce

🤝 Contributing

We welcome contributions! Here's how you can help:

How to Contribute

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/your-username/Pdf-Tools.git

Create a branch for your feature:

git checkout -b feature/your-amazing-feature

Make your changes and test them

Commit your changes:

git commit -m "Add: Your feature description"

Push to your fork:

git push origin feature/your-amazing-feature

Create a Pull Request on GitHub

Coding Guidelines

Follow PEP 8 style guide for Python
Add docstrings to functions and classes
Write meaningful commit messages
Add tests for new features
Update documentation as needed

What You Can Contribute

🐛 Bug fixes
✨ New features
📚 Documentation improvements
🧪 Tests
🌍 Translations
💡 Ideas and suggestions

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 PDF Tools

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

🙏 Acknowledgments

Special thanks to:

All the contributors who help improve this project
The open-source community for the amazing libraries used
Everyone who reports bugs and suggests features

📊 Technologies Used

Category	Technologies
Backend	Python 3.10+, Flask, FastAPI
Database	PostgreSQL, SQLAlchemy
Task Queue	Celery, Redis
PDF Processing	PyMuPDF, pypdf, pikepdf, reportlab
Conversion	pdf2docx, python-docx, python-pptx, openpyxl
OCR	Tesseract, ocrmypdf
Monitoring	OpenTelemetry, Prometheus

📈 Roadmap

Planned Features

🐳 Docker support
☁️ Cloud storage integration (AWS S3, Google Cloud)
🤖 AI-powered document analysis
📱 Mobile-friendly interface
🔄 Real-time collaboration
📧 Email integration

Made with ❤️ for PDF lovers worldwide

⭐ Star this repo | 🐛 Report Bug | 💡 Request Feature

Last Updated: January 2026

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
Feature		Feature
common		common
database		database
pdf_modules		pdf_modules
static		static
templates		templates
.env		.env
.env.example		.env.example
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
Procfile		Procfile
README.md		README.md
api.py		api.py
app.py		app.py
config.py		config.py
pdf_processor.py		pdf_processor.py
render.yaml		render.yaml
requirements.txt		requirements.txt
run.py		run.py
tasks.py		tasks.py
utils.py		utils.py

Folders and files

Latest commit

History

Repository files navigation

📄 PDF Tools - Complete PDF Management Solution

📑 Table of Contents

🏗️ Architecture Diagram

🎯 What is PDF Tools?

✨ Features

🔄 PDF Conversion

✂️ PDF Editing & Processing

🔒 PDF Security

📊 OCR & Advanced Features

🚀 Quick Start Guide

Step 1: Prerequisites

Step 2: Clone & Setup

Step 3: Configure Environment

Step 4: Initialize Database

Step 5: Run the Application

📦 Installation

Detailed Installation Guide

System Requirements

Optional Tools (for full functionality)

Installing on Windows

Installing on macOS

Installing on Ubuntu/Debian

💻 How to Use

🌐 Web Interface (Easiest Method)

🐍 Python Script (For Developers)

🔌 REST API (For Integration)

Convert PDF to Word

Merge Multiple PDFs

Add Password Protection

Compress PDF

📚 API Documentation

Interactive API Documentation

API Endpoints Overview

Conversion Endpoints

Processing Endpoints

Security Endpoints

Task Management

Response Format

📁 Project Structure

⚙️ Configuration

Environment Variables

Required Settings

Optional Settings

Running with Background Tasks (Celery)

🐛 Troubleshooting

Common Issues and Solutions

❌ "ModuleNotFoundError: No module named 'X'"

❌ "Cannot connect to database"

❌ "Port 5000 already in use"

❌ "File too large" (413 Error)

❌ "PDF conversion failed"

❌ "OCR not working"

Getting More Help

🤝 Contributing

How to Contribute

Coding Guidelines

What You Can Contribute

📝 License

🙏 Acknowledgments

📊 Technologies Used

📈 Roadmap

Planned Features

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages