From ac3da9b7c231e7d7f9c771cc4d65b62d2aa3f9d0 Mon Sep 17 00:00:00 2001 From: Reece Date: Sat, 14 Jun 2025 22:03:46 +0100 Subject: [PATCH] Developer guide updates and claude.md --- CLAUDE.md | 14 +++++ DeveloperGuide.md | 152 ++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 141 insertions(+), 25 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c67379e9a..05bfb5254 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -108,3 +108,17 @@ npx tailwindcss init -p - **Backend**: Designed to be stateless - files are processed in memory/temp locations only - **Frontend**: Uses IndexedDB for client-side file storage and caching (with thumbnails) - **Security**: When `DOCKER_ENABLE_SECURITY=false`, security-related classes are excluded from compilation + +## Communication Style +- Be direct and to the point +- No apologies or conversational filler +- Answer questions directly without preamble +- Explain reasoning concisely when asked +- Avoid unnecessary elaboration + +## Decision Making +- Ask clarifying questions before making assumptions +- Stop and ask when uncertain about project-specific details +- Confirm approach before making structural changes +- Request guidance on preferences (cross-platform vs specific tools, etc.) +- Verify understanding of requirements before proceeding diff --git a/DeveloperGuide.md b/DeveloperGuide.md index 32d480f5c..65c26d36a 100644 --- a/DeveloperGuide.md +++ b/DeveloperGuide.md @@ -2,21 +2,38 @@ ## 1. Introduction -Stirling-PDF is a robust, locally hosted, web-based PDF manipulation tool. This guide focuses on Docker-based development and testing, which is the recommended approach for working with the full version of Stirling-PDF. +Stirling-PDF is a robust, locally hosted, web-based PDF manipulation tool. **Stirling 2.0** represents a complete frontend rewrite, replacing the legacy Thymeleaf-based UI with a modern React SPA (Single Page Application). + +This guide focuses on developing for Stirling 2.0, including both the React frontend and Spring Boot backend development workflows. ## 2. Project Overview -Stirling-PDF is built using: +**Stirling 2.0** is built using: -- Spring Boot + Thymeleaf -- PDFBox -- LibreOffice -- qpdf -- HTML, CSS, JavaScript -- Docker -- PDF.js -- PDF-LIB.js -- Lombok +**Backend:** +- Spring Boot (Java 17+, JDK 21 recommended) +- PDFBox for core PDF operations +- LibreOffice for document conversions +- qpdf for PDF optimization +- Spring Security (optional, controlled by `DOCKER_ENABLE_SECURITY`) +- Lombok for reducing boilerplate code + +**Frontend (React SPA):** +- React + TypeScript +- Vite for build tooling and development server +- Mantine UI component library +- TailwindCSS for styling +- PDF.js for client-side PDF rendering +- PDF-LIB.js for client-side PDF manipulation +- IndexedDB for client-side file storage and thumbnails +- i18next for internationalization + +**Infrastructure:** +- Docker for containerization +- Gradle for build management + +**Legacy (reference only during development):** +- Thymeleaf templates (being completely replaced in 2.0) ## 3. Development Environment Setup @@ -24,7 +41,8 @@ Stirling-PDF is built using: - Docker - Git -- Java JDK 17 or later +- Java JDK 17 or later (JDK 21 recommended) +- Node.js 18+ and npm (required for frontend development) - Gradle 7.0 or later (Included within the repo) ### Setup Steps @@ -54,17 +72,45 @@ Stirling-PDF is built using: Stirling-PDF uses Lombok to reduce boilerplate code. Some IDEs, like Eclipse, don't support Lombok out of the box. To set up Lombok in your development environment: Visit the [Lombok website](https://projectlombok.org/setup/) for installation instructions specific to your IDE. -5. Add environment variable -For local testing, you should generally be testing the full 'Security' version of Stirling-PDF. To do this, you must add the environment flag DOCKER_ENABLE_SECURITY=true to your system and/or IDE build/run step. +5. **Frontend Setup (Required for Stirling 2.0)** + Navigate to the frontend directory and install dependencies using npm. -## 4. Project Structure +## 4. Stirling 2.0 Development Workflow + +### Frontend Development (React) +The frontend is a React SPA that runs independently during development: + +1. **Start the backend**: Run the Spring Boot application (serves API endpoints on localhost:8080) +2. **Start the frontend dev server**: Navigate to the frontend directory and run the development server (serves UI on localhost:5173) +3. **Development flow**: The Vite dev server automatically proxies API calls to the backend + +### File Storage Architecture +Stirling 2.0 uses client-side file storage: +- **IndexedDB**: Stores files locally in the browser with automatic thumbnail generation +- **PDF.js**: Handles client-side PDF rendering and processing +- **URL Parameters**: Support for deep linking and tool state persistence + +### Legacy Code Reference +The existing Thymeleaf templates remain in the codebase during development as reference material but will be completely removed for the 2.0 release. + +## 5. Project Structure ```bash Stirling-PDF/ ├── .github/ # GitHub-specific files (workflows, issue templates) ├── configs/ # Configuration files used by stirling at runtime (generated at runtime) -├── cucumber/ # Cucumber test files -│ ├── features/ +├── frontend/ # React SPA frontend (Stirling 2.0) +│ ├── src/ +│ │ ├── components/ # React components +│ │ ├── tools/ # Tool-specific React components +│ │ ├── hooks/ # Custom React hooks +│ │ ├── services/ # API and utility services +│ │ ├── types/ # TypeScript type definitions +│ │ └── utils/ # Utility functions +│ ├── public/ +│ │ └── locales/ # Internationalization files (JSON) +│ ├── package.json # Frontend dependencies +│ └── vite.config.ts # Vite configuration ├── customFiles/ # Custom static files and templates (generated at runtime used to replace existing files) ├── docs/ # Documentation files ├── exampleYmlFiles/ # Example YAML configuration files @@ -84,16 +130,14 @@ Stirling-PDF/ │ │ │ ├── service/ │ │ │ └── utils/ │ │ └── resources/ -│ │ ├── static/ +│ │ ├── static/ # Legacy static assets (reference only) │ │ │ ├── css/ │ │ │ ├── js/ │ │ │ └── pdfjs/ -│ │ └── templates/ +│ │ └── templates/ # Legacy Thymeleaf templates (reference only) │ └── test/ -│ └── java/ -│ └── stirling/ -│ └── software/ -│ └── SPDF/ +├── testing/ # Cucumber and integration tests +│ └── cucumber/ # Cucumber test files ├── build.gradle # Gradle build configuration ├── Dockerfile # Main Dockerfile ├── Dockerfile.ultra-lite # Dockerfile for ultra-lite version @@ -102,7 +146,7 @@ Stirling-PDF/ └── test.sh # Test script to deploy all docker versions and run cuke tests ``` -## 5. Docker-based Development +## 6. Docker-based Development Stirling-PDF offers several Docker versions: @@ -228,6 +272,15 @@ Note: The `test.sh` script will run automatically when you raise a PR. However, 2. Access the application at `http://localhost:8080` and manually test all features developed. +### Frontend Development Testing (Stirling 2.0) + +For React frontend development: + +1. Start the backend: Run the Spring Boot application to serve API endpoints on localhost:8080 +2. Start the frontend dev server: Navigate to the frontend directory and run the development server on localhost:5173 +3. The Vite dev server automatically proxies API calls to the backend +4. Test React components, UI interactions, and IndexedDB file operations using browser developer tools + ### Local Testing (Java and UI Components) For quick iterations and development of Java backend, JavaScript, and UI components, you can run and test Stirling-PDF locally without Docker. This approach allows you to work on and verify changes to: @@ -326,7 +379,56 @@ Remember to test your changes thoroughly to ensure they don't break any existing ## Code examples -### Overview of Thymeleaf +### React Component Development (Stirling 2.0) + +For Stirling 2.0, new features are built as React components instead of Thymeleaf templates: + +#### Creating a New Tool Component + +1. **Create the React Component:** + ```typescript + // frontend/src/tools/NewTool.tsx + import { useState } from 'react'; + import { Button, FileInput, Container } from '@mantine/core'; + + interface NewToolProps { + params: Record; + updateParams: (updates: Record) => void; + } + + export default function NewTool({ params, updateParams }: NewToolProps) { + const [files, setFiles] = useState([]); + + const handleProcess = async () => { + // Process files using API or client-side logic + }; + + return ( + + + + + ); + } + ``` + +2. **Add API Integration:** + ```typescript + // Use existing API endpoints or create new ones + const response = await fetch('/api/v1/new-tool', { + method: 'POST', + body: formData + }); + ``` + +3. **Register in Tool Picker:** + Update the tool picker component to include the new tool with proper routing and URL parameter support. + +### Legacy Reference: Overview of Thymeleaf Thymeleaf is a server-side Java HTML template engine. It is used in Stirling-PDF to render dynamic web pages. Thymeleaf integrates heavily with Spring Boot.