Developer guide updates and claude.md

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

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
+**Backend:**
-- PDFBox
+- Spring Boot (Java 17+, JDK 21 recommended)
-- LibreOffice
+- PDFBox for core PDF operations
-- qpdf
+- LibreOffice for document conversions
-- HTML, CSS, JavaScript
+- qpdf for PDF optimization
-- Docker
+- Spring Security (optional, controlled by `DOCKER_ENABLE_SECURITY`)
-- PDF.js
+- Lombok for reducing boilerplate code
-- PDF-LIB.js
+
-- Lombok
+**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
+5. **Frontend Setup (Required for Stirling 2.0)**
-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.
+   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
+├── frontend/              # React SPA frontend (Stirling 2.0)
-│   ├── features/
+│   ├── 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/
+├── testing/               # Cucumber and integration tests
-│           └── stirling/
+│   └── cucumber/          # Cucumber test files
-│               └── software/
-│                   └── SPDF/
 ├── 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<string, any>;
+     updateParams: (updates: Record<string, any>) => void;
+   }
+   
+   export default function NewTool({ params, updateParams }: NewToolProps) {
+     const [files, setFiles] = useState<File[]>([]);
+     
+     const handleProcess = async () => {
+       // Process files using API or client-side logic
+     };
+     
+     return (
+       <Container>
+         <FileInput 
+           multiple 
+           accept="application/pdf"
+           onChange={setFiles}
+         />
+         <Button onClick={handleProcess}>Process</Button>
+       </Container>
+     );
+   }
+   ```
+
+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.