The application follows a Monolithic Service-Oriented Architecture designed for maintainability and easy containerization.
- Controller-Service-Repository: Separation of concerns.
- Controllers (
/controller): Handle HTTP requests, input validation, and response formatting. - Services (
/service): Contain business logic (e.g.,PdfToolServicefor file processing,UsageResetServicefor scheduling). - Repositories (
/repository): Interface with PostgreSQL via Spring Data JPA.
- Controllers (
- DTOs: Data Transfer Objects used for type-safe communication between frontend and backend (e.g.,
AuthResponse,LoginRequest). - Global Configuration: System-wide settings stored in the database for dynamic runtime adjustments.
- Context API: Global state management for Authentication (
AuthContext), Toast Notifications (ToastContext), and User History (HistoryContext). - Component-Based Design: Reusable UI components (
/components/ui) like Modals, Buttons, and Inputs. - Layout Wrapper:
NavbarandFooterintegrated into the main layout for consistent navigation.
| Technology | Description |
|---|---|
| React 18 | High-performance SPA library |
| Vite | Next-generation frontend tooling |
| Tailwind CSS | Utility-first CSS framework |
| Framer Motion | Production-ready animation library |
| Axios | Promise-based HTTP client |
| Lucide React | Beautiful & consistent icon set |
| React Dropzone | Drag-and-drop file handling |
| Technology | Description |
|---|---|
| Java 17 (LTS) | Core programming language |
| Spring Boot 3.2 | Application framework |
| Spring Security | Authentication & Access Control |
| Spring Data JPA | Hibernate-based ORM |
| PostgreSQL | Relational Database |
| Apache PDFBox | PDF manipulation engine |
| Apache POI | Microsoft Office document conversion |
| Lombok | Boilerplate code reduction |
proj/
├── pdf-wiz-backend/ # Spring Boot Application
│ ├── src/main/java/com/pdfly/backend/
│ │ ├── controller/ # REST API Endpoints
│ │ ├── dto/ # Data Transfer Objects
│ │ ├── model/ # JPA Entities (User, GlobalConfig)
│ │ ├── repository/ # Database Interfaces
│ │ ├── service/ # Business Logic (PdfToolService, EmailService)
│ │ └── config/ # Security & App Config
│ └── pom.xml # Maven Dependencies
│
├── pdf-wiz-frontend/ # React Application
│ ├── src/
│ │ ├── components/ # Reusable UI Components
│ │ │ └── ui/ # Magic UI & Base Elements
│ │ ├── context/ # Global State (Auth, Toast)
│ │ ├── pages/ # Page Views (ToolPage, Login, Admin)
│ │ └── lib/ # Utilities (Tailwind merge, etc.)
│ └── package.json # NPM Dependencies
│
└── README.md # Project Documentation
- Node.js (v18+)
- Java JDK (v17+)
- PostgreSQL (Local or Cloud)
Option 1: Use the Helper Script (Recommended) From the project root directory:
./start-backend.shOption 2: Manual Start
cd pdf-wiz-backend
# Configure Database in src/main/resources/application.properties
# spring.datasource.url=jdbc:postgresql://localhost:5432/pdfly_db
# spring.datasource.username=postgres
# spring.datasource.password=your_password
# Run the application
./mvnw spring-boot:runServer starts on http://localhost:8080
cd pdf-wiz-frontend
# Install dependencies
npm install
# Start development server
npm run devUI accessible at http://localhost:5173
The backend application.properties requires the following configurations:
| Variable | Description | Example |
|---|---|---|
spring.datasource.url |
DB Connection | jdbc:postgresql://localhost:5432/pdfly_db |
jwt.secret |
Token Signing Key | 5367566B59... (Base64 encoded) |
spring.mail.password |
SMTP Password | Google App Password |
PDFly is a scalable, high-performance Micro-SaaS application designed for secure and efficient PDF manipulation. Built with a modern React frontend and a robust Java Spring Boot backend, it offers enterprise-grade document processing capabilities including merging, splitting, compression, conversion (Word/Excel/PPT), and security tools.
The platform operates on a Freemium business model, offering essential tools for free with daily usage limits, while incentivizing upgrades to the Pro tier for unlimited access and advanced features.
- Premium UI/UX: A modern, high-end interface built with Tailwind CSS and Framer Motion. Features "Magic UI" components like
RainbowButton,ShineBorder, andNumberTickerfor a polished feel. - 15+ PDF Tools: Comprehensive suite including Merge, Split, Compress, Convert (Word/Excel/PPT/JPG), Watermark, Sign, Protect, and Unlock.
- Smart Rate Limiting: Enforces a 3 Free Tasks per Day policy for free users, with visual countdowns and "Limit Reached" prompts.
- Interactive Pricing: Animated pricing page with counting numbers to drive conversions.
- Dark Mode: Fully responsive theme support (System/Light/Dark) using
next-themes. - Real-time Feedback: Toast notifications and smooth loading states for all operations.
- Secure Authentication: Stateless architecture using Spring Security and JWT (JSON Web Tokens).
- Passwordless Entry: "Magic Link" style access where secure keys are emailed to users via JavaMail.
- Robust PDF Engine: Powered by Apache PDFBox and Apache POI, handling complex document manipulations efficiently in memory.
- Daily Usage Reset: Automated scheduled tasks (
@Scheduled) reset user limits daily. - Role-Based Access Control (RBAC): Strict separation between
USERandADMINroles. - HTML Emails: Beautifully styled transactional emails for welcome messages and password resets.
- Live Dashboard: Real-time visualization of system health and user activity.
- Feature Flags: Dynamic control to enable/disable specific tools (e.g., "Disable Compression") or signups globally.
- User Management: CRM-style interface to view users, manage plans, and monitor usage.
Copyright © 2025 PDFly Inc. All rights reserved.