progress

### Description of Changes

This Pull Request was automatically generated to synchronize updates to
translation files and documentation for the **V2 branch**. Below are the
details of the changes made:

#### **1. Synchronization of Translation Files**
- Updated translation files
(`frontend/public/locales/*/translation.json`) to reflect changes in the
reference file `en-GB/translation.json`.
- Ensured consistency and synchronization across all supported language
files.
- Highlighted any missing or incomplete translations.

#### **2. Update README.md**
- Generated the translation progress table in `README.md`.
- Added a summary of the current translation status for all supported
languages.
- Included up-to-date statistics on translation coverage.

#### **Why these changes are necessary**
- Keeps translation files aligned with the latest reference updates.
- Ensures the documentation reflects the current translation progress.

---

Auto-generated by [create-pull-request][1].

[1]: https://github.com/peter-evans/create-pull-request

Co-authored-by: stirlingbot[bot] <195170888+stirlingbot[bot]@users.noreply.github.com>

.claude/settings.local.json

@@ -1,21 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(chmod:*)",
-      "Bash(mkdir:*)",
-      "Bash(./gradlew:*)",
-      "Bash(grep:*)",
-      "Bash(cat:*)",
-      "Bash(find:*)",
-      "Bash(npm test)",
-      "Bash(npm test:*)",
-      "Bash(ls:*)",
-      "Bash(npx tsc:*)",
-      "Bash(node:*)",
-      "Bash(npm run dev:*)",
-      "Bash(sed:*)"
-    ],
-    "deny": [],
-    "defaultMode": "acceptEdits"
-  }
-}

.editorconfig

@@ -24,7 +24,7 @@ indent_size = 2
 insert_final_newline = false
 trim_trailing_whitespace = false
 
-[{*.js,*.jsx,*.ts,*.tsx}]
+[{*.js,*.jsx,*.mjs,*.ts,*.tsx}]
 indent_size = 2
 
 [*.css]

.github/scripts/check_language_json.py

@@ -0,0 +1,345 @@
+"""
+Author: Ludy87
+Description: This script processes JSON translation files for localization checks. It compares translation files in a branch with
+a reference file to ensure consistency. The script performs two main checks:
+1. Verifies that the number of translation keys in the translation files matches the reference file.
+2. Ensures that all keys in the translation files are present in the reference file and vice versa.
+
+The script also provides functionality to update the translation files to match the reference file by adding missing keys and
+adjusting the format.
+
+Usage:
+    python check_language_json.py --reference-file <path_to_reference_file> --branch <branch_name> [--actor <actor_name>] [--files <list_of_changed_files>]
+"""
+# Sample for Windows:
+# python .github/scripts/check_language_json.py --reference-file frontend/public/locales/en-GB/translation.json --branch "" --files frontend/public/locales/de-DE/translation.json frontend/public/locales/fr-FR/translation.json
+
+import copy
+import glob
+import os
+import argparse
+import re
+import json
+
+
+def find_duplicate_keys(file_path, keys=None, prefix=""):
+    """
+    Identifies duplicate keys in a JSON file (including nested keys).
+    :param file_path: Path to the JSON file.
+    :param keys: Dictionary to track keys (used for recursion).
+    :param prefix: Prefix for nested keys.
+    :return: List of tuples (key, first_occurrence_path, duplicate_path).
+    """
+    if keys is None:
+        keys = {}
+
+    duplicates = []
+
+    with open(file_path, "r", encoding="utf-8") as file:
+        data = json.load(file)
+
+    def process_dict(obj, current_prefix=""):
+        for key, value in obj.items():
+            full_key = f"{current_prefix}.{key}" if current_prefix else key
+
+            if isinstance(value, dict):
+                process_dict(value, full_key)
+            else:
+                if full_key in keys:
+                    duplicates.append((full_key, keys[full_key], full_key))
+                else:
+                    keys[full_key] = full_key
+
+    process_dict(data, prefix)
+    return duplicates
+
+
+# Maximum size for JSON files (e.g., 500 KB)
+MAX_FILE_SIZE = 500 * 1024
+
+
+def parse_json_file(file_path):
+    """
+    Parses a JSON translation file and returns a flat dictionary of all keys.
+    :param file_path: Path to the JSON file.
+    :return: Dictionary with flattened keys.
+    """
+    with open(file_path, "r", encoding="utf-8") as file:
+        data = json.load(file)
+
+    def flatten_dict(d, parent_key="", sep="."):
+        items = {}
+        for k, v in d.items():
+            new_key = f"{parent_key}{sep}{k}" if parent_key else k
+            if isinstance(v, dict):
+                items.update(flatten_dict(v, new_key, sep=sep))
+            else:
+                items[new_key] = v
+        return items
+
+    return flatten_dict(data)
+
+
+def unflatten_dict(d, sep="."):
+    """
+    Converts a flat dictionary with dot notation keys back to nested dict.
+    :param d: Flattened dictionary.
+    :param sep: Separator used in keys.
+    :return: Nested dictionary.
+    """
+    result = {}
+    for key, value in d.items():
+        parts = key.split(sep)
+        current = result
+        for part in parts[:-1]:
+            if part not in current:
+                current[part] = {}
+            current = current[part]
+        current[parts[-1]] = value
+    return result
+
+
+def write_json_file(file_path, updated_properties):
+    """
+    Writes updated properties back to the JSON file.
+    :param file_path: Path to the JSON file.
+    :param updated_properties: Dictionary of updated properties to write.
+    """
+    nested_data = unflatten_dict(updated_properties)
+
+    with open(file_path, "w", encoding="utf-8", newline="\n") as file:
+        json.dump(nested_data, file, ensure_ascii=False, indent=2)
+        file.write("\n")  # Add trailing newline
+
+
+def update_missing_keys(reference_file, file_list, branch=""):
+    """
+    Updates missing keys in the translation files based on the reference file.
+    :param reference_file: Path to the reference JSON file.
+    :param file_list: List of translation files to update.
+    :param branch: Branch where the files are located.
+    """
+    reference_properties = parse_json_file(reference_file)
+
+    for file_path in file_list:
+        basename_current_file = os.path.basename(os.path.join(branch, file_path))
+        if (
+            basename_current_file == os.path.basename(reference_file)
+            or not file_path.endswith(".json")
+            or not os.path.dirname(file_path).endswith("locales")
+        ):
+            continue
+
+        current_properties = parse_json_file(os.path.join(branch, file_path))
+        updated_properties = {}
+
+        for ref_key, ref_value in reference_properties.items():
+            if ref_key in current_properties:
+                # Keep the current translation
+                updated_properties[ref_key] = current_properties[ref_key]
+            else:
+                # Add missing key with reference value
+                updated_properties[ref_key] = ref_value
+
+        write_json_file(os.path.join(branch, file_path), updated_properties)
+
+
+def check_for_missing_keys(reference_file, file_list, branch):
+    update_missing_keys(reference_file, file_list, branch)
+
+
+def read_json_keys(file_path):
+    if os.path.isfile(file_path) and os.path.exists(file_path):
+        return parse_json_file(file_path)
+    return {}
+
+
+def check_for_differences(reference_file, file_list, branch, actor):
+    reference_branch = branch
+    basename_reference_file = os.path.basename(reference_file)
+
+    report = []
+    report.append(f"#### 🔄 Reference Branch: `{reference_branch}`")
+    reference_keys = read_json_keys(reference_file)
+    has_differences = False
+
+    only_reference_file = True
+
+    file_arr = file_list
+
+    if len(file_list) == 1:
+        file_arr = file_list[0].split()
+
+    base_dir = os.path.abspath(
+        os.path.join(os.getcwd(), "frontend", "public", "locales")
+    )
+
+    for file_path in file_arr:
+        file_normpath = os.path.normpath(file_path)
+        absolute_path = os.path.abspath(file_normpath)
+
+        # Verify that file is within the expected directory
+        if not absolute_path.startswith(base_dir):
+            raise ValueError(f"Unsafe file found: {file_normpath}")
+
+        # Verify file size before processing
+        if os.path.getsize(os.path.join(branch, file_normpath)) > MAX_FILE_SIZE:
+            raise ValueError(
+                f"The file {file_normpath} is too large and could pose a security risk."
+            )
+
+        basename_current_file = os.path.basename(os.path.join(branch, file_normpath))
+        locale_dir = os.path.basename(os.path.dirname(file_normpath))
+
+        if (
+            basename_current_file == basename_reference_file
+            and locale_dir == "en-GB"
+        ):
+            continue
+
+        if not file_normpath.endswith(".json") or basename_current_file != "translation.json":
+            continue
+
+        only_reference_file = False
+        report.append(f"#### 📃 **File Check:** `{locale_dir}/{basename_current_file}`")
+        current_keys = read_json_keys(os.path.join(branch, file_path))
+        reference_key_count = len(reference_keys)
+        current_key_count = len(current_keys)
+
+        if reference_key_count != current_key_count:
+            report.append("")
+            report.append("1. **Test Status:** ❌ **_Failed_**")
+            report.append("  - **Issue:**")
+            has_differences = True
+            if reference_key_count > current_key_count:
+                report.append(
+                    f"    - **_Mismatched key count_**: {reference_key_count} (reference) vs {current_key_count} (current). Translation keys are missing."
+                )
+            elif reference_key_count < current_key_count:
+                report.append(
+                    f"    - **_Too many keys_**: {reference_key_count} (reference) vs {current_key_count} (current). Please verify if there are additional keys that need to be removed."
+                )
+        else:
+            report.append("1. **Test Status:** ✅ **_Passed_**")
+
+        # Check for missing or extra keys
+        current_keys_set = set(current_keys.keys())
+        reference_keys_set = set(reference_keys.keys())
+        missing_keys = current_keys_set.difference(reference_keys_set)
+        extra_keys = reference_keys_set.difference(current_keys_set)
+        missing_keys_list = list(missing_keys)
+        extra_keys_list = list(extra_keys)
+
+        if missing_keys_list or extra_keys_list:
+            has_differences = True
+            missing_keys_str = "`, `".join(missing_keys_list)
+            extra_keys_str = "`, `".join(extra_keys_list)
+            report.append("2. **Test Status:** ❌ **_Failed_**")
+            report.append("  - **Issue:**")
+            if missing_keys_list:
+                report.append(
+                    f"    - **_Extra keys in `{locale_dir}/{basename_current_file}`_**: `{missing_keys_str}` that are not present in **_`{basename_reference_file}`_**."
+                )
+            if extra_keys_list:
+                report.append(
+                    f"    - **_Missing keys in `{locale_dir}/{basename_current_file}`_**: `{extra_keys_str}` that are not present in **_`{basename_reference_file}`_**."
+                )
+        else:
+            report.append("2. **Test Status:** ✅ **_Passed_**")
+
+        if find_duplicate_keys(os.path.join(branch, file_normpath)):
+            has_differences = True
+            output = "\n".join(
+                [
+                    f"      - `{key}`: first at {first}, duplicate at `{duplicate}`"
+                    for key, first, duplicate in find_duplicate_keys(
+                        os.path.join(branch, file_normpath)
+                    )
+                ]
+            )
+            report.append("3. **Test Status:** ❌ **_Failed_**")
+            report.append("  - **Issue:**")
+            report.append("    - duplicate entries were found:")
+            report.append(output)
+        else:
+            report.append("3. **Test Status:** ✅ **_Passed_**")
+
+        report.append("")
+        report.append("---")
+        report.append("")
+
+    if has_differences:
+        report.append("## ❌ Overall Check Status: **_Failed_**")
+        report.append("")
+        report.append(
+            f"@{actor} please check your translation if it conforms to the standard. Follow the format of [en-GB/translation.json](https://github.com/Stirling-Tools/Stirling-PDF/blob/V2/frontend/public/locales/en-GB/translation.json)"
+        )
+    else:
+        report.append("## ✅ Overall Check Status: **_Success_**")
+        report.append("")
+        report.append(
+            f"Thanks @{actor} for your help in keeping the translations up to date."
+        )
+
+    if not only_reference_file:
+        print("\n".join(report))
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Find missing keys")
+    parser.add_argument(
+        "--actor",
+        required=False,
+        help="Actor from PR.",
+    )
+    parser.add_argument(
+        "--reference-file",
+        required=True,
+        help="Path to the reference file.",
+    )
+    parser.add_argument(
+        "--branch",
+        type=str,
+        required=True,
+        help="Branch name.",
+    )
+    parser.add_argument(
+        "--check-file",
+        type=str,
+        required=False,
+        help="List of changed files, separated by spaces.",
+    )
+    parser.add_argument(
+        "--files",
+        nargs="+",
+        required=False,
+        help="List of changed files, separated by spaces.",
+    )
+    args = parser.parse_args()
+
+    # Sanitize --actor input to avoid injection attacks
+    if args.actor:
+        args.actor = re.sub(r"[^a-zA-Z0-9_\\-]", "", args.actor)
+
+    # Sanitize --branch input to avoid injection attacks
+    if args.branch:
+        args.branch = re.sub(r"[^a-zA-Z0-9\\-]", "", args.branch)
+
+    file_list = args.files
+    if file_list is None:
+        if args.check_file:
+            file_list = [args.check_file]
+        else:
+            file_list = glob.glob(
+                os.path.join(
+                    os.getcwd(),
+                    "frontend",
+                    "public",
+                    "locales",
+                    "*",
+                    "translation.json",
+                )
+            )
+        update_missing_keys(args.reference_file, file_list)
+    else:
+        check_for_differences(args.reference_file, file_list, args.branch, args.actor)

.github/workflows/PR-Auto-Deploy-V2.yml

@@ -3,7 +3,15 @@ name: Auto PR V2 Deployment
 on:
   pull_request:
     types: [opened, synchronize, reopened, closed]
-
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: "PR number to deploy"
+        required: true
+      allow_fork:
+        description: "Allow deploying fork PR?"
+        required: false
+        default: "false"
 
 permissions:
   contents: read
@@ -12,102 +20,93 @@ permissions:
 
 jobs:
   check-pr:
-    if: github.event.action != 'closed'
+    if: (github.event_name == 'pull_request' && github.event.action != 'closed') || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     outputs:
-      should_deploy: ${{ steps.check-conditions.outputs.should_deploy }}
-      pr_number: ${{ github.event.number }}
-      pr_repository: ${{ steps.get-pr-info.outputs.repository }}
-      pr_ref: ${{ steps.get-pr-info.outputs.ref }}
+      should_deploy: ${{ steps.decide.outputs.should_deploy }}
+      is_fork: ${{ steps.resolve.outputs.is_fork }}
+      allow_fork: ${{ steps.decide.outputs.allow_fork }}
+      pr_number: ${{ steps.resolve.outputs.pr_number }}
+      pr_repository: ${{ steps.resolve.outputs.repository }}
+      pr_ref: ${{ steps.resolve.outputs.ref }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
-      - name: Check deployment conditions
-        id: check-conditions
+      - name: Resolve PR info
+        id: resolve
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            let prNumber = context.eventName === 'workflow_dispatch'
+              ? parseInt(process.env.INPUT_PR, 10)
+              : context.payload.number;
+
+            if (!Number.isInteger(prNumber)) { core.setFailed('Invalid PR number'); return; }
+
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            core.setOutput('pr_number', String(prNumber));
+            core.setOutput('repository', pr.head.repo.full_name);
+            core.setOutput('ref', pr.head.ref);
+            core.setOutput('is_fork', String(pr.head.repo.fork));
+            core.setOutput('base_ref', pr.base.ref);
+            core.setOutput('author', pr.user.login);
+            core.setOutput('state', pr.state);
+
+      - name: Decide deploy
+        id: decide
+        shell: bash
         env:
+          EVENT_NAME: ${{ github.event_name }}
+          STATE: ${{ steps.resolve.outputs.state }}
+          IS_FORK: ${{ steps.resolve.outputs.is_fork }}
+          # nur bei workflow_dispatch gesetzt:
+          ALLOW_FORK_INPUT: ${{ inputs.allow_fork }}
+          # für Auto-PR-Logik:
           PR_TITLE: ${{ github.event.pull_request.title }}
-          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
           PR_BRANCH: ${{ github.event.pull_request.head.ref }}
+          PR_BASE: ${{ steps.resolve.outputs.base_ref }}
+          PR_AUTHOR: ${{ steps.resolve.outputs.author }}
         run: |
-          echo "PR Title: $PR_TITLE"
-          echo "PR Author: $PR_AUTHOR"
-          echo "PR Branch: $PR_BRANCH"
-          echo "PR Base Branch: ${{ github.event.pull_request.base.ref }}"
-          
-          # Define authorized users
-          authorized_users=(
-            "Frooodle"
-            "sf298"
-            "Ludy87"
-            "LaserKaspar"
-            "sbplat"
-            "reecebrowne"
-            "DarioGii"
-            "ConnorYoh"
-            "EthanHealy01"
-            "jbrunton96"
-          )
-          
-          # Check if author is in the authorized list
-          is_authorized=false
-          for user in "${authorized_users[@]}"; do
-            if [[ "$PR_AUTHOR" == "$user" ]]; then
-              is_authorized=true
-              break
+          set -e
+          # Standard: nichts deployen
+          should=false
+          allow_fork="$(echo "${ALLOW_FORK_INPUT:-false}" | tr '[:upper:]' '[:lower:]')"
+
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            if [ "$STATE" != "open" ]; then
+              echo "PR not open -> skip"
+            else
+              if [ "$IS_FORK" = "true" ] && [ "$allow_fork" != "true" ]; then
+                echo "Fork PR and allow_fork=false -> skip"
+              else
+                should=true
+              fi
             fi
-          done
-          
-          # If PR is targeting V2 and user is authorized, deploy unconditionally
-          PR_BASE_BRANCH="${{ github.event.pull_request.base.ref }}"
-          if [[ "$PR_BASE_BRANCH" == "V2" && "$is_authorized" == "true" ]]; then
-            echo "✅ Deployment forced: PR targets V2 and author is authorized."
-            echo "should_deploy=true" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-          
-          # Otherwise, continue with original keyword checks
-          has_v2_keyword=false
-          if [[ "$PR_TITLE" =~ [Vv]2 ]] || [[ "$PR_TITLE" =~ [Vv]ersion.?2 ]] || [[ "$PR_TITLE" =~ [Vv]ersion.?[Tt]wo ]]; then
-            has_v2_keyword=true
-          fi
-          
-          has_branch_keyword=false
-          if [[ "$PR_BRANCH" =~ [Vv]2 ]] || [[ "$PR_BRANCH" =~ [Rr]eact ]]; then
-            has_branch_keyword=true
-          fi
-          
-          if [[ "$is_authorized" == "true" && ( "$has_v2_keyword" == "true" || "$has_branch_keyword" == "true" ) ]]; then
-            echo "✅ Deployment conditions met"
-            echo "should_deploy=true" >> $GITHUB_OUTPUT
           else
-            echo "❌ Deployment conditions not met"
-            echo "  - Authorized user: $is_authorized"
-            echo "  - Has V2 keyword in title: $has_v2_keyword"
-            echo "  - Has V2/React keyword in branch: $has_branch_keyword"
-            echo "should_deploy=false" >> $GITHUB_OUTPUT
+            auth_users=("Frooodle" "sf298" "Ludy87" "LaserKaspar" "sbplat" "reecebrowne" "DarioGii" "ConnorYoh" "EthanHealy01" "jbrunton96")
+            is_auth=false; for u in "${auth_users[@]}"; do [ "$u" = "$PR_AUTHOR" ] && is_auth=true && break; done
+            if [ "$PR_BASE" = "V2" ] && [ "$is_auth" = true ]; then
+              should=true
+            else
+              title_has_v2=false; echo "$PR_TITLE" | grep -qiE 'v2|version.?2|version.?two' && title_has_v2=true
+              branch_has_kw=false; echo "$PR_BRANCH" | grep -qiE 'v2|react' && branch_has_kw=true
+              if [ "$is_auth" = true ] && { [ "$title_has_v2" = true ] || [ "$branch_has_kw" = true ]; }; then
+                should=true
+              fi
+            fi
           fi
 
-      - name: Get PR repository and ref
-        id: get-pr-info
-        if: steps.check-conditions.outputs.should_deploy == 'true'
-        run: |
-          # For forks, use the full repository name, for internal PRs use the current repo
-          if [[ "${{ github.event.pull_request.head.repo.fork }}" == "true" ]]; then
-            repository="${{ github.event.pull_request.head.repo.full_name }}"
-          else
-            repository="${{ github.repository }}"
-          fi
-          
-          echo "repository=$repository" >> $GITHUB_OUTPUT
-          echo "ref=${{ github.event.pull_request.head.ref }}" >> $GITHUB_OUTPUT
+          echo "should_deploy=$should" >> $GITHUB_OUTPUT
+          echo "allow_fork=${allow_fork:-false}" >> $GITHUB_OUTPUT
 
   deploy-v2-pr:
     needs: check-pr
     runs-on: ubuntu-latest
-    if: needs.check-pr.outputs.should_deploy == 'true'
+    if: needs.check-pr.outputs.should_deploy == 'true' && (needs.check-pr.outputs.is_fork == 'false' || needs.check-pr.outputs.allow_fork == 'true')
     # Concurrency control - only one deployment per PR at a time
     concurrency:
       group: v2-deploy-pr-${{ needs.check-pr.outputs.pr_number }}
@@ -119,7 +118,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
         with:
           egress-policy: audit
 
@@ -154,13 +153,13 @@ jobs:
               issue_number: prNumber,
               per_page: 100
             });
-            
+
             const v2Comments = comments.filter(comment => 
               comment.body.includes('🚀 **Auto-deploying V2 version**') ||
               comment.body.includes('## 🚀 V2 Auto-Deployment Complete!') ||
               comment.body.includes('❌ **V2 Auto-deployment failed**')
             );
-            
+
             for (const comment of v2Comments) {
               console.log(`Deleting old V2 comment: ${comment.id}`);
               await github.rest.issues.deleteComment({
@@ -177,7 +176,6 @@ jobs:
               issue_number: prNumber,
               body: `🚀 **Auto-deploying V2 version** for PR #${prNumber}...\n\n_This is an automated deployment triggered by V2/version2 keywords in the PR title or V2/React keywords in the branch name._\n\n⚠️ **Note:** If new commits are pushed during deployment, this build will be cancelled and replaced with the latest version.`
             });
-            
             return newComment.id;
 
       - name: Checkout PR
@@ -188,7 +186,6 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           fetch-depth: 0  # Fetch full history for commit hash detection
 
-
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
 
@@ -212,7 +209,7 @@ jobs:
           if [ -z "$FRONTEND_HASH" ]; then
             FRONTEND_HASH="no-frontend-changes"
           fi
-          
+
           # Get last commit that touched backend code, docker/backend, or docker/compose
           BACKEND_HASH=$(git log -1 --format="%H" -- app/ docker/backend/ docker/compose/ 2>/dev/null || echo "")
           if [ -z "$BACKEND_HASH" ]; then
@@ -321,7 +318,7 @@ jobs:
                 SWAGGER_SERVER_URL: "https://${V2_PORT}.ssl.stirlingpdf.cloud"
                 baseUrl: "https://${V2_PORT}.ssl.stirlingpdf.cloud"
               restart: on-failure:5
-              
+
             stirling-pdf-v2-frontend:
               container_name: stirling-pdf-v2-frontend-pr-${{ needs.check-pr.outputs.pr_number }}
               image: ${{ secrets.DOCKER_HUB_USERNAME }}/test:v2-frontend-${{ steps.commit-hashes.outputs.frontend_short }}
@@ -354,7 +351,7 @@ jobs:
             
             # Clean up unused Docker resources to save space
             docker system prune -af --volumes || true
-            
+
             # Clean up old backend/frontend images (older than 2 weeks)
             docker image prune -af --filter "until=336h" --filter "label!=keep=true" || true
           ENDSSH
@@ -492,7 +489,7 @@ jobs:
             
             # Clean up old unused images (older than 2 weeks) but keep recent ones for reuse
             docker image prune -af --filter "until=336h" --filter "label!=keep=true" || true
-            
+
             # Note: We don't remove the commit-based images since they can be reused across PRs
             # Only remove PR-specific containers and directories
           ENDSSH
@@ -501,5 +498,4 @@ jobs:
         if: always()
         run: |
           rm -f ../private.key
-        continue-on-error: true
-
+        continue-on-error: true

.github/workflows/build.yml

@@ -147,6 +147,8 @@ jobs:
           cache-dependency-path: frontend/package-lock.json
       - name: Install frontend dependencies
         run: cd frontend && npm ci
+      - name: Lint frontend
+        run: cd frontend && npm run lint
       - name: Build frontend
         run: cd frontend && npm run build
       - name: Run frontend tests

.github/workflows/frontend-licenses-update.yml

@@ -12,6 +12,7 @@ on:
     branches:
       - V2
     paths:
+      - ".github/workflows/frontend-licenses-update.yml"
       - "frontend/package.json"
       - "frontend/package-lock.json"
       - "frontend/scripts/generate-licenses.js"
@@ -28,37 +29,81 @@ jobs:
       repository-projects: write # Required for enabling automerge
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:
           egress-policy: audit
 
-      - name: Check out code
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Checkout PR head (default)
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Setup GitHub App Bot
+        if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false)
         id: setup-bot
         uses: ./.github/actions/setup-bot
         with:
           app-id: ${{ secrets.GH_APP_ID }}
           private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
 
-      - name: Set up Node.js
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+      - name: Checkout BASE branch (safe script)
+        if: github.event_name == 'pull_request'
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
-          node-version: '18'
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          node-version: '22'
           cache: 'npm'
           cache-dependency-path: frontend/package-lock.json
 
       - name: Install frontend dependencies
         working-directory: frontend
-        run: npm ci
+        env:
+          NPM_CONFIG_IGNORE_SCRIPTS: "true"
+        run: npm ci --ignore-scripts --audit=false --fund=false
 
-      - name: Generate frontend license report
+      - name: Generate frontend license report (internal PR)
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
         working-directory: frontend
+        env:
+          PR_IS_FORK: "false"
         run: npm run generate-licenses
 
+      - name: Generate frontend license report (fork PRs, pinned)
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
+        env:
+          NPM_CONFIG_IGNORE_SCRIPTS: "true"
+        working-directory: frontend
+        run: |
+          mkdir -p src/assets
+          npx --yes license-report --only=prod --output=json > src/assets/3rdPartyLicenses.json
+
+      - name: Postprocess with project script (BASE version)
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
+        env:
+          PR_IS_FORK: "true"
+        run: |
+          node base/frontend/scripts/generate-licenses.js \
+            --input frontend/src/assets/3rdPartyLicenses.json
+
+      - name: Copy postprocessed artifacts back (fork PRs)
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
+        run: |
+          mkdir -p frontend/src/assets
+          if [ -f "base/frontend/src/assets/3rdPartyLicenses.json" ]; then
+            cp base/frontend/src/assets/3rdPartyLicenses.json frontend/src/assets/3rdPartyLicenses.json
+          fi
+          if [ -f "base/frontend/src/assets/license-warnings.json" ]; then
+            cp base/frontend/src/assets/license-warnings.json frontend/src/assets/license-warnings.json
+          fi
+
       - name: Check for license warnings
         run: |
           if [ -f "frontend/src/assets/license-warnings.json" ]; then
@@ -69,8 +114,8 @@ jobs:
 
       # PR Event: Check licenses and comment on PR
       - name: Delete previous license check comments
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |
@@ -101,9 +146,29 @@ jobs:
               });
             }
 
+      - name: Summarize results (fork PRs)
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
+        run: |
+          {
+            echo "## Frontend License Check"
+            echo ""
+            if [ "${LICENSE_WARNINGS_EXIST}" = "true" ]; then
+              echo "❌ **Failed** – incompatible or unknown licenses found."
+              if [ -f "frontend/src/assets/license-warnings.json" ]; then
+                echo ""
+                echo "### Warnings"
+                jq -r '.warnings[] | "- \(.message)"' frontend/src/assets/license-warnings.json || true
+              fi
+            else
+              echo "✅ **Passed** – no license warnings detected."
+            fi
+            echo ""
+            echo "_Note: This is a fork PR. PR comments are disabled; use this summary._"
+          } >> "$GITHUB_STEP_SUMMARY"
+
       - name: Comment on PR - License Check Results
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           github-token: ${{ steps.setup-bot.outputs.token }}
           script: |

.github/workflows/sync_files_v2.yml

@@ -0,0 +1,118 @@
+name: Sync Files V2
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - V2
+      - syncLangTest
+    paths:
+      - "build.gradle"
+      - "README.md"
+      - "frontend/public/locales/*/translation.json"
+      - "app/core/src/main/resources/static/3rdPartyLicenses.json"
+      - "scripts/ignore_translation.toml"
+
+# cancel in-progress jobs if a new job is triggered
+# This is useful to avoid running multiple builds for the same branch if a new commit is pushed
+# or a pull request is updated.
+# It helps to save resources and time by ensuring that only the latest commit is built and tested
+# This is particularly useful for long-running jobs that may take a while to complete.
+# The `group` is set to a combination of the workflow name, event name, and branch name.
+# This ensures that jobs are grouped by the workflow and branch, allowing for cancellation of
+# in-progress jobs when a new commit is pushed to the same branch or a new pull request is opened.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref_name || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  sync-files:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+
+      - name: Setup GitHub App Bot
+        id: setup-bot
+        uses: ./.github/actions/setup-bot
+        with:
+          app-id: ${{ secrets.GH_APP_ID }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+          cache: "pip" # caching pip dependencies
+
+      - name: Sync translation JSON files
+        run: |
+          python .github/scripts/check_language_json.py --reference-file "frontend/public/locales/en-GB/translation.json" --branch V2
+
+      - name: Commit translation files
+        run: |
+          git add frontend/public/locales/*/translation.json
+          git diff --staged --quiet || git commit -m ":memo: Sync translation files" || echo "No changes detected"
+
+      - name: Install dependencies
+        run: pip install --require-hashes -r ./.github/scripts/requirements_sync_readme.txt
+
+      - name: Sync README.md
+        run: |
+          python scripts/counter_translation_v2.py
+
+      - name: Run git add
+        run: |
+          git add README.md scripts/ignore_translation.toml
+          git diff --staged --quiet || git commit -m ":memo: Sync README.md & scripts/ignore_translation.toml" || echo "No changes detected"
+
+      - name: Create Pull Request
+        if: always()
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
+        with:
+          token: ${{ steps.setup-bot.outputs.token }}
+          commit-message: Update files
+          committer: ${{ steps.setup-bot.outputs.committer }}
+          author: ${{ steps.setup-bot.outputs.committer }}
+          signoff: true
+          branch: sync_readme_v2
+          base: V2
+          title: ":globe_with_meridians: [V2] Sync Translations + Update README Progress Table"
+          body: |
+            ### Description of Changes
+
+            This Pull Request was automatically generated to synchronize updates to translation files and documentation for the **V2 branch**. Below are the details of the changes made:
+
+            #### **1. Synchronization of Translation Files**
+            - Updated translation files (`frontend/public/locales/*/translation.json`) to reflect changes in the reference file `en-GB/translation.json`.
+            - Ensured consistency and synchronization across all supported language files.
+            - Highlighted any missing or incomplete translations.
+
+            #### **2. Update README.md**
+            - Generated the translation progress table in `README.md`.
+            - Added a summary of the current translation status for all supported languages.
+            - Included up-to-date statistics on translation coverage.
+
+            #### **Why these changes are necessary**
+            - Keeps translation files aligned with the latest reference updates.
+            - Ensures the documentation reflects the current translation progress.
+
+            ---
+
+            Auto-generated by [create-pull-request][1].
+
+            [1]: https://github.com/peter-evans/create-pull-request
+          draft: false
+          delete-branch: true
+          labels: github-actions
+          sign-commits: true
+          add-paths: |
+            README.md
+            frontend/public/locales/*/translation.json

.gitignore

@@ -203,3 +203,10 @@ id_ed25519.pub
 
 # node_modules
 node_modules/
+
+# Translation temp files
+*_compact.json
+*compact*.json
+test_batch.json
+*.backup.*.json
+frontend/public/locales/*/translation.backup*.json

.vscode/extensions.json

@@ -19,5 +19,6 @@
     "yzhang.markdown-all-in-one", // Markdown All-in-One extension for enhanced Markdown editing
     "stylelint.vscode-stylelint", // Stylelint extension for CSS and SCSS linting
     "redhat.vscode-yaml", // YAML extension for Visual Studio Code
+    "dbaeumer.vscode-eslint", // ESLint extension for TypeScript linting
   ]
 }

.vscode/settings.json

@@ -139,5 +139,8 @@
     "app/core/src/main/java",
     "app/common/src/main/java",
     "app/proprietary/src/main/java"
-  ]
+  ],
+  "[typescript]": {
+    "editor.defaultFormatter": "vscode.typescript-language-features"
+  }
 }

ADDING_TOOLS.md

@@ -0,0 +1,300 @@
+# Adding New React Tools to Stirling PDF
+
+This guide covers how to add new PDF tools to the React frontend, either by migrating existing Thymeleaf templates or creating entirely new tools.
+
+## Overview
+
+When adding tools, follow this systematic approach using the established patterns and architecture.
+
+## 1. Create Tool Structure
+
+Create these files in the correct directories:
+```
+frontend/src/hooks/tools/[toolName]/
+  ├── use[ToolName]Parameters.ts     # Parameter definitions and validation
+  └── use[ToolName]Operation.ts      # Tool operation logic using useToolOperation
+
+frontend/src/components/tools/[toolName]/
+  └── [ToolName]Settings.tsx         # Settings UI component (if needed)
+
+frontend/src/tools/
+  └── [ToolName].tsx                 # Main tool component
+```
+
+## 2. Implementation Pattern
+
+Use `useBaseTool` for simplified hook management. This is the recommended approach for all new tools:
+
+**Parameters Hook** (`use[ToolName]Parameters.ts`):
+```typescript
+import { BaseParameters } from '../../../types/parameters';
+import { useBaseParameters, BaseParametersHook } from '../shared/useBaseParameters';
+
+export interface [ToolName]Parameters extends BaseParameters {
+  // Define your tool-specific parameters here
+  someOption: boolean;
+}
+
+export const defaultParameters: [ToolName]Parameters = {
+  someOption: false,
+};
+
+export const use[ToolName]Parameters = (): BaseParametersHook<[ToolName]Parameters> => {
+  return useBaseParameters({
+    defaultParameters,
+    endpointName: 'your-endpoint-name',
+    validateFn: (params) => true, // Add validation logic
+  });
+};
+```
+
+**Operation Hook** (`use[ToolName]Operation.ts`):
+```typescript
+import { useTranslation } from 'react-i18next';
+import { ToolType, useToolOperation } from '../shared/useToolOperation';
+import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
+
+export const build[ToolName]FormData = (parameters: [ToolName]Parameters, file: File): FormData => {
+  const formData = new FormData();
+  formData.append('fileInput', file);
+  // Add parameters to formData
+  return formData;
+};
+
+export const [toolName]OperationConfig = {
+  toolType: ToolType.singleFile, // or ToolType.multiFile (buildFormData's file parameter will need to be updated)
+  buildFormData: build[ToolName]FormData,
+  operationType: '[toolName]',
+  endpoint: '/api/v1/category/endpoint-name',
+  filePrefix: 'processed_', // Will be overridden with translation
+  defaultParameters,
+} as const;
+
+export const use[ToolName]Operation = () => {
+  const { t } = useTranslation();
+  return useToolOperation({
+    ...[toolName]OperationConfig,
+    filePrefix: t('[toolName].filenamePrefix', 'processed') + '_',
+    getErrorMessage: createStandardErrorHandler(t('[toolName].error.failed', 'Operation failed'))
+  });
+};
+```
+
+**Main Component** (`[ToolName].tsx`):
+```typescript
+import { useTranslation } from "react-i18next";
+import { createToolFlow } from "../components/tools/shared/createToolFlow";
+import { use[ToolName]Parameters } from "../hooks/tools/[toolName]/use[ToolName]Parameters";
+import { use[ToolName]Operation } from "../hooks/tools/[toolName]/use[ToolName]Operation";
+import { useBaseTool } from "../hooks/tools/shared/useBaseTool";
+import { BaseToolProps, ToolComponent } from "../types/tool";
+
+const [ToolName] = (props: BaseToolProps) => {
+  const { t } = useTranslation();
+  const base = useBaseTool('[toolName]', use[ToolName]Parameters, use[ToolName]Operation, props);
+
+  return createToolFlow({
+    files: {
+      selectedFiles: base.selectedFiles,
+      isCollapsed: base.hasResults,
+      placeholder: t("[toolName].files.placeholder", "Select files to get started"),
+    },
+    steps: [
+      // Add settings steps if needed
+    ],
+    executeButton: {
+      text: t("[toolName].submit", "Process"),
+      isVisible: !base.hasResults,
+      loadingText: t("loading"),
+      onClick: base.handleExecute,
+      disabled: !base.params.validateParameters() || !base.hasFiles || !base.endpointEnabled,
+    },
+    review: {
+      isVisible: base.hasResults,
+      operation: base.operation,
+      title: t("[toolName].results.title", "Results"),
+      onFileClick: base.handleThumbnailClick,
+      onUndo: base.handleUndo,
+    },
+  });
+};
+
+[ToolName].tool = () => use[ToolName]Operation;
+export default [ToolName] as ToolComponent;
+```
+
+**Note**: Some existing tools (like AddPassword, Compress) use a legacy pattern with manual hook management. **Always use the Modern Pattern above for new tools** - it's cleaner, more maintainable, and includes automation support.
+
+## 3. Register Tool in System
+Update these files to register your new tool:
+
+**Tool Registry** (`frontend/src/data/useTranslatedToolRegistry.tsx`):
+1. Add imports at the top:
+```typescript
+import [ToolName] from "../tools/[ToolName]";
+import { [toolName]OperationConfig } from "../hooks/tools/[toolName]/use[ToolName]Operation";
+import [ToolName]Settings from "../components/tools/[toolName]/[ToolName]Settings";
+```
+
+2. Add tool entry in the `allTools` object:
+```typescript
+[toolName]: {
+  icon: <LocalIcon icon="your-icon-name" width="1.5rem" height="1.5rem" />,
+  name: t("home.[toolName].title", "Tool Name"),
+  component: [ToolName],
+  description: t("home.[toolName].desc", "Tool description"),
+  categoryId: ToolCategoryId.STANDARD_TOOLS, // or appropriate category
+  subcategoryId: SubcategoryId.APPROPRIATE_SUBCATEGORY,
+  maxFiles: -1, // or specific number
+  endpoints: ["endpoint-name"],
+  operationConfig: [toolName]OperationConfig,
+  settingsComponent: [ToolName]Settings, // if settings exist
+},
+```
+
+## 4. Add Tooltips (Optional but Recommended)
+Create user-friendly tooltips to help non-technical users understand your tool. **Use simple, clear language - avoid technical jargon:**
+
+**Tooltip Hook** (`frontend/src/components/tooltips/use[ToolName]Tips.ts`):
+```typescript
+import { useTranslation } from 'react-i18next';
+import { TooltipContent } from '../../types/tips';
+
+export const use[ToolName]Tips = (): TooltipContent => {
+  const { t } = useTranslation();
+
+  return {
+    header: {
+      title: t("[toolName].tooltip.header.title", "Tool Overview")
+    },
+    tips: [
+      {
+        title: t("[toolName].tooltip.description.title", "What does this tool do?"),
+        description: t("[toolName].tooltip.description.text", "Simple explanation in everyday language that non-technical users can understand."),
+        bullets: [
+          t("[toolName].tooltip.description.bullet1", "Easy-to-understand benefit 1"),
+          t("[toolName].tooltip.description.bullet2", "Easy-to-understand benefit 2")
+        ]
+      }
+      // Add more tip sections as needed
+    ]
+  };
+};
+```
+
+**Add tooltip to your main component:**
+```typescript
+import { use[ToolName]Tips } from "../components/tooltips/use[ToolName]Tips";
+
+const [ToolName] = (props: BaseToolProps) => {
+  const tips = use[ToolName]Tips();
+  
+  // In your steps array:
+  steps: [
+    {
+      title: t("[toolName].steps.settings", "Settings"),
+      tooltip: tips, // Add this line
+      content: <[ToolName]Settings ... />
+    }
+  ]
+```
+
+## 5. Add Translations
+Update translation files. **Important: Only update `en-GB` files** - other languages are handled separately.
+
+**File to update:** `frontend/public/locales/en-GB/translation.json`
+
+**Required Translation Keys**:
+```json
+{
+  "home": {
+    "[toolName]": {
+      "title": "Tool Name",
+      "desc": "Tool description"
+    }
+  },
+  "[toolName]": {
+    "title": "Tool Name",
+    "submit": "Process",
+    "filenamePrefix": "processed",
+    "files": {
+      "placeholder": "Select files to get started"
+    },
+    "steps": {
+      "settings": "Settings"
+    },
+    "options": {
+      "title": "Tool Options",
+      "someOption": "Option Label",
+      "someOption.desc": "Option description",
+      "note": "General information about the tool."
+    },
+    "results": {
+      "title": "Results"
+    },
+    "error": {
+      "failed": "Operation failed"
+    },
+    "tooltip": {
+      "header": {
+        "title": "Tool Overview"
+      },
+      "description": {
+        "title": "What does this tool do?",
+        "text": "Simple explanation in everyday language",
+        "bullet1": "Easy-to-understand benefit 1",
+        "bullet2": "Easy-to-understand benefit 2"
+      }
+    }
+  }
+}
+```
+
+**Translation Notes:**
+- **Only update `en-GB/translation.json`** - other locale files are managed separately
+- Use descriptive keys that match your component's `t()` calls
+- Include tooltip translations if you created tooltip hooks
+- Add `options.*` keys if your tool has settings with descriptions
+
+**Tooltip Writing Guidelines:**
+- **Use simple, everyday language** - avoid technical terms like "converts interactive elements" 
+- **Focus on benefits** - explain what the user gains, not how it works internally
+- **Use concrete examples** - "text boxes become regular text" vs "form fields are flattened"
+- **Answer user questions** - "What does this do?", "When should I use this?", "What's this option for?"
+- **Keep descriptions concise** - 1-2 sentences maximum per section
+- **Use bullet points** for multiple benefits or features
+
+## 6. Migration from Thymeleaf
+When migrating existing Thymeleaf templates:
+
+1. **Identify Form Parameters**: Look at the original `<form>` inputs to determine parameter structure
+2. **Extract Translation Keys**: Find `#{key.name}` references and add them to JSON translations (For many tools these translations will already exist but some parts will be missing)
+3. **Map API Endpoint**: Note the `th:action` URL for the operation hook
+4. **Preserve Functionality**: Ensure all original form behaviour is replicated which is applicable to V2 react UI
+
+## 7. Testing Your Tool
+- Verify tool appears in UI with correct icon and description
+- Test with various file sizes and types
+- Confirm translations work
+- Check error handling
+- Test undo functionality
+- Verify results display correctly
+
+## Tool Development Patterns
+
+### Three Tool Patterns:
+
+**Pattern 1: Single-File Tools** (Individual processing)
+- Backend processes one file per API call
+- Set `multiFileEndpoint: false`
+- Examples: Compress, Rotate
+
+**Pattern 2: Multi-File Tools** (Batch processing)
+- Backend accepts `MultipartFile[]` arrays in single API call
+- Set `multiFileEndpoint: true`
+- Examples: Split, Merge, Overlay
+
+**Pattern 3: Complex Tools** (Custom processing)
+- Tools with complex routing logic or non-standard processing
+- Provide `customProcessor` for full control
+- Examples: Convert, OCR

CLAUDE.md

@@ -39,7 +39,7 @@ Frontend designed for **stateful document processing**:
 #### FileContext - Central State Management
 **Location**: `src/contexts/FileContext.tsx`
 - **Active files**: Currently loaded PDFs and their variants
-- **Tool navigation**: Current mode (viewer/pageEditor/fileEditor/toolName)  
+- **Tool navigation**: Current mode (viewer/pageEditor/fileEditor/toolName)
 - **Memory management**: PDF document cleanup, blob URL lifecycle, Web Worker management
 - **IndexedDB persistence**: File storage with thumbnail caching
 - **Preview system**: Tools can preview results (e.g., Split → Viewer → back to Split) without context pollution
@@ -89,7 +89,6 @@ return useToolOperation({
   endpoint: '/api/v1/misc/compress-pdf',
   buildFormData: (params, file: File) => { /* single file */ },
   multiFileEndpoint: false,
-  filePrefix: 'compressed_'
 });
 ```
 
@@ -103,7 +102,7 @@ return useToolOperation({
   endpoint: '/api/v1/general/split-pages',
   buildFormData: (params, files: File[]) => { /* all files */ },
   multiFileEndpoint: true,
-  filePrefix: 'split_'
+  filePrefix: 'split_',
 });
 ```
 
@@ -115,13 +114,12 @@ return useToolOperation({
 return useToolOperation({
   operationType: 'convert',
   customProcessor: async (params, files) => { /* custom logic */ },
-  filePrefix: 'converted_'
 });
 ```
 
 **Benefits**:
 - **No Timeouts**: Operations run until completion (supports 100GB+ files)
-- **Consistent**: All tools follow same pattern and interface  
+- **Consistent**: All tools follow same pattern and interface
 - **Maintainable**: Single responsibility hooks, easy to test and modify
 - **i18n Ready**: Built-in internationalization support
 - **Type Safe**: Full TypeScript support with generic interfaces
@@ -185,7 +183,7 @@ return useToolOperation({
 ## Frontend Architecture Status
 
 - **Core Status**: React SPA architecture complete with multi-tool workflow support
-- **State Management**: FileContext handles all file operations and tool navigation  
+- **State Management**: FileContext handles all file operations and tool navigation
 - **File Processing**: Production-ready with memory management for large PDF workflows (up to 100GB+)
 - **Tool Integration**: Modular hook architecture with `useToolOperation` orchestrator
   - Individual hooks: `useToolState`, `useToolApiCalls`, `useToolResources`
@@ -194,6 +192,11 @@ return useToolOperation({
 - **Preview System**: Tool results can be previewed without polluting file context (Split tool example)
 - **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing
 
+## Translation Rules
+
+- **CRITICAL**: Always update translations in `en-GB` only, never `en-US`
+- Translation files are located in `frontend/public/locales/`
+
 ## Important Notes
 
 - **Java Version**: Minimum JDK 17, supports and recommends JDK 21
@@ -208,6 +211,7 @@ return useToolOperation({
 - **Tool Development**: New tools should follow `useToolOperation` hook pattern (see `useCompressOperation.ts`)
 - **Performance Target**: Must handle PDFs up to 100GB+ without browser crashes
 - **Preview System**: Tools can preview results without polluting main file context (see Split tool implementation)
+- **Adding Tools**: See `ADDING_TOOLS.md` for complete guide to creating new PDF tools
 
 ## Communication Style
 - Be direct and to the point

README.md

@@ -97,7 +97,6 @@ All documentation available at [https://docs.stirlingpdf.com/](https://docs.stir
 
 
 
-
 # 📖 Get Started
 
 Visit our comprehensive documentation at [docs.stirlingpdf.com](https://docs.stirlingpdf.com) for:
@@ -116,46 +115,46 @@ Stirling-PDF currently supports 40 languages!
 
 | Language                                     | Progress                               |
 | -------------------------------------------- | -------------------------------------- |
-| Arabic (العربية) (ar_AR)                        | ![61%](https://geps.dev/progress/61)   |
-| Azerbaijani (Azərbaycan Dili) (az_AZ)        | ![62%](https://geps.dev/progress/62)   |
-| Basque (Euskara) (eu_ES)                     | ![36%](https://geps.dev/progress/36)   |
-| Bulgarian (Български) (bg_BG)                | ![68%](https://geps.dev/progress/68)   |
-| Catalan (Català) (ca_CA)                     | ![68%](https://geps.dev/progress/68)   |
-| Croatian (Hrvatski) (hr_HR)                  | ![60%](https://geps.dev/progress/60)   |
-| Czech (Česky) (cs_CZ)                        | ![70%](https://geps.dev/progress/70)   |
-| Danish (Dansk) (da_DK)                       | ![61%](https://geps.dev/progress/61)   |
-| Dutch (Nederlands) (nl_NL)                   | ![60%](https://geps.dev/progress/60)   |
+| Arabic (العربية) (ar_AR)                        | ![95%](https://geps.dev/progress/95)   |
+| Azerbaijani (Azərbaycan Dili) (az_AZ)        | ![35%](https://geps.dev/progress/35)   |
+| Basque (Euskara) (eu_ES)                     | ![20%](https://geps.dev/progress/20)   |
+| Bulgarian (Български) (bg_BG)                | ![39%](https://geps.dev/progress/39)   |
+| Catalan (Català) (ca_CA)                     | ![37%](https://geps.dev/progress/37)   |
+| Croatian (Hrvatski) (hr_HR)                  | ![34%](https://geps.dev/progress/34)   |
+| Czech (Česky) (cs_CZ)                        | ![38%](https://geps.dev/progress/38)   |
+| Danish (Dansk) (da_DK)                       | ![34%](https://geps.dev/progress/34)   |
+| Dutch (Nederlands) (nl_NL)                   | ![34%](https://geps.dev/progress/34)   |
 | English (English) (en_GB)                    | ![100%](https://geps.dev/progress/100) |
 | English (US) (en_US)                         | ![100%](https://geps.dev/progress/100) |
-| French (Français) (fr_FR)                    | ![89%](https://geps.dev/progress/89)   |
-| German (Deutsch) (de_DE)                     | ![98%](https://geps.dev/progress/98)   |
-| Greek (Ελληνικά) (el_GR)                     | ![67%](https://geps.dev/progress/67)   |
-| Hindi (हिंदी) (hi_IN)                          | ![67%](https://geps.dev/progress/67)   |
-| Hungarian (Magyar) (hu_HU)                   | ![99%](https://geps.dev/progress/99)   |
-| Indonesian (Bahasa Indonesia) (id_ID)        | ![62%](https://geps.dev/progress/62)   |
-| Irish (Gaeilge) (ga_IE)                      | ![68%](https://geps.dev/progress/68)   |
-| Italian (Italiano) (it_IT)                   | ![98%](https://geps.dev/progress/98)   |
-| Japanese (日本語) (ja_JP)                    | ![93%](https://geps.dev/progress/93)   |
-| Korean (한국어) (ko_KR)                      | ![67%](https://geps.dev/progress/67)   |
-| Norwegian (Norsk) (no_NB)                    | ![66%](https://geps.dev/progress/66)   |
-| Persian (فارسی) (fa_IR)                      | ![64%](https://geps.dev/progress/64)   |
-| Polish (Polski) (pl_PL)                      | ![72%](https://geps.dev/progress/72)   |
-| Portuguese (Português) (pt_PT)               | ![69%](https://geps.dev/progress/69)   |
-| Portuguese Brazilian (Português) (pt_BR)     | ![76%](https://geps.dev/progress/76)   |
-| Romanian (Română) (ro_RO)                    | ![57%](https://geps.dev/progress/57)   |
-| Russian (Русский) (ru_RU)                    | ![88%](https://geps.dev/progress/88)   |
-| Serbian Latin alphabet (Srpski) (sr_LATN_RS) | ![95%](https://geps.dev/progress/95)   |
-| Simplified Chinese (简体中文) (zh_CN)         | ![93%](https://geps.dev/progress/93)   |
-| Slovakian (Slovensky) (sk_SK)                | ![51%](https://geps.dev/progress/51)   |
-| Slovenian (Slovenščina) (sl_SI)              | ![71%](https://geps.dev/progress/71)   |
-| Spanish (Español) (es_ES)                    | ![74%](https://geps.dev/progress/74)   |
-| Swedish (Svenska) (sv_SE)                    | ![65%](https://geps.dev/progress/65)   |
-| Thai (ไทย) (th_TH)                           | ![59%](https://geps.dev/progress/59)   |
+| French (Français) (fr_FR)                    | ![93%](https://geps.dev/progress/93)   |
+| German (Deutsch) (de_DE)                     | ![95%](https://geps.dev/progress/95)   |
+| Greek (Ελληνικά) (el_GR)                     | ![38%](https://geps.dev/progress/38)   |
+| Hindi (हिंदी) (hi_IN)                          | ![38%](https://geps.dev/progress/38)   |
+| Hungarian (Magyar) (hu_HU)                   | ![42%](https://geps.dev/progress/42)   |
+| Indonesian (Bahasa Indonesia) (id_ID)        | ![34%](https://geps.dev/progress/34)   |
+| Irish (Gaeilge) (ga_IE)                      | ![38%](https://geps.dev/progress/38)   |
+| Italian (Italiano) (it_IT)                   | ![95%](https://geps.dev/progress/95)   |
+| Japanese (日本語) (ja_JP)                    | ![70%](https://geps.dev/progress/70)   |
+| Korean (한국어) (ko_KR)                      | ![38%](https://geps.dev/progress/38)   |
+| Norwegian (Norsk) (no_NB)                    | ![36%](https://geps.dev/progress/36)   |
+| Persian (فارسی) (fa_IR)                      | ![38%](https://geps.dev/progress/38)   |
+| Polish (Polski) (pl_PL)                      | ![40%](https://geps.dev/progress/40)   |
+| Portuguese (Português) (pt_PT)               | ![38%](https://geps.dev/progress/38)   |
+| Portuguese Brazilian (Português) (pt_BR)     | ![95%](https://geps.dev/progress/95)   |
+| Romanian (Română) (ro_RO)                    | ![32%](https://geps.dev/progress/32)   |
+| Russian (Русский) (ru_RU)                    | ![94%](https://geps.dev/progress/94)   |
+| Serbian Latin alphabet (Srpski) (sr_LATN_RS) | ![42%](https://geps.dev/progress/42)   |
+| Simplified Chinese (简体中文) (zh_CN)         | ![96%](https://geps.dev/progress/96)   |
+| Slovakian (Slovensky) (sk_SK)                | ![28%](https://geps.dev/progress/28)   |
+| Slovenian (Slovenščina) (sl_SI)              | ![40%](https://geps.dev/progress/40)   |
+| Spanish (Español) (es_ES)                    | ![95%](https://geps.dev/progress/95)   |
+| Swedish (Svenska) (sv_SE)                    | ![37%](https://geps.dev/progress/37)   |
+| Thai (ไทย) (th_TH)                           | ![34%](https://geps.dev/progress/34)   |
 | Tibetan (བོད་ཡིག་) (bo_CN)                     | ![65%](https://geps.dev/progress/65) |
-| Traditional Chinese (繁體中文) (zh_TW)        | ![97%](https://geps.dev/progress/97)   |
-| Turkish (Türkçe) (tr_TR)                     | ![80%](https://geps.dev/progress/80)   |
-| Ukrainian (Українська) (uk_UA)               | ![71%](https://geps.dev/progress/71)   |
-| Vietnamese (Tiếng Việt) (vi_VN)              | ![57%](https://geps.dev/progress/57)   |
+| Traditional Chinese (繁體中文) (zh_TW)        | ![42%](https://geps.dev/progress/42)   |
+| Turkish (Türkçe) (tr_TR)                     | ![41%](https://geps.dev/progress/41)   |
+| Ukrainian (Українська) (uk_UA)               | ![40%](https://geps.dev/progress/40)   |
+| Vietnamese (Tiếng Việt) (vi_VN)              | ![31%](https://geps.dev/progress/31)   |
 | Malayalam (മലയാളം) (ml_IN)              | ![73%](https://geps.dev/progress/73)   |
 
 ## Stirling PDF Enterprise

app/common/src/main/java/stirling/software/common/annotations/AutoJobPostMapping.java

@@ -6,6 +6,8 @@ import org.springframework.core.annotation.AliasFor;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestMethod;
 
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
+
 /**
  * Shortcut for a POST endpoint that is executed through the Stirling "auto‑job" framework.
  *
@@ -29,6 +31,7 @@ import org.springframework.web.bind.annotation.RequestMethod;
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 @RequestMapping(method = RequestMethod.POST)
+@RequestBody(required = true)
 public @interface AutoJobPostMapping {
 
     /** Alias for {@link RequestMapping#value} – the path mapping of the endpoint. */

app/common/src/main/java/stirling/software/common/annotations/api/AccountSecurityApi.java

@@ -0,0 +1,48 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Account Security API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/account"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/account")
+@Tag(
+        name = "Account Security",
+        description =
+                """
+                Account security and protection services for user safety and organizational compliance.
+
+                This endpoint group provides account security capabilities for organizations requiring
+                enhanced protection against unauthorized access, security threats, and compliance violations.
+
+                Common use cases:
+                • Corporate security policy compliance and SOX, HIPAA, GDPR requirements
+                • Fraud prevention, identity theft protection, and account compromise recovery
+                • Multi-factor authentication implementation and insider threat mitigation
+                • Account recovery and emergency access procedures
+
+                Business applications:
+                • Enterprise risk management, security governance, and customer trust protection
+                • Legal liability reduction and insurance requirement fulfillment
+                • Audit preparation, compliance reporting, and business continuity management
+
+                Operational scenarios:
+                • Security incident response, forensic investigation, and user training
+                • Emergency account lockdown, suspicious activity monitoring, and compliance documentation
+
+                Target users: Security administrators, compliance officers, and organizations
+                prioritizing account security and regulatory compliance.
+                """)
+public @interface AccountSecurityApi {}

app/common/src/main/java/stirling/software/common/annotations/api/AdminApi.java

@@ -0,0 +1,48 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Admin Settings API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/admin/settings"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/admin/settings")
+@Tag(
+        name = "Admin Settings",
+        description =
+                """
+                System administration and configuration management for enterprise deployments.
+
+                This endpoint group provides administrative control for organizations deploying
+                Stirling PDF in production environments with multi-user scenarios.
+
+                Common use cases:
+                • Enterprise deployment configuration and multi-tenant environment management
+                • Security policy enforcement, compliance monitoring, and capacity planning
+                • Operational maintenance, troubleshooting, and enterprise infrastructure integration
+                • Disaster recovery and business continuity preparation
+
+                Business applications:
+                • Corporate IT governance, policy enforcement, and compliance reporting
+                • Cost optimization, SLA monitoring, and vendor management oversight
+                • Risk management and security incident response
+
+                Operational scenarios:
+                • 24/7 production monitoring, scheduled maintenance, and system updates
+                • Emergency response, change management, and performance optimization
+
+                Target users: IT administrators, system engineers, and operations teams
+                responsible for enterprise-grade document processing infrastructure.
+                """)
+public @interface AdminApi {}

app/common/src/main/java/stirling/software/common/annotations/api/AdminServerCertificateApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Admin Server Certificate API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/admin/server-certificate"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/admin/server-certificate")
+@Tag(
+        name = "Admin - Server Certificate",
+        description =
+                """
+                Server certificate management for secure enterprise deployments and encrypted communications.
+
+                This endpoint group provides certificate lifecycle management for organizations
+                requiring secure communications in document processing infrastructure.
+
+                Common use cases:
+                • Corporate security compliance and encrypted communications for healthcare/finance
+                • Customer data protection, internal audits, and multi-environment standardization
+                • Third-party security assessments and disaster recovery security measures
+
+                Business applications:
+                • Enterprise security governance, client trust protection, and secure B2B exchange
+                • Legal requirement fulfillment, liability reduction, and M&A security preparation
+
+                Operational scenarios:
+                • Certificate renewal, emergency replacement, and security incident response
+                • Multi-site deployment coordination and cloud migration preparation
+
+                Target users: Security administrators, compliance officers, and IT infrastructure
+                teams requiring enterprise-grade security for document processing systems.
+                """)
+public @interface AdminServerCertificateApi {}

app/common/src/main/java/stirling/software/common/annotations/api/AnalysisApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Analysis API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/analysis"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/analysis")
+@Tag(
+        name = "Analysis",
+        description =
+                """
+                Document analysis and information extraction services for content intelligence and insights.
+
+                This endpoint group provides analytical capabilities to understand document structure,
+                extract information, and generate insights from PDF content for automated processing.
+
+                Common use cases:
+                • Document inventory management and content audit for compliance verification
+                • Quality assurance workflows and business intelligence analytics
+                • Migration planning, accessibility evaluation, and document forensics
+
+                Business applications:
+                • Legal discovery, financial document review, and healthcare records analysis
+                • Academic research, government processing, and publishing optimization
+
+                Operational scenarios:
+                • Large-scale profiling, migration assessment, and performance optimization
+                • Automated quality control and content strategy development
+
+                Target users: Data analysts, QA teams, administrators, and business intelligence
+                professionals requiring detailed document insights.
+                """)
+public @interface AnalysisApi {}

app/common/src/main/java/stirling/software/common/annotations/api/ConfigApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Configuration API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/config"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/config")
+@Tag(
+        name = "Config",
+        description =
+                """
+                System configuration management for deployment optimization and operational control.
+
+                This endpoint group provides system configuration capabilities for organizations
+                deploying and operating Stirling PDF in various environments.
+
+                Common use cases:
+                • Environment-specific deployment and performance tuning for varying workloads
+                • Resource optimization, cost management, and infrastructure integration
+                • Compliance configuration, disaster recovery, and multi-environment standardization
+
+                Business applications:
+                • Operational cost optimization, SLA compliance, and risk management
+                • Vendor integration, change management, and capacity planning
+
+                Operational scenarios:
+                • System deployment, performance troubleshooting, and emergency changes
+                • Planned maintenance and multi-site deployment coordination
+
+                Target users: System administrators, DevOps engineers, and IT operations teams
+                responsible for deployment configuration and system optimization.
+                """)
+public @interface ConfigApi {}

app/common/src/main/java/stirling/software/common/annotations/api/ConvertApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Convert API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/convert"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/convert")
+@Tag(
+        name = "Convert",
+        description =
+                """
+                Document format transformation services for cross-platform compatibility and workflow integration.
+
+                This endpoint group enables transformation between various formats, supporting
+                diverse business workflows and system integrations for mixed document ecosystems.
+
+                Common use cases:
+                • Legacy system integration, document migration, and cross-platform sharing
+                • Archive standardization, publishing preparation, and content adaptation
+                • Accessibility compliance and mobile-friendly document preparation
+
+                Business applications:
+                • Enterprise content management, digital publishing, and educational platforms
+                • Legal document processing, healthcare interoperability, and government standardization
+
+                Integration scenarios:
+                • API-driven pipelines, automated workflow preparation, and batch conversions
+                • Real-time format adaptation for user requests
+
+                Target users: System integrators, content managers, digital archivists, and
+                organizations requiring flexible document format interoperability.
+                """)
+public @interface ConvertApi {}

app/common/src/main/java/stirling/software/common/annotations/api/DatabaseApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Database Management API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/database"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/database")
+@Tag(
+        name = "Database",
+        description =
+                """
+                Database operations for data protection and business continuity management.
+
+                This endpoint group provides essential database operations for organizations requiring
+                reliable data protection and recovery capabilities.
+
+                Common use cases:
+                • Regular data backup, disaster recovery, and business continuity planning
+                • System migration, compliance management, and development environment support
+                • Operational troubleshooting and scheduled maintenance operations
+
+                Business applications:
+                • Risk management, regulatory compliance, and operational resilience
+                • Data governance, change management, and quality assurance support
+
+                Operational scenarios:
+                • Routine backup, emergency recovery, and system maintenance preparation
+                • Data migration projects and performance monitoring
+
+                Target users: Operations teams, system administrators, and organizations requiring
+                reliable data protection and operational database management.
+                """)
+public @interface DatabaseApi {}

app/common/src/main/java/stirling/software/common/annotations/api/DatabaseManagementApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Database Management API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/admin/database"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/admin/database")
+@Tag(
+        name = "Database Management",
+        description =
+                """
+                Enterprise database administration for production data management and business continuity.
+
+                This endpoint group provides database administration capabilities for organizations
+                operating Stirling PDF in production environments.
+
+                Common use cases:
+                • Business continuity, disaster recovery, and regulatory compliance requirements
+                • Performance optimization, data security, and system migration projects
+                • Audit preparation, compliance reporting, and cost optimization
+
+                Business applications:
+                • Enterprise risk management, regulatory compliance, and SLA monitoring
+                • Data retention policies, security incident response, and vendor oversight
+
+                Operational scenarios:
+                • Scheduled maintenance, emergency recovery, and capacity planning
+                • Performance troubleshooting and multi-environment deployment coordination
+
+                Target users: Database administrators, IT operations teams, and enterprise
+                administrators responsible for production data management and system reliability.
+                """)
+public @interface DatabaseManagementApi {}

app/common/src/main/java/stirling/software/common/annotations/api/FilterApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Filter API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/filter"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/filter")
+@Tag(
+        name = "Filter",
+        description =
+                """
+                Document content filtering and search operations for information discovery and organization.
+
+                This endpoint group enables intelligent content discovery and organization within
+                document collections for content-based processing and information extraction.
+
+                Common use cases:
+                • Legal discovery, research organization, and compliance auditing
+                • Content moderation, academic research, and business intelligence
+                • Quality assurance and content validation workflows
+
+                Business applications:
+                • Contract analysis, financial review, and healthcare records organization
+                • Government processing, educational curation, and IP protection
+
+                Workflow scenarios:
+                • Large-scale processing, automated classification, and information extraction
+                • Document preparation for further processing or analysis
+
+                Target users: Legal professionals, researchers, compliance officers, and
+                organizations requiring intelligent document content discovery and organization.
+                """)
+public @interface FilterApi {}

app/common/src/main/java/stirling/software/common/annotations/api/GeneralApi.java

@@ -0,0 +1,42 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for General PDF processing API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/general"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/general")
+@Tag(
+        name = "General",
+        description =
+                """
+                Core PDF processing operations for fundamental document manipulation workflows.
+
+                This endpoint group provides essential PDF functionality that forms the foundation
+                of most document processing workflows across various industries.
+
+                Common use cases:
+                • Document preparation for archival systems and content organization
+                • File preparation for distribution, accessibility compliance, and batch processing
+                • Document consolidation for reporting and legal compliance workflows
+
+                Typical applications:
+                • Content management, publishing workflows, and educational content distribution
+                • Business process automation and archive management
+
+                Target users: Content managers, document processors, and organizations requiring
+                reliable foundational PDF manipulation capabilities.
+                """)
+public @interface GeneralApi {}

app/common/src/main/java/stirling/software/common/annotations/api/InfoApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Info API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/info"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/info")
+@Tag(
+        name = "Info",
+        description =
+                """
+                System information and operational insights for monitoring and performance management.
+
+                This endpoint group provides system information and operational metrics for organizations
+                operating Stirling PDF in production environments.
+
+                Common use cases:
+                • System health monitoring, performance optimization, and capacity planning
+                • Troubleshooting, compliance monitoring, and SLA reporting
+                • Cost optimization, usage analysis, and security monitoring
+
+                Business applications:
+                • Operational cost management, business continuity monitoring, and vendor management
+                • Compliance reporting, strategic planning, and customer service tracking
+
+                Operational scenarios:
+                • 24/7 monitoring, scheduled maintenance, and emergency response coordination
+                • System upgrade planning and capacity scaling decisions
+
+                Target users: Operations teams, system administrators, and management teams requiring
+                operational insights and system performance visibility.
+                """)
+public @interface InfoApi {}

app/common/src/main/java/stirling/software/common/annotations/api/MiscApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Miscellaneous API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/misc"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/misc")
+@Tag(
+        name = "Misc",
+        description =
+                """
+                Specialized utilities and supplementary tools for enhanced document processing workflows.
+
+                This endpoint group provides utility operations that support core document processing
+                tasks and address specific workflow needs in real-world scenarios.
+
+                Common use cases:
+                • Document optimization for bandwidth-limited environments and storage cost management
+                • Document repair, content extraction, and validation for quality assurance
+                • Accessibility improvement and custom processing for specialized needs
+
+                Business applications:
+                • Web publishing optimization, email attachment management, and archive efficiency
+                • Mobile compatibility, print production, and legacy document recovery
+
+                Operational scenarios:
+                • Batch processing, quality control, and performance optimization
+                • Troubleshooting and recovery of problematic documents
+
+                Target users: System administrators, document specialists, and organizations requiring
+                specialized document processing and optimization tools.
+                """)
+public @interface MiscApi {}

app/common/src/main/java/stirling/software/common/annotations/api/PipelineApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Pipeline API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/pipeline"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/pipeline")
+@Tag(
+        name = "Pipeline",
+        description =
+                """
+                Automated document processing workflows for complex multi-stage business operations.
+
+                This endpoint group enables organizations to create sophisticated document processing
+                workflows that combine multiple operations into streamlined, repeatable processes.
+
+                Common use cases:
+                • Invoice processing, legal document review, and healthcare records standardization
+                • Government processing, educational content preparation, and publishing automation
+                • Contract lifecycle management and approval processes
+
+                Business applications:
+                • Automated compliance reporting, large-scale migration, and quality assurance
+                • Archive preparation, content delivery, and document approval workflows
+
+                Operational scenarios:
+                • Scheduled batch processing and event-driven document processing
+                • Multi-department coordination and business system integration
+
+                Target users: Business process managers, IT automation specialists, and organizations
+                requiring consistent, repeatable document processing workflows.
+                """)
+public @interface PipelineApi {}

app/common/src/main/java/stirling/software/common/annotations/api/ProprietaryUiDataApi.java

@@ -0,0 +1,47 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Proprietary UI Data API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/proprietary/ui-data"), and OpenAPI @Tag. Note:
+ * Controllers using this annotation should also add @EnterpriseEndpoint.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/proprietary/ui-data")
+@Tag(
+        name = "Proprietary UI Data",
+        description =
+                """
+                Enterprise user interface data services for commercial deployments and advanced business features.
+
+                This endpoint group provides enhanced data services for commercial and enterprise features,
+                supporting advanced business workflows and professional-grade functionality.
+
+                Common use cases:
+                • Enterprise-grade dashboards, multi-tenant deployment, and business intelligence
+                • Organizational hierarchy management and commercial feature licensing
+                • Professional support integration and advanced workflow automation
+
+                Business applications:
+                • ERP integration, CRM development, and executive reporting dashboards
+                • Multi-subsidiary management, professional service delivery, and compliance interfaces
+
+                Operational scenarios:
+                • Large-scale deployment management and white-label solution development
+                • Advanced system integration and commercial feature rollout
+
+                Target users: Enterprise administrators, business analysts, and organizations utilizing
+                commercial features and advanced business capabilities.
+                """)
+public @interface ProprietaryUiDataApi {}

app/common/src/main/java/stirling/software/common/annotations/api/SecurityApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Security API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/security"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/security")
+@Tag(
+        name = "Security",
+        description =
+                """
+                Document security and protection services for confidential and sensitive content.
+
+                This endpoint group provides essential security operations for organizations handling
+                sensitive documents and materials requiring controlled access.
+
+                Common use cases:
+                • Legal confidentiality, healthcare privacy (HIPAA), and financial regulatory compliance
+                • Government classified handling, corporate IP protection, and educational privacy (FERPA)
+                • Contract security for business transactions
+
+                Business applications:
+                • Document authentication, confidential sharing, and secure archiving
+                • Content watermarking, access control, and privacy protection through redaction
+
+                Industry scenarios:
+                • Legal discovery, medical records exchange, financial audit documentation
+                • Enterprise policy enforcement and data governance
+
+                Target users: Legal professionals, healthcare administrators, compliance officers,
+                government agencies, and enterprises handling sensitive content.
+                """)
+public @interface SecurityApi {}

app/common/src/main/java/stirling/software/common/annotations/api/SettingsApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Settings API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/settings"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/settings")
+@Tag(
+        name = "Settings",
+        description =
+                """
+                User preferences and application customization for personalized workflow optimization.
+
+                This endpoint group provides preference management capabilities for users and
+                organizations to customize their document processing experience.
+
+                Common use cases:
+                • Workflow optimization, accessibility compliance, and corporate branding
+                • Multi-language support, user personalization, and business system integration
+                • Organizational policy compliance
+
+                Business applications:
+                • Corporate branding, productivity optimization, and accessibility compliance
+                • Change management facilitation and training efficiency improvement
+
+                Operational scenarios:
+                • User onboarding, department-specific customization, and system migration
+                • Multi-tenant customization and project-based configuration adjustments
+
+                Target users: End users, department managers, and organizations focused on optimizing
+                user experience and workflow efficiency through personalization.
+                """)
+public @interface SettingsApi {}

app/common/src/main/java/stirling/software/common/annotations/api/TeamApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for Team Management API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/team"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/team")
+@Tag(
+        name = "Team",
+        description =
+                """
+                Team management and collaboration services for organized document processing workflows.
+
+                This endpoint group enables organizations to structure collaborative document processing
+                activities through team-based organization and resource management.
+
+                Common use cases:
+                • Department-based processing, project collaboration, and cross-functional coordination
+                • Client-specific team isolation, temporary project teams, and training coordination
+                • Compliance team coordination for regulatory processing
+
+                Business applications:
+                • Matrix organization support, client service delivery, and cost center allocation
+                • Scalable collaboration, knowledge management, and team-based quality assurance
+
+                Operational scenarios:
+                • Large-scale processing coordination and temporary team formation
+                • M&A integration, remote collaboration, and knowledge transfer management
+
+                Target users: Team leaders, project managers, and organizations requiring structured
+                collaborative environments for document processing activities.
+                """)
+public @interface TeamApi {}

app/common/src/main/java/stirling/software/common/annotations/api/UiDataApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for UI Data API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/ui-data"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/ui-data")
+@Tag(
+        name = "UI Data",
+        description =
+                """
+                User interface data services for dynamic frontend applications and user experience customization.
+
+                This endpoint group provides data services for frontend applications to render personalized
+                interfaces and deliver optimized experiences based on system configuration.
+
+                Common use cases:
+                • Dynamic UI customization, multi-language support, and feature configuration
+                • Real-time status delivery, corporate branding, and mobile optimization
+                • Progressive web application (PWA) configuration
+
+                Business applications:
+                • Brand customization, user experience optimization, and accessibility compliance
+                • Multi-tenant customization, training support, and performance optimization
+
+                Operational scenarios:
+                • Frontend deployment, UI A/B testing, and system integration
+                • Mobile synchronization and offline capability enhancement
+
+                Target users: Frontend developers, UI/UX designers, and organizations requiring
+                customizable user interfaces and optimized user experiences.
+                """)
+public @interface UiDataApi {}

app/common/src/main/java/stirling/software/common/annotations/api/UserApi.java

@@ -0,0 +1,46 @@
+package stirling.software.common.annotations.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * Combined annotation for User Management API controllers.
+ * Includes @RestController, @RequestMapping("/api/v1/user"), and OpenAPI @Tag.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@RestController
+@RequestMapping("/api/v1/user")
+@Tag(
+        name = "User",
+        description =
+                """
+                User management and authentication services for multi-user and enterprise environments.
+
+                This endpoint group provides user lifecycle management capabilities for organizations
+                deploying Stirling PDF in multi-user scenarios.
+
+                Common use cases:
+                • Employee onboarding/offboarding and corporate access control
+                • Department-based permissions, regulatory compliance, and SSO integration
+                • Multi-tenant deployment and guest user access management
+
+                Business applications:
+                • Enterprise IAM integration, security governance, and cost allocation
+                • Compliance reporting, workflow management, and partner collaboration
+
+                Operational scenarios:
+                • Large-scale provisioning, automated HR integration, and emergency access
+                • User migration and self-service profile maintenance
+
+                Target users: IT administrators, HR departments, and organizations requiring
+                structured user management and enterprise identity integration.
+                """)
+public @interface UserApi {}

app/common/src/main/java/stirling/software/common/aop/AutoJobAspect.java

@@ -87,7 +87,8 @@ public class AutoJobAspect {
                     },
                     timeout,
                     queueable,
-                    resourceWeight);
+                    resourceWeight,
+                    trackProgress);
         } else {
             // Use retry logic
             return executeWithRetries(
@@ -220,7 +221,8 @@ public class AutoJobAspect {
                 },
                 timeout,
                 queueable,
-                resourceWeight);
+                resourceWeight,
+                trackProgress);
     }
 
     /**

app/common/src/main/java/stirling/software/common/configuration/AppConfig.java

@@ -258,12 +258,6 @@ public class AppConfig {
         return false;
     }
 
-    @Bean(name = "GoogleDriveEnabled")
-    @Profile("default")
-    public boolean googleDriveEnabled() {
-        return false;
-    }
-
     @Bean(name = "license")
     @Profile("default")
     public String licenseType() {

app/common/src/main/java/stirling/software/common/context/JobContextHolder.java

@@ -0,0 +1,44 @@
+package stirling.software.common.context;
+
+import lombok.AccessLevel;
+import lombok.NoArgsConstructor;
+
+/**
+ * Holds contextual information for the currently executing job. Backed by a {@link ThreadLocal} so
+ * worker threads can retrieve the job ID and progress tracking preference while processing
+ * asynchronous work dispatched by {@link stirling.software.common.service.JobExecutorService
+ * JobExecutorService}.
+ */
+@NoArgsConstructor(access = AccessLevel.PRIVATE)
+public final class JobContextHolder {
+
+    private static final ThreadLocal<String> JOB_ID = new ThreadLocal<>();
+    private static final ThreadLocal<Boolean> PROGRESS_ENABLED = new ThreadLocal<>();
+
+    /** Store context for the current thread. */
+    public static void setContext(String jobId, boolean progressEnabled) {
+        if (jobId == null) {
+            clear();
+            return;
+        }
+        JOB_ID.set(jobId);
+        PROGRESS_ENABLED.set(progressEnabled);
+    }
+
+    /** Get the job ID bound to the current thread, or {@code null} if none. */
+    public static String getJobId() {
+        return JOB_ID.get();
+    }
+
+    /** Whether progress tracking is enabled for the current job (defaults to {@code false}). */
+    public static boolean isProgressEnabled() {
+        Boolean enabled = PROGRESS_ENABLED.get();
+        return enabled != null && enabled;
+    }
+
+    /** Remove all context associated with the current thread. */
+    public static void clear() {
+        JOB_ID.remove();
+        PROGRESS_ENABLED.remove();
+    }
+}

app/common/src/main/java/stirling/software/common/model/ApplicationProperties.java

@@ -530,7 +530,6 @@ public class ApplicationProperties {
             private boolean ssoAutoLogin;
             private boolean database;
             private CustomMetadata customMetadata = new CustomMetadata();
-            private GoogleDrive googleDrive = new GoogleDrive();
 
             @Data
             public static class CustomMetadata {
@@ -549,26 +548,6 @@ public class ApplicationProperties {
                             : producer;
                 }
             }
-
-            @Data
-            public static class GoogleDrive {
-                private boolean enabled;
-                private String clientId;
-                private String apiKey;
-                private String appId;
-
-                public String getClientId() {
-                    return clientId == null || clientId.trim().isEmpty() ? "" : clientId;
-                }
-
-                public String getApiKey() {
-                    return apiKey == null || apiKey.trim().isEmpty() ? "" : apiKey;
-                }
-
-                public String getAppId() {
-                    return appId == null || appId.trim().isEmpty() ? "" : appId;
-                }
-            }
         }
 
         @Data

app/common/src/main/java/stirling/software/common/model/api/PDFFile.java

@@ -4,6 +4,8 @@ import org.springframework.web.multipart.MultipartFile;
 
 import io.swagger.v3.oas.annotations.media.Schema;
 
+import jakarta.validation.constraints.AssertTrue;
+
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.NoArgsConstructor;
@@ -11,15 +13,20 @@ import lombok.NoArgsConstructor;
 @Data
 @NoArgsConstructor
 @EqualsAndHashCode
+@Schema(description = "PDF file input - either upload a file or provide a server-side file ID")
 public class PDFFile {
-    @Schema(
-            description = "The input PDF file",
-            contentMediaType = "application/pdf",
-            format = "binary")
+    @Schema(description = "The input PDF file", format = "binary")
     private MultipartFile fileInput;
 
     @Schema(
-            description = "File ID for server-side files (can be used instead of fileInput)",
-            example = "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr")
+            description =
+                    "File ID for server-side files (can be used instead of fileInput if job was previously done on file in async mode)")
     private String fileId;
+
+    @AssertTrue(message = "Either fileInput or fileId must be provided")
+    @Schema(hidden = true)
+    private boolean isValid() {
+        return (fileInput != null && (fileId == null || fileId.trim().isEmpty()))
+                || (fileId != null && !fileId.trim().isEmpty() && fileInput == null);
+    }
 }

app/common/src/main/java/stirling/software/common/model/job/JobResult.java

@@ -41,6 +41,18 @@ public class JobResult {
     /** The actual result object, if not a file */
     private Object result;
 
+    /** Whether detailed progress tracking is enabled for this job. */
+    @Builder.Default private boolean trackProgress = true;
+
+    /** Most recent percentage update (0-100) if progress tracking is enabled. */
+    private Integer progressPercent;
+
+    /** Human readable progress message (e.g. current stage) when progress is enabled. */
+    private String progressMessage;
+
+    /** Timestamp of the last progress update. */
+    private LocalDateTime progressUpdatedAt;
+
     /**
      * Notes attached to this job for tracking purposes. Uses CopyOnWriteArrayList for thread safety
      * when notes are added concurrently.
@@ -54,11 +66,28 @@ public class JobResult {
      * @return A new JobResult
      */
     public static JobResult createNew(String jobId) {
-        return JobResult.builder()
-                .jobId(jobId)
-                .complete(false)
-                .createdAt(LocalDateTime.now())
-                .build();
+        return createNew(jobId, true);
+    }
+
+    /**
+     * Create a new JobResult with the given job ID and progress tracking preference.
+     *
+     * @param jobId The job ID
+     * @param trackProgress Whether detailed progress should be tracked
+     * @return A new JobResult
+     */
+    public static JobResult createNew(String jobId, boolean trackProgress) {
+        JobResult result =
+                JobResult.builder()
+                        .jobId(jobId)
+                        .complete(false)
+                        .createdAt(LocalDateTime.now())
+                        .trackProgress(trackProgress)
+                        .build();
+        if (trackProgress) {
+            result.updateProgressInternal(0, "Pending");
+        }
+        return result;
     }
 
     /**
@@ -70,6 +99,9 @@ public class JobResult {
         this.complete = true;
         this.result = result;
         this.completedAt = LocalDateTime.now();
+        if (trackProgress) {
+            updateProgressInternal(100, "Completed");
+        }
     }
 
     /**
@@ -81,6 +113,9 @@ public class JobResult {
         this.complete = true;
         this.error = error;
         this.completedAt = LocalDateTime.now();
+        if (trackProgress) {
+            updateProgressInternal(100, error != null ? error : "Failed");
+        }
     }
 
     /**
@@ -92,6 +127,9 @@ public class JobResult {
         this.complete = true;
         this.resultFiles = new ArrayList<>(resultFiles);
         this.completedAt = LocalDateTime.now();
+        if (trackProgress) {
+            updateProgressInternal(100, "Completed");
+        }
     }
 
     /**
@@ -161,4 +199,26 @@ public class JobResult {
     public List<String> getNotes() {
         return Collections.unmodifiableList(notes);
     }
+
+    /**
+     * Update the progress information if tracking is enabled.
+     *
+     * @param percent The percent complete (0-100)
+     * @param message Optional descriptive message
+     */
+    public void updateProgress(int percent, String message) {
+        if (!trackProgress) {
+            return;
+        }
+        updateProgressInternal(percent, message);
+    }
+
+    private void updateProgressInternal(int percent, String message) {
+        int clamped = Math.min(100, Math.max(0, percent));
+        this.progressPercent = clamped;
+        if (message != null && !message.isBlank()) {
+            this.progressMessage = message;
+        }
+        this.progressUpdatedAt = LocalDateTime.now();
+    }
 }

app/common/src/main/java/stirling/software/common/service/JobExecutorService.java

@@ -20,6 +20,7 @@ import jakarta.servlet.http.HttpServletRequest;
 
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.common.context.JobContextHolder;
 import stirling.software.common.model.job.JobResponse;
 import stirling.software.common.util.ExecutorFactory;
 
@@ -65,7 +66,7 @@ public class JobExecutorService {
      * @return The response
      */
     public ResponseEntity<?> runJobGeneric(boolean async, Supplier<Object> work) {
-        return runJobGeneric(async, work, -1);
+        return runJobGeneric(async, work, -1, false, 50, true);
     }
 
     /**
@@ -78,7 +79,7 @@ public class JobExecutorService {
      */
     public ResponseEntity<?> runJobGeneric(
             boolean async, Supplier<Object> work, long customTimeoutMs) {
-        return runJobGeneric(async, work, customTimeoutMs, false, 50);
+        return runJobGeneric(async, work, customTimeoutMs, false, 50, true);
     }
 
     /**
@@ -96,7 +97,8 @@ public class JobExecutorService {
             Supplier<Object> work,
             long customTimeoutMs,
             boolean queueable,
-            int resourceWeight) {
+            int resourceWeight,
+            boolean trackProgress) {
         String jobId = UUID.randomUUID().toString();
 
         // Store the job ID in the request for potential use by other components
@@ -138,6 +140,8 @@ public class JobExecutorService {
                         && // Only async jobs can be queued
                         resourceMonitor.shouldQueueJob(resourceWeight);
 
+        boolean enableProgress = async && trackProgress;
+
         if (shouldQueue) {
             // Queue the job instead of executing immediately
             log.debug(
@@ -145,13 +149,18 @@ public class JobExecutorService {
                     jobId,
                     resourceWeight);
 
-            taskManager.createTask(jobId);
+            taskManager.createTask(jobId, trackProgress);
+
+            Supplier<Object> contextualWork = withJobContext(jobId, enableProgress, work);
 
             // Create a specialized wrapper that updates the TaskManager
             Supplier<Object> wrappedWork =
                     () -> {
                         try {
-                            Object result = work.get();
+                            if (enableProgress) {
+                                taskManager.updateProgress(jobId, 5, null);
+                            }
+                            Object result = contextualWork.get();
                             processJobResult(jobId, result);
                             return result;
                         } catch (Exception e) {
@@ -169,24 +178,49 @@ public class JobExecutorService {
             // Return immediately with job ID
             return ResponseEntity.ok().body(new JobResponse<>(true, jobId, null));
         } else if (async) {
-            taskManager.createTask(jobId);
+            taskManager.createTask(jobId, trackProgress);
             executor.execute(
-                    () -> {
-                        try {
-                            log.debug(
-                                    "Running async job {} with timeout {} ms", jobId, timeoutToUse);
+                    () ->
+                            runWithJobContext(
+                                    jobId,
+                                    enableProgress,
+                                    () -> {
+                                        try {
+                                            log.debug(
+                                                    "Running async job {} with timeout {} ms",
+                                                    jobId,
+                                                    timeoutToUse);
 
-                            // Execute with timeout
-                            Object result = executeWithTimeout(() -> work.get(), timeoutToUse);
-                            processJobResult(jobId, result);
-                        } catch (TimeoutException te) {
-                            log.error("Job {} timed out after {} ms", jobId, timeoutToUse);
-                            taskManager.setError(jobId, "Job timed out");
-                        } catch (Exception e) {
-                            log.error("Error executing job {}: {}", jobId, e.getMessage(), e);
-                            taskManager.setError(jobId, e.getMessage());
-                        }
-                    });
+                                            Supplier<Object> contextualWork =
+                                                    withJobContext(jobId, enableProgress, work);
+
+                                            if (enableProgress) {
+                                                taskManager.updateProgress(jobId, 5, null);
+                                            }
+
+                                            // Execute with timeout
+                                            Object result =
+                                                    executeWithTimeout(
+                                                            contextualWork,
+                                                            timeoutToUse,
+                                                            jobId,
+                                                            enableProgress);
+                                            processJobResult(jobId, result);
+                                        } catch (TimeoutException te) {
+                                            log.error(
+                                                    "Job {} timed out after {} ms",
+                                                    jobId,
+                                                    timeoutToUse);
+                                            taskManager.setError(jobId, "Job timed out");
+                                        } catch (Exception e) {
+                                            log.error(
+                                                    "Error executing job {}: {}",
+                                                    jobId,
+                                                    e.getMessage(),
+                                                    e);
+                                            taskManager.setError(jobId, e.getMessage());
+                                        }
+                                    }));
 
             return ResponseEntity.ok().body(new JobResponse<>(true, jobId, null));
         } else {
@@ -194,7 +228,9 @@ public class JobExecutorService {
                 log.debug("Running sync job with timeout {} ms", timeoutToUse);
 
                 // Execute with timeout
-                Object result = executeWithTimeout(() -> work.get(), timeoutToUse);
+                Supplier<Object> contextualWork = withJobContext(jobId, enableProgress, work);
+                Object result =
+                        executeWithTimeout(contextualWork, timeoutToUse, jobId, enableProgress);
 
                 // If the result is already a ResponseEntity, return it directly
                 if (result instanceof ResponseEntity) {
@@ -452,12 +488,14 @@ public class JobExecutorService {
      * @throws TimeoutException If the execution times out
      * @throws Exception If the supplier throws an exception
      */
-    private <T> T executeWithTimeout(Supplier<T> supplier, long timeoutMs)
+    private <T> T executeWithTimeout(
+            Supplier<T> supplier, long timeoutMs, String jobId, boolean progressEnabled)
             throws TimeoutException, Exception {
         // Use the same executor as other async jobs for consistency
         // This ensures all operations run on the same thread pool
         java.util.concurrent.CompletableFuture<T> future =
-                java.util.concurrent.CompletableFuture.supplyAsync(supplier, executor);
+                java.util.concurrent.CompletableFuture.supplyAsync(
+                        withJobContext(jobId, progressEnabled, supplier), executor);
 
         try {
             return future.get(timeoutMs, TimeUnit.MILLISECONDS);
@@ -473,4 +511,62 @@ public class JobExecutorService {
             throw new Exception("Execution was interrupted", e);
         }
     }
+
+    /** Backwards compatible helper used by tests via reflection. */
+    @SuppressWarnings("unused")
+    private <T> T executeWithTimeout(Supplier<T> supplier, long timeoutMs)
+            throws TimeoutException, Exception {
+        return executeWithTimeout(
+                supplier,
+                timeoutMs,
+                JobContextHolder.getJobId(),
+                JobContextHolder.isProgressEnabled());
+    }
+
+    private <T> Supplier<T> withJobContext(
+            String jobId, boolean progressEnabled, Supplier<T> delegate) {
+        if (jobId == null) {
+            return delegate;
+        }
+        return () -> {
+            String previousJobId = JobContextHolder.getJobId();
+            boolean previousProgress = JobContextHolder.isProgressEnabled();
+
+            JobContextHolder.setContext(jobId, progressEnabled);
+            try {
+                return delegate.get();
+            } finally {
+                if (previousJobId == null) {
+                    JobContextHolder.clear();
+                } else {
+                    JobContextHolder.setContext(previousJobId, previousProgress);
+                }
+            }
+        };
+    }
+
+    private void runWithJobContext(String jobId, boolean progressEnabled, Runnable runnable) {
+        if (jobId == null) {
+            runnable.run();
+            return;
+        }
+        Runnable contextualRunnable =
+                () -> {
+                    String previousJobId = JobContextHolder.getJobId();
+                    boolean previousProgress = JobContextHolder.isProgressEnabled();
+
+                    JobContextHolder.setContext(jobId, progressEnabled);
+                    try {
+                        runnable.run();
+                    } finally {
+                        if (previousJobId == null) {
+                            JobContextHolder.clear();
+                        } else {
+                            JobContextHolder.setContext(previousJobId, previousProgress);
+                        }
+                    }
+                };
+
+        contextualRunnable.run();
+    }
 }

app/common/src/main/java/stirling/software/common/service/JobProgressService.java

@@ -0,0 +1,56 @@
+package stirling.software.common.service;
+
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.context.JobContextHolder;
+
+/**
+ * Convenience service that exposes a simple API for updating progress information from within job
+ * handlers executed through {@link JobExecutorService}. The service automatically ties progress
+ * updates to the current job (if any) and no-ops when progress tracking is disabled.
+ */
+@Service
+@RequiredArgsConstructor
+public class JobProgressService {
+
+    private final TaskManager taskManager;
+
+    /** Update the progress percentage for the current job. */
+    public boolean updateProgress(int percent, String message) {
+        String jobId = JobContextHolder.getJobId();
+        if (jobId == null || !JobContextHolder.isProgressEnabled()) {
+            return false;
+        }
+        return taskManager.updateProgress(jobId, percent, message);
+    }
+
+    /**
+     * Create a simple tracker that can be used to report progress across a fixed number of steps.
+     * When progress tracking is disabled for the current job, the returned tracker will be a
+     * lightweight no-op implementation.
+     */
+    public JobProgressTracker tracker(int totalSteps) {
+        return tracker(totalSteps, null);
+    }
+
+    /**
+     * Create a tracker and optionally publish an initial message. Useful for multi-stage pipelines
+     * where the initial state should be visible to clients.
+     */
+    public JobProgressTracker tracker(int totalSteps, String initialMessage) {
+        String jobId = JobContextHolder.getJobId();
+        boolean enabled = JobContextHolder.isProgressEnabled();
+
+        if (jobId == null || !enabled || totalSteps <= 0) {
+            return JobProgressTracker.disabled();
+        }
+
+        if (initialMessage != null && !initialMessage.isBlank()) {
+            taskManager.updateProgress(jobId, 0, initialMessage);
+        }
+
+        return new JobProgressTracker(taskManager, jobId, totalSteps, true);
+    }
+}

app/common/src/main/java/stirling/software/common/service/JobProgressTracker.java

@@ -0,0 +1,81 @@
+package stirling.software.common.service;
+
+import lombok.AccessLevel;
+import lombok.RequiredArgsConstructor;
+
+/**
+ * Utility that helps controllers report progress in a structured way by distributing the 0-100%
+ * range across a finite number of logical steps.
+ */
+@RequiredArgsConstructor(access = AccessLevel.PACKAGE)
+public class JobProgressTracker {
+
+    private final TaskManager taskManager;
+    private final String jobId;
+    private final int totalSteps;
+    private final boolean enabled;
+
+    private int completedSteps;
+
+    static JobProgressTracker disabled() {
+        return new JobProgressTracker(null, null, 1, false);
+    }
+
+    /** Whether the tracker will emit updates. */
+    public boolean isEnabled() {
+        return enabled;
+    }
+
+    /** Advance the tracker by one step. */
+    public void advance() {
+        advanceBy(1, null);
+    }
+
+    /** Advance the tracker by {@code steps} steps. */
+    public void advanceBy(int steps, String message) {
+        if (!enabled) {
+            return;
+        }
+        int safeSteps = Math.max(0, steps);
+        completedSteps = Math.min(totalSteps, completedSteps + safeSteps);
+        publish(message);
+    }
+
+    /** Advance the tracker by {@code steps} steps without a message. */
+    public void advanceBy(int steps) {
+        advanceBy(steps, null);
+    }
+
+    /** Explicitly set the completed steps count. */
+    public void setStepsCompleted(int stepsCompleted, String message) {
+        if (!enabled) {
+            return;
+        }
+        completedSteps = Math.max(0, Math.min(totalSteps, stepsCompleted));
+        publish(message);
+    }
+
+    /** Explicitly set completed steps without a message. */
+    public void setStepsCompleted(int stepsCompleted) {
+        setStepsCompleted(stepsCompleted, null);
+    }
+
+    /** Mark the tracker as complete and emit a final message. */
+    public void complete(String message) {
+        if (!enabled) {
+            return;
+        }
+        completedSteps = totalSteps;
+        taskManager.updateProgress(jobId, 100, message);
+    }
+
+    /** Mark the tracker as complete without a message. */
+    public void complete() {
+        complete(null);
+    }
+
+    private void publish(String message) {
+        int percent = (int) Math.floor(((double) completedSteps / (double) totalSteps) * 100);
+        taskManager.updateProgress(jobId, percent, message);
+    }
+}

app/common/src/main/java/stirling/software/common/service/ServerCertificateServiceInterface.java

@@ -0,0 +1,42 @@
+package stirling.software.common.service;
+
+import java.io.InputStream;
+import java.security.KeyStore;
+import java.security.cert.X509Certificate;
+import java.util.Date;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+public interface ServerCertificateServiceInterface {
+
+    boolean isEnabled();
+
+    boolean hasServerCertificate();
+
+    void initializeServerCertificate();
+
+    KeyStore getServerKeyStore() throws Exception;
+
+    String getServerCertificatePassword();
+
+    X509Certificate getServerCertificate() throws Exception;
+
+    byte[] getServerCertificatePublicKey() throws Exception;
+
+    void uploadServerCertificate(InputStream p12Stream, String password) throws Exception;
+
+    void deleteServerCertificate() throws Exception;
+
+    ServerCertificateInfo getServerCertificateInfo() throws Exception;
+
+    @Getter
+    @AllArgsConstructor
+    class ServerCertificateInfo {
+        private final boolean exists;
+        private final String subject;
+        private final String issuer;
+        private final Date validFrom;
+        private final Date validTo;
+    }
+}

app/common/src/main/java/stirling/software/common/service/TaskManager.java

@@ -65,7 +65,17 @@ public class TaskManager {
      * @param jobId The job ID
      */
     public void createTask(String jobId) {
-        jobResults.put(jobId, JobResult.createNew(jobId));
+        createTask(jobId, true);
+    }
+
+    /**
+     * Create a new task with the given job ID and progress tracking preference
+     *
+     * @param jobId The job ID
+     * @param trackProgress Whether detailed progress updates should be stored
+     */
+    public void createTask(String jobId, boolean trackProgress) {
+        jobResults.put(jobId, JobResult.createNew(jobId, trackProgress));
         log.debug("Created task with job ID: {}", jobId);
     }
 
@@ -165,6 +175,11 @@ public class TaskManager {
                 && jobResult.getError() == null) {
             // If no result or error has been set, mark it as complete with an empty result
             jobResult.completeWithResult("Task completed successfully");
+        } else {
+            // Ensure progress is set to 100% with "Completed" message
+            if (jobResult.isTrackProgress()) {
+                jobResult.updateProgress(100, "Completed");
+            }
         }
         log.debug("Marked job ID: {} as complete", jobId);
     }
@@ -209,6 +224,33 @@ public class TaskManager {
         return false;
     }
 
+    /**
+     * Update the progress information for a task.
+     *
+     * @param jobId The job ID
+     * @param percent Percentage complete (0-100)
+     * @param message Descriptive message for the current stage
+     * @return true if the progress update was accepted
+     */
+    public boolean updateProgress(String jobId, int percent, String message) {
+        JobResult jobResult = jobResults.get(jobId);
+        if (jobResult == null) {
+            log.debug("Ignoring progress update for unknown job ID: {}", jobId);
+            return false;
+        }
+
+        if (!jobResult.isTrackProgress()) {
+            log.trace("Progress tracking disabled for job ID: {}", jobId);
+            return false;
+        }
+
+        jobResult.updateProgress(percent, message);
+        log.debug(
+                "Updated progress for job {} to {}% with message: {}",
+                jobId, jobResult.getProgressPercent(), message);
+        return true;
+    }
+
     /**
      * Get statistics about all jobs in the system
      *

app/common/src/test/java/stirling/software/common/annotations/AutoJobPostMappingIntegrationTest.java

@@ -1,6 +1,7 @@
 package stirling.software.common.annotations;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
@@ -72,6 +73,8 @@ class AutoJobPostMappingIntegrationTest {
 
     @Captor private ArgumentCaptor<Integer> resourceWeightCaptor;
 
+    @Captor private ArgumentCaptor<Boolean> trackProgressCaptor;
+
     @Test
     void shouldExecuteWithCustomParameters() throws Throwable {
         // Given
@@ -91,7 +94,12 @@ class AutoJobPostMappingIntegrationTest {
         when(fileStorage.retrieveFile("test-file-id")).thenReturn(mockFile);
 
         when(jobExecutorService.runJobGeneric(
-                        anyBoolean(), any(Supplier.class), anyLong(), anyBoolean(), anyInt()))
+                        anyBoolean(),
+                        any(Supplier.class),
+                        anyLong(),
+                        anyBoolean(),
+                        anyInt(),
+                        anyBoolean()))
                 .thenReturn(ResponseEntity.ok("success"));
 
         // When
@@ -106,12 +114,14 @@ class AutoJobPostMappingIntegrationTest {
                         workCaptor.capture(),
                         timeoutCaptor.capture(),
                         queueableCaptor.capture(),
-                        resourceWeightCaptor.capture());
+                        resourceWeightCaptor.capture(),
+                        trackProgressCaptor.capture());
 
         assertTrue(asyncCaptor.getValue(), "Async should be true");
         assertEquals(60000L, timeoutCaptor.getValue(), "Timeout should be 60000ms");
         assertTrue(queueableCaptor.getValue(), "Queueable should be true");
         assertEquals(75, resourceWeightCaptor.getValue(), "Resource weight should be 75");
+        assertTrue(trackProgressCaptor.getValue(), "Track progress should propagate");
 
         // Test that file was resolved
         assertNotNull(pdfFile.getFileInput(), "File input should be set");
@@ -135,7 +145,12 @@ class AutoJobPostMappingIntegrationTest {
 
         // Mock jobExecutorService to execute the work immediately
         when(jobExecutorService.runJobGeneric(
-                        anyBoolean(), any(Supplier.class), anyLong(), anyBoolean(), anyInt()))
+                        anyBoolean(),
+                        any(Supplier.class),
+                        anyLong(),
+                        anyBoolean(),
+                        anyInt(),
+                        anyBoolean()))
                 .thenAnswer(
                         invocation -> {
                             Supplier<Object> work = invocation.getArgument(1);
@@ -150,6 +165,16 @@ class AutoJobPostMappingIntegrationTest {
 
         // Verify that proceed was called twice (initial attempt + 1 retry)
         verify(joinPoint, times(2)).proceed(any());
+
+        verify(jobExecutorService)
+                .runJobGeneric(
+                        asyncCaptor.capture(),
+                        workCaptor.capture(),
+                        timeoutCaptor.capture(),
+                        queueableCaptor.capture(),
+                        resourceWeightCaptor.capture(),
+                        trackProgressCaptor.capture());
+        assertFalse(trackProgressCaptor.getValue(), "Track progress should be false when disabled");
     }
 
     @Test
@@ -168,7 +193,12 @@ class AutoJobPostMappingIntegrationTest {
 
         // Mock job executor to return a successful response
         when(jobExecutorService.runJobGeneric(
-                        anyBoolean(), any(Supplier.class), anyLong(), anyBoolean(), anyInt()))
+                        anyBoolean(),
+                        any(Supplier.class),
+                        anyLong(),
+                        anyBoolean(),
+                        anyInt(),
+                        anyBoolean()))
                 .thenReturn(ResponseEntity.ok("success"));
 
         // When

app/common/src/test/java/stirling/software/common/model/ApplicationPropertiesLogicTest.java

@@ -109,22 +109,6 @@ class ApplicationPropertiesLogicTest {
         assertTrue(ex.getMessage().toLowerCase().contains("not supported"));
     }
 
-    @Test
-    void premium_google_drive_getters_return_empty_string_on_null_or_blank() {
-        Premium.ProFeatures.GoogleDrive gd = new Premium.ProFeatures.GoogleDrive();
-
-        assertEquals("", gd.getClientId());
-        assertEquals("", gd.getApiKey());
-        assertEquals("", gd.getAppId());
-
-        gd.setClientId(" id ");
-        gd.setApiKey(" key ");
-        gd.setAppId(" app ");
-        assertEquals(" id ", gd.getClientId());
-        assertEquals(" key ", gd.getApiKey());
-        assertEquals(" app ", gd.getAppId());
-    }
-
     @Test
     void ui_getters_return_null_for_blank() {
         ApplicationProperties.Ui ui = new ApplicationProperties.Ui();

app/common/src/test/java/stirling/software/common/service/JobExecutorServiceTest.java

@@ -94,7 +94,7 @@ class JobExecutorServiceTest {
         assertNotNull(jobResponse.getJobId());
 
         // Verify task manager was called
-        verify(taskManager).createTask(jobIdCaptor.capture());
+        verify(taskManager).createTask(jobIdCaptor.capture(), eq(true));
     }
 
     @Test
@@ -129,7 +129,8 @@ class JobExecutorServiceTest {
         when(jobQueue.queueJob(anyString(), eq(80), any(), anyLong())).thenReturn(future);
 
         // When
-        ResponseEntity<?> response = jobExecutorService.runJobGeneric(true, work, 5000, true, 80);
+        ResponseEntity<?> response =
+                jobExecutorService.runJobGeneric(true, work, 5000, true, 80, true);
 
         // Then
         assertEquals(HttpStatus.OK, response.getStatusCode());
@@ -137,7 +138,7 @@ class JobExecutorServiceTest {
 
         // Verify job was queued
         verify(jobQueue).queueJob(anyString(), eq(80), any(), eq(5000L));
-        verify(taskManager).createTask(anyString());
+        verify(taskManager).createTask(anyString(), eq(true));
     }
 
     @Test

app/common/src/test/java/stirling/software/common/service/JobProgressServiceTest.java

@@ -0,0 +1,83 @@
+package stirling.software.common.service;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import stirling.software.common.context.JobContextHolder;
+
+class JobProgressServiceTest {
+
+    @Mock private TaskManager taskManager;
+
+    private JobProgressService jobProgressService;
+
+    private AutoCloseable mocks;
+
+    @BeforeEach
+    void setUp() {
+        mocks = MockitoAnnotations.openMocks(this);
+        jobProgressService = new JobProgressService(taskManager);
+        JobContextHolder.clear();
+    }
+
+    @AfterEach
+    void tearDown() throws Exception {
+        JobContextHolder.clear();
+        mocks.close();
+    }
+
+    @Test
+    void updateProgressReturnsFalseWhenNoContext() {
+        boolean updated = jobProgressService.updateProgress(10, "Stage");
+        assertFalse(updated);
+        verify(taskManager, never()).updateProgress(anyString(), anyInt(), anyString());
+    }
+
+    @Test
+    void updateProgressDelegatesToTaskManager() {
+        JobContextHolder.setContext("job-123", true);
+        when(taskManager.updateProgress("job-123", 20, "Processing")).thenReturn(true);
+
+        boolean updated = jobProgressService.updateProgress(20, "Processing");
+
+        assertTrue(updated);
+        verify(taskManager).updateProgress("job-123", 20, "Processing");
+    }
+
+    @Test
+    void trackerNoOpsWhenDisabled() {
+        JobContextHolder.setContext("job-123", false);
+        JobProgressTracker tracker = jobProgressService.tracker(5, "Start");
+
+        assertFalse(tracker.isEnabled());
+        tracker.advanceBy(1, "Step");
+        tracker.complete("Done");
+
+        verify(taskManager, never()).updateProgress(anyString(), anyInt(), anyString());
+    }
+
+    @Test
+    void trackerPublishesProgress() {
+        JobContextHolder.setContext("job-123", true);
+        JobProgressTracker tracker = jobProgressService.tracker(4, "Starting");
+
+        assertTrue(tracker.isEnabled());
+        verify(taskManager).updateProgress("job-123", 0, "Starting");
+
+        tracker.advanceBy(1, "25 percent");
+        tracker.advanceBy(1, "50 percent");
+        tracker.setStepsCompleted(3, "75 percent");
+        tracker.complete("Done");
+
+        verify(taskManager).updateProgress("job-123", 25, "25 percent");
+        verify(taskManager).updateProgress("job-123", 50, "50 percent");
+        verify(taskManager).updateProgress("job-123", 75, "75 percent");
+        verify(taskManager).updateProgress("job-123", 100, "Done");
+    }
+}

app/common/src/test/java/stirling/software/common/service/TaskManagerTest.java

@@ -50,6 +50,9 @@ class TaskManagerTest {
         assertEquals(jobId, result.getJobId());
         assertFalse(result.isComplete());
         assertNotNull(result.getCreatedAt());
+        assertTrue(result.isTrackProgress());
+        assertEquals(0, result.getProgressPercent());
+        assertEquals("Pending", result.getProgressMessage());
     }
 
     @Test
@@ -68,6 +71,8 @@ class TaskManagerTest {
         assertTrue(result.isComplete());
         assertEquals(resultObject, result.getResult());
         assertNotNull(result.getCompletedAt());
+        assertEquals(100, result.getProgressPercent());
+        assertEquals("Completed", result.getProgressMessage());
     }
 
     @Test
@@ -120,6 +125,8 @@ class TaskManagerTest {
         assertTrue(result.isComplete());
         assertEquals(errorMessage, result.getError());
         assertNotNull(result.getCompletedAt());
+        assertEquals(100, result.getProgressPercent());
+        assertEquals(errorMessage, result.getProgressMessage());
     }
 
     @Test
@@ -138,6 +145,7 @@ class TaskManagerTest {
         assertNotNull(result);
         assertTrue(result.isComplete());
         assertEquals(resultObject, result.getResult());
+        assertEquals(100, result.getProgressPercent());
     }
 
     @Test
@@ -154,6 +162,8 @@ class TaskManagerTest {
         assertNotNull(result);
         assertTrue(result.isComplete());
         assertEquals("Task completed successfully", result.getResult());
+        assertEquals(100, result.getProgressPercent());
+        assertEquals("Completed", result.getProgressMessage());
     }
 
     @Test
@@ -305,4 +315,45 @@ class TaskManagerTest {
         // Assert
         assertFalse(result);
     }
+
+    @Test
+    void testCreateTaskWithoutProgressTracking() {
+        String jobId = UUID.randomUUID().toString();
+        taskManager.createTask(jobId, false);
+
+        JobResult result = taskManager.getJobResult(jobId);
+        assertNotNull(result);
+        assertFalse(result.isTrackProgress());
+        assertNull(result.getProgressPercent());
+        assertNull(result.getProgressMessage());
+    }
+
+    @Test
+    void testUpdateProgress() {
+        String jobId = UUID.randomUUID().toString();
+        taskManager.createTask(jobId);
+
+        boolean updated = taskManager.updateProgress(jobId, 50, "Halfway there");
+
+        assertTrue(updated);
+        JobResult result = taskManager.getJobResult(jobId);
+        assertEquals(50, result.getProgressPercent());
+        assertEquals("Halfway there", result.getProgressMessage());
+        assertNotNull(result.getProgressUpdatedAt());
+    }
+
+    @Test
+    void testUpdateProgressReturnsFalseWhenJobMissing() {
+        boolean updated = taskManager.updateProgress("missing", 10, "Stage");
+        assertFalse(updated);
+    }
+
+    @Test
+    void testUpdateProgressIgnoredWhenTrackingDisabled() {
+        String jobId = UUID.randomUUID().toString();
+        taskManager.createTask(jobId, false);
+
+        boolean updated = taskManager.updateProgress(jobId, 75, "Stage");
+        assertFalse(updated);
+    }
 }

app/core/src/main/java/stirling/software/SPDF/config/EndpointConfiguration.java

@@ -237,6 +237,7 @@ public class EndpointConfiguration {
         addEndpointToGroup("PageOps", "pdf-organizer");
         addEndpointToGroup("PageOps", "rotate-pdf");
         addEndpointToGroup("PageOps", "multi-page-layout");
+        addEndpointToGroup("PageOps", "booklet-imposition");
         addEndpointToGroup("PageOps", "scale-pages");
         addEndpointToGroup("PageOps", "crop");
         addEndpointToGroup("PageOps", "extract-page");
@@ -366,6 +367,7 @@ public class EndpointConfiguration {
         addEndpointToGroup("Java", "cert-sign");
         addEndpointToGroup("Java", "remove-cert-sign");
         addEndpointToGroup("Java", "multi-page-layout");
+        addEndpointToGroup("Java", "booklet-imposition");
         addEndpointToGroup("Java", "scale-pages");
         addEndpointToGroup("Java", "add-page-numbers");
         addEndpointToGroup("Java", "auto-rename");

app/core/src/main/java/stirling/software/SPDF/config/GlobalErrorResponseCustomizer.java

@@ -0,0 +1,188 @@
+package stirling.software.SPDF.config;
+
+import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
+import org.springframework.stereotype.Component;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.Operation;
+import io.swagger.v3.oas.models.PathItem;
+import io.swagger.v3.oas.models.media.Content;
+import io.swagger.v3.oas.models.media.MediaType;
+import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.responses.ApiResponse;
+
+/**
+ * Global OpenAPI customizer that adds standard error responses (400, 413, 422, 500) to all API
+ * operations under /api/v1/** paths.
+ */
+@Component
+public class GlobalErrorResponseCustomizer implements GlobalOpenApiCustomizer {
+
+    @Override
+    public void customise(OpenAPI openApi) {
+        if (openApi.getPaths() == null) {
+            return;
+        }
+
+        openApi.getPaths()
+                .forEach(
+                        (path, pathItem) -> {
+                            if (path.startsWith("/api/v1/")) {
+                                addErrorResponsesToPathItem(pathItem);
+                            }
+                        });
+    }
+
+    private void addErrorResponsesToPathItem(PathItem pathItem) {
+        if (pathItem.getPost() != null) {
+            addStandardErrorResponses(pathItem.getPost());
+        }
+        if (pathItem.getPut() != null) {
+            addStandardErrorResponses(pathItem.getPut());
+        }
+        if (pathItem.getPatch() != null) {
+            addStandardErrorResponses(pathItem.getPatch());
+        }
+        if (pathItem.getDelete() != null) {
+            addStandardErrorResponses(pathItem.getDelete());
+        }
+        if (pathItem.getGet() != null) {
+            addStandardErrorResponses(pathItem.getGet());
+        }
+    }
+
+    private void addStandardErrorResponses(Operation operation) {
+        if (operation.getResponses() == null) {
+            return;
+        }
+
+        // Only add error responses if they don't already exist
+        if (!operation.getResponses().containsKey("400")) {
+            operation.getResponses().addApiResponse("400", create400Response());
+        }
+        if (!operation.getResponses().containsKey("413")) {
+            operation.getResponses().addApiResponse("413", create413Response());
+        }
+        if (!operation.getResponses().containsKey("422")) {
+            operation.getResponses().addApiResponse("422", create422Response());
+        }
+        if (!operation.getResponses().containsKey("500")) {
+            operation.getResponses().addApiResponse("500", create500Response());
+        }
+    }
+
+    private ApiResponse create400Response() {
+        return new ApiResponse()
+                .description(
+                        "Bad request - Invalid input parameters, unsupported format, or corrupted file")
+                .content(
+                        new Content()
+                                .addMediaType(
+                                        "application/json",
+                                        new MediaType()
+                                                .schema(
+                                                        createErrorSchema(
+                                                                400,
+                                                                "Invalid input parameters or corrupted file",
+                                                                "/api/v1/example/endpoint"))
+                                                .example(
+                                                        createErrorExample(
+                                                                400,
+                                                                "Invalid input parameters or corrupted file",
+                                                                "/api/v1/example/endpoint"))));
+    }
+
+    private ApiResponse create413Response() {
+        return new ApiResponse()
+                .description("Payload too large - File exceeds maximum allowed size")
+                .content(
+                        new Content()
+                                .addMediaType(
+                                        "application/json",
+                                        new MediaType()
+                                                .schema(
+                                                        createErrorSchema(
+                                                                413,
+                                                                "File size exceeds maximum allowed limit",
+                                                                "/api/v1/example/endpoint"))
+                                                .example(
+                                                        createErrorExample(
+                                                                413,
+                                                                "File size exceeds maximum allowed limit",
+                                                                "/api/v1/example/endpoint"))));
+    }
+
+    private ApiResponse create422Response() {
+        return new ApiResponse()
+                .description("Unprocessable entity - File is valid but cannot be processed")
+                .content(
+                        new Content()
+                                .addMediaType(
+                                        "application/json",
+                                        new MediaType()
+                                                .schema(
+                                                        createErrorSchema(
+                                                                422,
+                                                                "File is valid but cannot be processed",
+                                                                "/api/v1/example/endpoint"))
+                                                .example(
+                                                        createErrorExample(
+                                                                422,
+                                                                "File is valid but cannot be processed",
+                                                                "/api/v1/example/endpoint"))));
+    }
+
+    private ApiResponse create500Response() {
+        return new ApiResponse()
+                .description("Internal server error - Unexpected error during processing")
+                .content(
+                        new Content()
+                                .addMediaType(
+                                        "application/json",
+                                        new MediaType()
+                                                .schema(
+                                                        createErrorSchema(
+                                                                500,
+                                                                "Unexpected error during processing",
+                                                                "/api/v1/example/endpoint"))
+                                                .example(
+                                                        createErrorExample(
+                                                                500,
+                                                                "Unexpected error during processing",
+                                                                "/api/v1/example/endpoint"))));
+    }
+
+    private Schema<?> createErrorSchema(int status, String message, String path) {
+        return new Schema<>()
+                .type("object")
+                .addProperty("status", new Schema<>().type("integer").example(status))
+                .addProperty("error", new Schema<>().type("string").example(getErrorType(status)))
+                .addProperty("message", new Schema<>().type("string").example(message))
+                .addProperty(
+                        "timestamp",
+                        new Schema<>()
+                                .type("string")
+                                .format("date-time")
+                                .example("2024-01-15T10:30:00Z"))
+                .addProperty("path", new Schema<>().type("string").example(path));
+    }
+
+    private Object createErrorExample(int status, String message, String path) {
+        return java.util.Map.of(
+                "status", status,
+                "error", getErrorType(status),
+                "message", message,
+                "timestamp", "2024-01-15T10:30:00Z",
+                "path", path);
+    }
+
+    private String getErrorType(int status) {
+        return switch (status) {
+            case 400 -> "Bad Request";
+            case 413 -> "Payload Too Large";
+            case 422 -> "Unprocessable Entity";
+            case 500 -> "Internal Server Error";
+            default -> "Error";
+        };
+    }
+}

app/core/src/main/java/stirling/software/SPDF/config/OpenApiConfig.java

@@ -1,5 +1,8 @@
 package stirling.software.SPDF.config;
 
+import java.util.List;
+
+import org.springdoc.core.customizers.OpenApiCustomizer;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
@@ -8,6 +11,10 @@ import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Contact;
 import io.swagger.v3.oas.models.info.Info;
 import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.media.ComposedSchema;
+import io.swagger.v3.oas.models.media.ObjectSchema;
+import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.media.StringSchema;
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 import io.swagger.v3.oas.models.security.SecurityScheme;
 import io.swagger.v3.oas.models.servers.Server;
@@ -42,8 +49,7 @@ public class OpenApiConfig {
                                 new License()
                                         .name("MIT")
                                         .url(
-                                                "https://raw.githubusercontent.com/Stirling-Tools/Stirling-PDF/refs/heads/main/LICENSE")
-                                        .identifier("MIT"))
+                                                "https://raw.githubusercontent.com/Stirling-Tools/Stirling-PDF/refs/heads/main/LICENSE"))
                         .termsOfService("https://www.stirlingpdf.com/terms")
                         .contact(
                                 new Contact()
@@ -52,7 +58,7 @@ public class OpenApiConfig {
                                         .email("contact@stirlingpdf.com"))
                         .description(DEFAULT_DESCRIPTION);
 
-        OpenAPI openAPI = new OpenAPI().info(info);
+        OpenAPI openAPI = new OpenAPI().info(info).openapi("3.0.3");
 
         // Add server configuration from environment variable
         String swaggerServerUrl = System.getenv("SWAGGER_SERVER_URL");
@@ -61,16 +67,83 @@ public class OpenApiConfig {
             openAPI.addServersItem(server);
         }
 
+        // Add ErrorResponse schema to components
+        Schema<?> errorResponseSchema =
+                new Schema<>()
+                        .type("object")
+                        .addProperty(
+                                "timestamp",
+                                new Schema<>()
+                                        .type("string")
+                                        .format("date-time")
+                                        .description("Error timestamp"))
+                        .addProperty(
+                                "status",
+                                new Schema<>().type("integer").description("HTTP status code"))
+                        .addProperty(
+                                "error", new Schema<>().type("string").description("Error type"))
+                        .addProperty(
+                                "message",
+                                new Schema<>().type("string").description("Error message"))
+                        .addProperty(
+                                "path", new Schema<>().type("string").description("Request path"))
+                        .description("Standard error response format");
+
+        Components components = new Components().addSchemas("ErrorResponse", errorResponseSchema);
+
         if (!applicationProperties.getSecurity().getEnableLogin()) {
-            return openAPI.components(new Components());
+            return openAPI.components(components);
         } else {
             SecurityScheme apiKeyScheme =
                     new SecurityScheme()
                             .type(SecurityScheme.Type.APIKEY)
                             .in(SecurityScheme.In.HEADER)
                             .name("X-API-KEY");
-            return openAPI.components(new Components().addSecuritySchemes("apiKey", apiKeyScheme))
+            components.addSecuritySchemes("apiKey", apiKeyScheme);
+            return openAPI.components(components)
                     .addSecurityItem(new SecurityRequirement().addList("apiKey"));
         }
     }
+
+    @Bean
+    OpenApiCustomizer pdfFileOneOfCustomizer() {
+        return openApi -> {
+            var components = openApi.getComponents();
+            var schemas = components.getSchemas();
+
+            // Define the two shapes
+            var upload =
+                    new ObjectSchema()
+                            .name("PDFFileUpload")
+                            .description("Upload a PDF file")
+                            .addProperty("fileInput", new StringSchema().format("binary"))
+                            .addRequiredItem("fileInput");
+
+            var ref =
+                    new ObjectSchema()
+                            .name("PDFFileRef")
+                            .description("Reference a server-side file")
+                            .addProperty(
+                                    "fileId",
+                                    new StringSchema()
+                                            .example("a1b2c3d4-5678-90ab-cdef-ghijklmnopqr"))
+                            .addRequiredItem("fileId");
+
+            schemas.put("PDFFileUpload", upload);
+            schemas.put("PDFFileRef", ref);
+
+            // Create the oneOf schema
+            var pdfFileOneOf =
+                    new ComposedSchema()
+                            .oneOf(
+                                    List.of(
+                                            new Schema<>()
+                                                    .$ref("#/components/schemas/PDFFileUpload"),
+                                            new Schema<>().$ref("#/components/schemas/PDFFileRef")))
+                            .description("Either upload a file or provide a server-side file ID");
+
+            // Replace PDFFile schema
+            schemas.put("PDFFile", pdfFileOneOf);
+        };
+    }
 }

app/core/src/main/java/stirling/software/SPDF/config/SpringDocConfig.java

@@ -0,0 +1,83 @@
+package stirling.software.SPDF.config;
+
+import org.springdoc.core.customizers.OpenApiCustomizer;
+import org.springdoc.core.models.GroupedOpenApi;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class SpringDocConfig {
+
+    @Bean
+    public GroupedOpenApi pdfProcessingApi(
+            @Qualifier("pdfFileOneOfCustomizer") OpenApiCustomizer pdfFileOneOfCustomizer) {
+        return GroupedOpenApi.builder()
+                .group("file-processing")
+                .displayName("File Processing")
+                .pathsToMatch("/api/v1/**")
+                .pathsToExclude(
+                        "/api/v1/admin/**",
+                        "/api/v1/user/**",
+                        "/api/v1/settings/**",
+                        "/api/v1/team/**",
+                        "/api/v1/ui-data/**",
+                        "/api/v1/proprietary/ui-data/**",
+                        "/api/v1/info/**",
+                        "/api/v1/general/job/**",
+                        "/api/v1/general/files/**")
+                .addOpenApiCustomizer(pdfFileOneOfCustomizer)
+                .addOpenApiCustomizer(
+                        openApi -> {
+                            openApi.info(
+                                    openApi.getInfo()
+                                            .title("Stirling PDF - Processing API")
+                                            .description(
+                                                    "API documentation for PDF processing operations including conversion, manipulation, security, and utilities."));
+                        })
+                .build();
+    }
+
+    @Bean
+    public GroupedOpenApi adminApi() {
+        return GroupedOpenApi.builder()
+                .group("management")
+                .displayName("Management")
+                .pathsToMatch(
+                        "/api/v1/admin/**",
+                        "/api/v1/user/**",
+                        "/api/v1/settings/**",
+                        "/api/v1/team/**")
+                .addOpenApiCustomizer(
+                        openApi -> {
+                            openApi.info(
+                                    openApi.getInfo()
+                                            .title("Stirling PDF - Admin API")
+                                            .description(
+                                                    "API documentation for administrative functions, user management, and system configuration."));
+                        })
+                .build();
+    }
+
+    @Bean
+    public GroupedOpenApi systemApi() {
+        return GroupedOpenApi.builder()
+                .group("system")
+                .displayName("System & UI API")
+                .pathsToMatch(
+                        "/api/v1/ui-data/**",
+                        "/api/v1/proprietary/ui-data/**",
+                        "/api/v1/info/**",
+                        "/api/v1/general/job/**",
+                        "/api/v1/general/files/**")
+                .addOpenApiCustomizer(
+                        openApi -> {
+                            openApi.info(
+                                    openApi.getInfo()
+                                            .title("Stirling PDF - System API")
+                                            .description(
+                                                    "API documentation for system information, UI data, and utility endpoints."));
+                        })
+                .build();
+    }
+}

app/core/src/main/java/stirling/software/SPDF/config/swagger/CsvConversionResponse.java

@@ -0,0 +1,58 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for PDF to CSV conversions. Use for endpoints that convert PDF tables to
+ * CSV format.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF tables extracted successfully to CSV format",
+                    content = {
+                        @Content(
+                                mediaType = "text/csv",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description =
+                                                        "CSV file containing extracted table data")),
+                        @Content(
+                                mediaType = "application/zip",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description =
+                                                        "ZIP archive containing multiple CSV files when multiple tables are extracted"))
+                    }),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "Invalid PDF file or no tables found for extraction",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(responseCode = "204", description = "No tables found in the PDF"),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "Internal server error during table extraction",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface CsvConversionResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/ErrorResponse.java

@@ -0,0 +1,30 @@
+package stirling.software.SPDF.config.swagger;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+@Schema(description = "Standard error response")
+public class ErrorResponse {
+
+    @Schema(description = "HTTP status code", example = "400")
+    private int status;
+
+    @Schema(
+            description = "Error message describing what went wrong",
+            example = "Invalid PDF file or corrupted data")
+    private String message;
+
+    @Schema(description = "Timestamp when the error occurred", example = "2024-01-15T10:30:00Z")
+    private String timestamp;
+
+    @Schema(
+            description = "Request path where the error occurred",
+            example = "/api/v1/{endpoint-path}")
+    private String path;
+}

app/core/src/main/java/stirling/software/SPDF/config/swagger/FilterResponse.java

@@ -0,0 +1,67 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for filter operations that conditionally return the original file. Use
+ * for operations like text filters, page count filters, size filters, etc. Returns the original PDF
+ * if condition is met, otherwise returns no content (204).
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "Filter condition met - returns the original PDF file",
+                    content =
+                            @Content(
+                                    mediaType = "application/pdf",
+                                    schema =
+                                            @Schema(
+                                                    type = "string",
+                                                    format = "binary",
+                                                    description = "The original PDF file"))),
+            @ApiResponse(
+                    responseCode = "204",
+                    description = "Filter condition not met - no content returned",
+                    content = @Content()),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "Bad request - Invalid filter parameters or corrupted PDF",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "413",
+                    description = "Payload too large - File exceeds maximum allowed size",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "422",
+                    description =
+                            "Unprocessable entity - PDF is valid but cannot be analyzed for filtering",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "Internal server error - Unexpected error during PDF analysis",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface FilterResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/HtmlConversionResponse.java

@@ -0,0 +1,33 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for PDF to HTML conversions. Use for endpoints that convert PDF to HTML
+ * format.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF converted successfully to HTML format",
+                    content =
+                            @Content(
+                                    mediaType = "text/html",
+                                    schema =
+                                            @Schema(
+                                                    type = "string",
+                                                    format = "binary",
+                                                    description = "HTML file converted from PDF")))
+        })
+public @interface HtmlConversionResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/JavaScriptResponse.java

@@ -0,0 +1,34 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for JavaScript extraction from PDFs. Use for endpoints that extract
+ * JavaScript code from PDF documents.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "JavaScript extracted successfully from PDF",
+                    content =
+                            @Content(
+                                    mediaType = "text/plain",
+                                    schema =
+                                            @Schema(
+                                                    type = "string",
+                                                    format = "binary",
+                                                    description =
+                                                            "JavaScript code extracted from PDF")))
+        })
+public @interface JavaScriptResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/JsonDataResponse.java

@@ -0,0 +1,47 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for operations that return JSON data or analysis results. Use for
+ * analysis operations, metadata extraction, info operations, etc.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "Analysis or data extraction completed successfully",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema =
+                                            @Schema(
+                                                    type = "object",
+                                                    description =
+                                                            "JSON object containing the requested data or analysis results"))),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "Invalid PDF file or request parameters",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "Internal server error during processing",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface JsonDataResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/MarkdownConversionResponse.java

@@ -0,0 +1,34 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for PDF to Markdown conversions. Use for endpoints that convert PDF to
+ * Markdown format.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF converted successfully to Markdown format",
+                    content =
+                            @Content(
+                                    mediaType = "text/markdown",
+                                    schema =
+                                            @Schema(
+                                                    type = "string",
+                                                    format = "binary",
+                                                    description =
+                                                            "Markdown file converted from PDF")))
+        })
+public @interface MarkdownConversionResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/MultiFileResponse.java

@@ -0,0 +1,71 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for operations that may return multiple files or a ZIP archive. Use for
+ * operations like PDF to images, split PDF, or multiple file conversions.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description =
+                            "Files processed successfully. Returns single file or ZIP archive containing multiple files.",
+                    content = {
+                        @Content(
+                                mediaType = "application/pdf",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description = "Single PDF file result")),
+                        @Content(
+                                mediaType = "application/zip",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description =
+                                                        "ZIP archive containing multiple output files")),
+                        @Content(
+                                mediaType = "image/png",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description = "Single image file (PNG)")),
+                        @Content(
+                                mediaType = "image/jpeg",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description = "Single image file (JPEG)"))
+                    }),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "Invalid PDF file or request parameters",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "Internal server error during processing",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface MultiFileResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/PowerPointConversionResponse.java

@@ -0,0 +1,66 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for PDF to PowerPoint presentation conversions. Use for endpoints that
+ * convert PDF to PPTX format.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF converted successfully to PowerPoint presentation",
+                    content =
+                            @Content(
+                                    mediaType =
+                                            "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+                                    schema =
+                                            @Schema(
+                                                    type = "string",
+                                                    format = "binary",
+                                                    description =
+                                                            "Microsoft PowerPoint presentation (PPTX)"))),
+            @ApiResponse(
+                    responseCode = "400",
+                    description =
+                            "Bad request - Invalid input parameters, unsupported format, or corrupted PDF",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "413",
+                    description = "Payload too large - File exceeds maximum allowed size",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "422",
+                    description =
+                            "Unprocessable entity - PDF is valid but cannot be converted to PowerPoint format",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "500",
+                    description =
+                            "Internal server error - Unexpected error during PowerPoint conversion",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface PowerPointConversionResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/StandardPdfResponse.java

@@ -0,0 +1,47 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * Standard API response annotation for PDF operations that take PDF input and return PDF output.
+ * Use for single PDF input → single PDF output (SISO) operations like rotate, compress, etc.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF processed successfully",
+                    content =
+                            @Content(
+                                    mediaType = "application/pdf",
+                                    schema =
+                                            @Schema(
+                                                    type = "string",
+                                                    format = "binary",
+                                                    description = "The processed PDF file"))),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "Invalid PDF file or request parameters",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "Internal server error during processing",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface StandardPdfResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/TextPlainConversionResponse.java

@@ -0,0 +1,69 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for PDF to plain text conversions. Use for endpoints that extract text
+ * content from PDF.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF text extracted successfully",
+                    content = {
+                        @Content(
+                                mediaType = "text/plain",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                description =
+                                                        "Plain text content extracted from PDF")),
+                        @Content(
+                                mediaType = "application/rtf",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description = "Rich Text Format document"))
+                    }),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "Bad request - Invalid input parameters or corrupted PDF",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "413",
+                    description = "Payload too large - File exceeds maximum allowed size",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "422",
+                    description = "Unprocessable entity - PDF is valid but text extraction failed",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "Internal server error - Unexpected error during text extraction",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface TextPlainConversionResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/WordConversionResponse.java

@@ -0,0 +1,72 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for PDF to Word document conversions. Use for endpoints that convert PDF
+ * to DOCX/DOC formats.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF converted successfully to Word document",
+                    content = {
+                        @Content(
+                                mediaType =
+                                        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description = "Microsoft Word document (DOCX)")),
+                        @Content(
+                                mediaType = "application/msword",
+                                schema =
+                                        @Schema(
+                                                type = "string",
+                                                format = "binary",
+                                                description = "Microsoft Word document (DOC)"))
+                    }),
+            @ApiResponse(
+                    responseCode = "400",
+                    description =
+                            "Bad request - Invalid input parameters, unsupported format, or corrupted PDF",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "413",
+                    description = "Payload too large - File exceeds maximum allowed size",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "422",
+                    description =
+                            "Unprocessable entity - PDF is valid but cannot be converted to Word format",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class))),
+            @ApiResponse(
+                    responseCode = "500",
+                    description = "Internal server error - Unexpected error during Word conversion",
+                    content =
+                            @Content(
+                                    mediaType = "application/json",
+                                    schema = @Schema(implementation = ErrorResponse.class)))
+        })
+public @interface WordConversionResponse {}

app/core/src/main/java/stirling/software/SPDF/config/swagger/XmlConversionResponse.java

@@ -0,0 +1,33 @@
+package stirling.software.SPDF.config.swagger;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+/**
+ * API response annotation for PDF to XML conversions. Use for endpoints that convert PDF to XML
+ * format.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@ApiResponses(
+        value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "PDF converted successfully to XML format",
+                    content =
+                            @Content(
+                                    mediaType = "application/xml",
+                                    schema =
+                                            @Schema(
+                                                    type = "string",
+                                                    format = "binary",
+                                                    description = "XML file converted from PDF")))
+        })
+public @interface XmlConversionResponse {}

app/core/src/main/java/stirling/software/SPDF/controller/api/AnalysisController.java

@@ -14,23 +14,26 @@ import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
 import org.springframework.web.bind.annotation.*;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.JsonDataResponse;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.AnalysisApi;
 import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 
-@RestController
-@RequestMapping("/api/v1/analysis")
-@Tag(name = "Analysis", description = "Analysis APIs")
+@AnalysisApi
 @RequiredArgsConstructor
 public class AnalysisController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(value = "/page-count", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get PDF page count",
             description = "Returns total number of pages in PDF. Input:PDF Output:JSON Type:SISO")
@@ -41,6 +44,7 @@ public class AnalysisController {
     }
 
     @AutoJobPostMapping(value = "/basic-info", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get basic PDF information",
             description = "Returns page count, version, file size. Input:PDF Output:JSON Type:SISO")
@@ -55,6 +59,7 @@ public class AnalysisController {
     }
 
     @AutoJobPostMapping(value = "/document-properties", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get PDF document properties",
             description = "Returns title, author, subject, etc. Input:PDF Output:JSON Type:SISO")
@@ -78,6 +83,7 @@ public class AnalysisController {
     }
 
     @AutoJobPostMapping(value = "/page-dimensions", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get page dimensions for all pages",
             description = "Returns width and height of each page. Input:PDF Output:JSON Type:SISO")
@@ -86,18 +92,29 @@ public class AnalysisController {
         try (PDDocument document = pdfDocumentFactory.load(file.getFileInput())) {
             List<Map<String, Float>> dimensions = new ArrayList<>();
             PDPageTree pages = document.getPages();
+            JobProgressTracker progressTracker =
+                    jobProgressService.tracker(Math.max(1, pages.getCount()));
+            boolean trackProgress = progressTracker.isEnabled();
 
             for (PDPage page : pages) {
                 Map<String, Float> pageDim = new HashMap<>();
                 pageDim.put("width", page.getBBox().getWidth());
                 pageDim.put("height", page.getBBox().getHeight());
                 dimensions.add(pageDim);
+                if (trackProgress) {
+                    progressTracker.advance();
+                }
+            }
+
+            if (trackProgress) {
+                progressTracker.complete();
             }
             return dimensions;
         }
     }
 
     @AutoJobPostMapping(value = "/form-fields", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get form field information",
             description =
@@ -121,6 +138,7 @@ public class AnalysisController {
     }
 
     @AutoJobPostMapping(value = "/annotation-info", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get annotation information",
             description = "Returns count and types of annotations. Input:PDF Output:JSON Type:SISO")
@@ -129,13 +147,24 @@ public class AnalysisController {
             Map<String, Object> annotInfo = new HashMap<>();
             int totalAnnotations = 0;
             Map<String, Integer> annotationTypes = new HashMap<>();
+            PDPageTree pages = document.getPages();
+            JobProgressTracker progressTracker =
+                    jobProgressService.tracker(Math.max(1, pages.getCount()));
+            boolean trackProgress = progressTracker.isEnabled();
 
-            for (PDPage page : document.getPages()) {
+            for (PDPage page : pages) {
                 for (PDAnnotation annot : page.getAnnotations()) {
                     totalAnnotations++;
                     String subType = annot.getSubtype();
                     annotationTypes.merge(subType, 1, Integer::sum);
                 }
+                if (trackProgress) {
+                    progressTracker.advance();
+                }
+            }
+
+            if (trackProgress) {
+                progressTracker.complete();
             }
 
             annotInfo.put("totalCount", totalAnnotations);
@@ -145,6 +174,7 @@ public class AnalysisController {
     }
 
     @AutoJobPostMapping(value = "/font-info", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get font information",
             description =
@@ -154,10 +184,22 @@ public class AnalysisController {
             Map<String, Object> fontInfo = new HashMap<>();
             Set<String> fontNames = new HashSet<>();
 
-            for (PDPage page : document.getPages()) {
+            PDPageTree pages = document.getPages();
+            JobProgressTracker progressTracker =
+                    jobProgressService.tracker(Math.max(1, pages.getCount()));
+            boolean trackProgress = progressTracker.isEnabled();
+
+            for (PDPage page : pages) {
                 for (COSName font : page.getResources().getFontNames()) {
                     fontNames.add(font.getName());
                 }
+                if (trackProgress) {
+                    progressTracker.advance();
+                }
+            }
+
+            if (trackProgress) {
+                progressTracker.complete();
             }
 
             fontInfo.put("fontCount", fontNames.size());
@@ -167,6 +209,7 @@ public class AnalysisController {
     }
 
     @AutoJobPostMapping(value = "/security-info", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Get security information",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/BookletImpositionController.java

@@ -0,0 +1,341 @@
+package stirling.software.SPDF.controller.api;
+
+import java.awt.*;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.pdfbox.multipdf.LayerUtility;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.PDPageContentStream;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.graphics.form.PDFormXObject;
+import org.apache.pdfbox.util.Matrix;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ModelAttribute;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.multipart.MultipartFile;
+
+import io.github.pixee.security.Filenames;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.SPDF.model.api.general.BookletImpositionRequest;
+import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
+import stirling.software.common.util.WebResponseUtils;
+
+@RestController
+@RequestMapping("/api/v1/general")
+@Tag(name = "General", description = "General APIs")
+@RequiredArgsConstructor
+public class BookletImpositionController {
+
+    private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
+
+    @AutoJobPostMapping(value = "/booklet-imposition", consumes = "multipart/form-data")
+    @Operation(
+            summary = "Create a booklet with proper page imposition",
+            description =
+                    "This operation combines page reordering for booklet printing with multi-page layout. "
+                            + "It rearranges pages in the correct order for booklet printing and places multiple pages "
+                            + "on each sheet for proper folding and binding. Input:PDF Output:PDF Type:SISO")
+    public ResponseEntity<byte[]> createBookletImposition(
+            @ModelAttribute BookletImpositionRequest request) throws IOException {
+
+        MultipartFile file = request.getFileInput();
+        int pagesPerSheet = request.getPagesPerSheet();
+        boolean addBorder = Boolean.TRUE.equals(request.getAddBorder());
+        String spineLocation =
+                request.getSpineLocation() != null ? request.getSpineLocation() : "LEFT";
+        boolean addGutter = Boolean.TRUE.equals(request.getAddGutter());
+        float gutterSize = request.getGutterSize();
+        boolean doubleSided = Boolean.TRUE.equals(request.getDoubleSided());
+        String duplexPass = request.getDuplexPass() != null ? request.getDuplexPass() : "BOTH";
+        boolean flipOnShortEdge = Boolean.TRUE.equals(request.getFlipOnShortEdge());
+
+        // Validate pages per sheet for booklet - only 2-up landscape is proper booklet
+        if (pagesPerSheet != 2) {
+            throw new IllegalArgumentException(
+                    "Booklet printing uses 2 pages per side (landscape). For 4-up, use the N-up feature.");
+        }
+
+        PDDocument sourceDocument = pdfDocumentFactory.load(file);
+        int totalPages = sourceDocument.getNumberOfPages();
+
+        List<Side> sides = saddleStitchSides(totalPages, doubleSided, duplexPass, flipOnShortEdge);
+        JobProgressTracker progressTracker = jobProgressService.tracker(Math.max(1, sides.size()));
+        boolean trackProgress = progressTracker.isEnabled();
+
+        // Create proper booklet with signature-based page ordering
+        PDDocument newDocument =
+                createSaddleBooklet(
+                        sourceDocument,
+                        addBorder,
+                        spineLocation,
+                        addGutter,
+                        gutterSize,
+                        doubleSided,
+                        duplexPass,
+                        flipOnShortEdge,
+                        sides,
+                        progressTracker,
+                        trackProgress);
+
+        sourceDocument.close();
+
+        if (trackProgress) {
+            progressTracker.complete();
+        }
+
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        newDocument.save(baos);
+        newDocument.close();
+
+        byte[] result = baos.toByteArray();
+        return WebResponseUtils.bytesToWebResponse(
+                result,
+                Filenames.toSimpleFileName(file.getOriginalFilename()).replaceFirst("[.][^.]+$", "")
+                        + "_booklet.pdf");
+    }
+
+    private static int padToMultipleOf4(int n) {
+        return (n + 3) / 4 * 4;
+    }
+
+    private static class Side {
+        final int left, right;
+        final boolean isBack;
+
+        Side(int left, int right, boolean isBack) {
+            this.left = left;
+            this.right = right;
+            this.isBack = isBack;
+        }
+    }
+
+    private static List<Side> saddleStitchSides(
+            int totalPagesOriginal,
+            boolean doubleSided,
+            String duplexPass,
+            boolean flipOnShortEdge) {
+        int N = padToMultipleOf4(totalPagesOriginal);
+        List<Side> out = new ArrayList<>();
+        int sheets = N / 4;
+
+        for (int s = 0; s < sheets; s++) {
+            int a = N - 1 - (s * 2); // left, front
+            int b = (s * 2); // right, front
+            int c = (s * 2) + 1; // left, back
+            int d = N - 2 - (s * 2); // right, back
+
+            // clamp to -1 (blank) if >= totalPagesOriginal
+            a = (a < totalPagesOriginal) ? a : -1;
+            b = (b < totalPagesOriginal) ? b : -1;
+            c = (c < totalPagesOriginal) ? c : -1;
+            d = (d < totalPagesOriginal) ? d : -1;
+
+            // Handle duplex pass selection
+            boolean includeFront = "BOTH".equals(duplexPass) || "FIRST".equals(duplexPass);
+            boolean includeBack = "BOTH".equals(duplexPass) || "SECOND".equals(duplexPass);
+
+            if (includeFront) {
+                out.add(new Side(a, b, false)); // front side
+            }
+
+            if (includeBack) {
+                // For short-edge duplex, swap back-side left/right
+                // Note: flipOnShortEdge is ignored in manual duplex mode since users physically
+                // flip the stack
+                if (doubleSided && flipOnShortEdge) {
+                    out.add(new Side(d, c, true)); // swapped back side (automatic duplex only)
+                } else {
+                    out.add(new Side(c, d, true)); // normal back side
+                }
+            }
+        }
+        return out;
+    }
+
+    private PDDocument createSaddleBooklet(
+            PDDocument src,
+            boolean addBorder,
+            String spineLocation,
+            boolean addGutter,
+            float gutterSize,
+            boolean doubleSided,
+            String duplexPass,
+            boolean flipOnShortEdge,
+            List<Side> sides,
+            JobProgressTracker progressTracker,
+            boolean trackProgress)
+            throws IOException {
+
+        PDDocument dst = pdfDocumentFactory.createNewDocumentBasedOnOldDocument(src);
+
+        // Derive paper size from source document's first page CropBox
+        PDRectangle srcBox = src.getPage(0).getCropBox();
+        PDRectangle portraitPaper = new PDRectangle(srcBox.getWidth(), srcBox.getHeight());
+        // Force landscape for booklet (Acrobat booklet uses landscape paper to fold to portrait)
+        PDRectangle pageSize = new PDRectangle(portraitPaper.getHeight(), portraitPaper.getWidth());
+
+        // Validate and clamp gutter size
+        if (gutterSize < 0) gutterSize = 0;
+        if (gutterSize >= pageSize.getWidth() / 2f) gutterSize = pageSize.getWidth() / 2f - 1f;
+
+        for (Side side : sides) {
+            PDPage out = new PDPage(pageSize);
+            dst.addPage(out);
+
+            float cellW = pageSize.getWidth() / 2f;
+            float cellH = pageSize.getHeight();
+
+            // For RIGHT spine (RTL), swap left/right placements
+            boolean rtl = "RIGHT".equalsIgnoreCase(spineLocation);
+            int leftCol = rtl ? 1 : 0;
+            int rightCol = rtl ? 0 : 1;
+
+            // Apply gutter margins with centered gap option
+            float g = addGutter ? gutterSize : 0f;
+            float leftCellX = leftCol * cellW + (g / 2f);
+            float rightCellX = rightCol * cellW - (g / 2f);
+            float leftCellW = cellW - (g / 2f);
+            float rightCellW = cellW - (g / 2f);
+
+            // Create LayerUtility once per page for efficiency
+            LayerUtility layerUtility = new LayerUtility(dst);
+
+            try (PDPageContentStream cs =
+                    new PDPageContentStream(
+                            dst, out, PDPageContentStream.AppendMode.APPEND, true, true)) {
+
+                if (addBorder) {
+                    cs.setLineWidth(1.5f);
+                    cs.setStrokingColor(Color.BLACK);
+                }
+
+                // draw left cell
+                drawCell(
+                        src,
+                        dst,
+                        cs,
+                        layerUtility,
+                        side.left,
+                        leftCellX,
+                        0f,
+                        leftCellW,
+                        cellH,
+                        addBorder);
+                // draw right cell
+                drawCell(
+                        src,
+                        dst,
+                        cs,
+                        layerUtility,
+                        side.right,
+                        rightCellX,
+                        0f,
+                        rightCellW,
+                        cellH,
+                        addBorder);
+            }
+
+            if (trackProgress) {
+                progressTracker.advance();
+            }
+        }
+        return dst;
+    }
+
+    private void drawCell(
+            PDDocument src,
+            PDDocument dst,
+            PDPageContentStream cs,
+            LayerUtility layerUtility,
+            int pageIndex,
+            float cellX,
+            float cellY,
+            float cellW,
+            float cellH,
+            boolean addBorder)
+            throws IOException {
+
+        if (pageIndex < 0) {
+            // Draw border for blank cell if needed
+            if (addBorder) {
+                cs.addRect(cellX, cellY, cellW, cellH);
+                cs.stroke();
+            }
+            return;
+        }
+
+        PDPage srcPage = src.getPage(pageIndex);
+        PDRectangle r = srcPage.getCropBox(); // Use CropBox instead of MediaBox
+        int rot = (srcPage.getRotation() + 360) % 360;
+
+        // Calculate scale factors, accounting for rotation
+        float sx = cellW / r.getWidth();
+        float sy = cellH / r.getHeight();
+        float s = Math.min(sx, sy);
+
+        // If rotated 90/270 degrees, swap dimensions for fitting
+        if (rot == 90 || rot == 270) {
+            sx = cellW / r.getHeight();
+            sy = cellH / r.getWidth();
+            s = Math.min(sx, sy);
+        }
+
+        float drawnW = (rot == 90 || rot == 270) ? r.getHeight() * s : r.getWidth() * s;
+        float drawnH = (rot == 90 || rot == 270) ? r.getWidth() * s : r.getHeight() * s;
+
+        // Center in cell, accounting for CropBox offset
+        float tx = cellX + (cellW - drawnW) / 2f - r.getLowerLeftX() * s;
+        float ty = cellY + (cellH - drawnH) / 2f - r.getLowerLeftY() * s;
+
+        cs.saveGraphicsState();
+        cs.transform(Matrix.getTranslateInstance(tx, ty));
+        cs.transform(Matrix.getScaleInstance(s, s));
+
+        // Apply rotation if needed (rotate about origin), then translate to keep in cell
+        switch (rot) {
+            case 90:
+                cs.transform(Matrix.getRotateInstance(Math.PI / 2, 0, 0));
+                // After 90° CCW, the content spans x in [-r.getHeight(), 0] and y in [0,
+                // r.getWidth()]
+                cs.transform(Matrix.getTranslateInstance(0, -r.getWidth()));
+                break;
+            case 180:
+                cs.transform(Matrix.getRotateInstance(Math.PI, 0, 0));
+                cs.transform(Matrix.getTranslateInstance(-r.getWidth(), -r.getHeight()));
+                break;
+            case 270:
+                cs.transform(Matrix.getRotateInstance(3 * Math.PI / 2, 0, 0));
+                // After 270° CCW, the content spans x in [0, r.getHeight()] and y in
+                // [-r.getWidth(), 0]
+                cs.transform(Matrix.getTranslateInstance(-r.getHeight(), 0));
+                break;
+            default:
+                // 0°: no-op
+        }
+
+        // Reuse LayerUtility passed from caller
+        PDFormXObject form = layerUtility.importPageAsForm(src, pageIndex);
+        cs.drawForm(form);
+
+        cs.restoreGraphicsState();
+
+        // Draw border on top of form to ensure visibility
+        if (addBorder) {
+            cs.addRect(cellX, cellY, cellW, cellH);
+            cs.stroke();
+        }
+    }
+}

app/core/src/main/java/stirling/software/SPDF/controller/api/CropController.java

@@ -12,28 +12,29 @@ import org.apache.pdfbox.pdmodel.common.PDRectangle;
 import org.apache.pdfbox.pdmodel.graphics.form.PDFormXObject;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.general.CropPdfForm;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class CropController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(value = "/crop", consumes = "multipart/form-data")
+    @StandardPdfResponse
     @Operation(
             summary = "Crops a PDF document",
             description =
@@ -46,6 +47,8 @@ public class CropController {
                 pdfDocumentFactory.createNewDocumentBasedOnOldDocument(sourceDocument);
 
         int totalPages = sourceDocument.getNumberOfPages();
+        JobProgressTracker progressTracker = jobProgressService.tracker(Math.max(1, totalPages));
+        boolean trackProgress = progressTracker.isEnabled();
 
         LayerUtility layerUtility = new LayerUtility(newDocument);
 
@@ -82,6 +85,10 @@ public class CropController {
                             request.getY(),
                             request.getWidth(),
                             request.getHeight()));
+
+            if (trackProgress) {
+                progressTracker.advance();
+            }
         }
 
         ByteArrayOutputStream baos = new ByteArrayOutputStream();
@@ -89,6 +96,10 @@ public class CropController {
         newDocument.close();
         sourceDocument.close();
 
+        if (trackProgress) {
+            progressTracker.complete();
+        }
+
         byte[] pdfContent = baos.toByteArray();
         return WebResponseUtils.bytesToWebResponse(
                 pdfContent,

app/core/src/main/java/stirling/software/SPDF/controller/api/EditTableOfContentsController.java

@@ -14,30 +14,28 @@ import org.apache.pdfbox.pdmodel.interactive.documentnavigation.outline.PDOutlin
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.ResponseBody;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.JsonDataResponse;
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.EditTableOfContentsRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
+@GeneralApi
 @Slf4j
-@Tag(name = "General", description = "General APIs")
 @RequiredArgsConstructor
 public class EditTableOfContentsController {
 
@@ -45,6 +43,7 @@ public class EditTableOfContentsController {
     private final ObjectMapper objectMapper;
 
     @AutoJobPostMapping(value = "/extract-bookmarks", consumes = "multipart/form-data")
+    @JsonDataResponse
     @Operation(
             summary = "Extract PDF Bookmarks",
             description = "Extracts bookmarks/table of contents from a PDF document as JSON.")
@@ -153,6 +152,7 @@ public class EditTableOfContentsController {
     }
 
     @AutoJobPostMapping(value = "/edit-table-of-contents", consumes = "multipart/form-data")
+    @StandardPdfResponse
     @Operation(
             summary = "Edit Table of Contents",
             description = "Add or edit bookmarks/table of contents in a PDF document.")

app/core/src/main/java/stirling/software/SPDF/controller/api/MergeController.java

@@ -3,6 +3,7 @@ package stirling.software.SPDF.controller.api;
 import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.nio.file.attribute.BasicFileAttributes;
@@ -20,34 +21,36 @@ import org.apache.pdfbox.pdmodel.interactive.documentnavigation.outline.PDOutlin
 import org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm;
 import org.apache.pdfbox.pdmodel.interactive.form.PDField;
 import org.apache.pdfbox.pdmodel.interactive.form.PDSignatureField;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.general.MergePdfsRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.GeneralUtils;
 import stirling.software.common.util.PdfErrorUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
+@GeneralApi
 @Slf4j
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
 @RequiredArgsConstructor
 public class MergeController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     // Merges a list of PDDocument objects into a single PDDocument
     public PDDocument mergeDocuments(List<PDDocument> documents) throws IOException {
@@ -114,6 +117,32 @@ public class MergeController {
         }
     }
 
+    // Parse client file IDs from JSON string
+    private String[] parseClientFileIds(String clientFileIds) {
+        if (clientFileIds == null || clientFileIds.trim().isEmpty()) {
+            return new String[0];
+        }
+        try {
+            // Simple JSON array parsing - remove brackets and split by comma
+            String trimmed = clientFileIds.trim();
+            if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+                String inside = trimmed.substring(1, trimmed.length() - 1).trim();
+                if (inside.isEmpty()) {
+                    return new String[0];
+                }
+                String[] parts = inside.split(",");
+                String[] result = new String[parts.length];
+                for (int i = 0; i < parts.length; i++) {
+                    result[i] = parts[i].trim().replaceAll("^\"|\"$", "");
+                }
+                return result;
+            }
+        } catch (Exception e) {
+            log.warn("Failed to parse client file IDs: {}", clientFileIds, e);
+        }
+        return new String[0];
+    }
+
     // Adds a table of contents to the merged document using filenames as chapter titles
     private void addTableOfContents(PDDocument mergedDocument, MultipartFile[] files) {
         // Create the document outline
@@ -155,6 +184,7 @@ public class MergeController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/merge-pdfs")
+    @StandardPdfResponse
     @Operation(
             summary = "Merge multiple PDF files into one",
             description =
@@ -177,20 +207,67 @@ public class MergeController {
                     getSortComparator(
                             request.getSortType())); // Sort files based on the given sort type
 
+            JobProgressTracker progressTracker =
+                    jobProgressService.tracker(Math.max(1, files.length) + 4);
+            boolean trackProgress = progressTracker.isEnabled();
+
             PDFMergerUtility mergerUtility = new PDFMergerUtility();
             long totalSize = 0;
-            for (MultipartFile multipartFile : files) {
+            List<Integer> invalidIndexes = new ArrayList<>();
+            for (int index = 0; index < files.length; index++) {
+                MultipartFile multipartFile = files[index];
                 totalSize += multipartFile.getSize();
                 File tempFile =
                         GeneralUtils.convertMultipartFileToFile(
                                 multipartFile); // Convert MultipartFile to File
                 filesToDelete.add(tempFile); // Add temp file to the list for later deletion
+
+                // Pre-validate each PDF so we can report which one(s) are broken
+                // Use the original MultipartFile to avoid deleting the tempFile during validation
+                try (PDDocument ignored = pdfDocumentFactory.load(multipartFile)) {
+                    // OK
+                } catch (IOException e) {
+                    ExceptionUtils.logException("PDF pre-validate", e);
+                    invalidIndexes.add(index);
+                }
                 mergerUtility.addSource(tempFile); // Add source file to the merger utility
+
+                if (trackProgress) {
+                    progressTracker.advance();
+                }
+            }
+
+            if (!invalidIndexes.isEmpty()) {
+                // Parse client file IDs (always present from frontend)
+                String[] clientIds = parseClientFileIds(request.getClientFileIds());
+
+                // Map invalid indexes to client IDs
+                List<String> errorFileIds = new ArrayList<>();
+                for (Integer index : invalidIndexes) {
+                    if (index < clientIds.length) {
+                        errorFileIds.add(clientIds[index]);
+                    }
+                }
+
+                String payload =
+                        String.format(
+                                "{\"errorFileIds\":%s,\"message\":\"Some of the selected files can't be merged\"}",
+                                errorFileIds.toString());
+
+                jobProgressService.updateProgress(100, null);
+
+                return ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY)
+                        .header("Content-Type", MediaType.APPLICATION_JSON_VALUE)
+                        .body(payload.getBytes(StandardCharsets.UTF_8));
             }
 
             mergedTempFile = Files.createTempFile("merged-", ".pdf").toFile();
             mergerUtility.setDestinationFileName(mergedTempFile.getAbsolutePath());
 
+            if (trackProgress) {
+                progressTracker.advance();
+            }
+
             try {
                 mergerUtility.mergeDocuments(
                         pdfDocumentFactory.getStreamCacheFunction(
@@ -229,10 +306,18 @@ public class MergeController {
                 addTableOfContents(mergedDocument, files);
             }
 
+            if (trackProgress) {
+                progressTracker.advance();
+            }
+
             // Save the modified document to a new ByteArrayOutputStream
             ByteArrayOutputStream baos = new ByteArrayOutputStream();
             mergedDocument.save(baos);
 
+            if (trackProgress) {
+                progressTracker.complete();
+            }
+
             String mergedFileName =
                     files[0].getOriginalFilename().replaceFirst("[.][^.]+$", "")
                             + "_merged_unsigned.pdf";

app/core/src/main/java/stirling/software/SPDF/controller/api/MultiPageLayoutController.java

@@ -13,30 +13,31 @@ import org.apache.pdfbox.pdmodel.graphics.form.PDFormXObject;
 import org.apache.pdfbox.util.Matrix;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.general.MergeMultiplePagesRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class MultiPageLayoutController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(value = "/multi-page-layout", consumes = "multipart/form-data")
+    @StandardPdfResponse
     @Operation(
             summary = "Merge multiple pages of a PDF document into a single page",
             description =
@@ -68,6 +69,8 @@ public class MultiPageLayoutController {
         newDocument.addPage(newPage);
 
         int totalPages = sourceDocument.getNumberOfPages();
+        JobProgressTracker progressTracker = jobProgressService.tracker(Math.max(1, totalPages));
+        boolean trackProgress = progressTracker.isEnabled();
         float cellWidth = newPage.getMediaBox().getWidth() / cols;
         float cellHeight = newPage.getMediaBox().getHeight() / rows;
 
@@ -128,6 +131,10 @@ public class MultiPageLayoutController {
                 contentStream.addRect(borderX, borderY, cellWidth, cellHeight);
                 contentStream.stroke();
             }
+
+            if (trackProgress) {
+                progressTracker.advance();
+            }
         }
 
         contentStream.close(); // Close the final content stream
@@ -137,6 +144,10 @@ public class MultiPageLayoutController {
         newDocument.save(baos);
         newDocument.close();
 
+        if (trackProgress) {
+            progressTracker.complete();
+        }
+
         byte[] result = baos.toByteArray();
         return WebResponseUtils.bytesToWebResponse(
                 result,

app/core/src/main/java/stirling/software/SPDF/controller/api/PdfImageRemovalController.java

@@ -6,27 +6,26 @@ import java.io.IOException;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.service.PdfImageRemovalService;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.WebResponseUtils;
 
 /**
  * Controller class for handling PDF image removal requests. Provides an endpoint to remove images
  * from a PDF file to reduce its size.
  */
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class PdfImageRemovalController {
 
@@ -35,6 +34,8 @@ public class PdfImageRemovalController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
 
+    private final JobProgressService jobProgressService;
+
     /**
      * Endpoint to remove images from a PDF file.
      *
@@ -47,17 +48,23 @@ public class PdfImageRemovalController {
      * @throws IOException If an error occurs while processing the PDF file.
      */
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/remove-image-pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Remove images from file to reduce the file size.",
             description =
                     "This endpoint remove images from file to reduce the file size.Input:PDF"
-                            + " Output:PDF Type:MISO")
+                            + " Output:PDF Type:SISO")
     public ResponseEntity<byte[]> removeImages(@ModelAttribute PDFFile file) throws IOException {
         // Load the PDF document
         PDDocument document = pdfDocumentFactory.load(file);
 
+        int pageCount = Math.max(1, document.getNumberOfPages());
+        JobProgressTracker progressTracker = jobProgressService.tracker(pageCount + 1);
+        boolean trackProgress = progressTracker.isEnabled();
+
         // Remove images from the PDF document using the service
-        PDDocument modifiedDocument = pdfImageRemovalService.removeImagesFromPdf(document);
+        PDDocument modifiedDocument =
+                pdfImageRemovalService.removeImagesFromPdf(document, progressTracker);
 
         // Create a ByteArrayOutputStream to hold the modified PDF data
         ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
@@ -71,6 +78,10 @@ public class PdfImageRemovalController {
                 file.getFileInput().getOriginalFilename().replaceFirst("[.][^.]+$", "")
                         + "_removed_images.pdf";
 
+        if (trackProgress) {
+            progressTracker.complete();
+        }
+
         // Convert the byte array to a web response and return it
         return WebResponseUtils.bytesToWebResponse(outputStream.toByteArray(), mergedFileName);
     }

app/core/src/main/java/stirling/software/SPDF/controller/api/PdfOverlayController.java

@@ -15,31 +15,32 @@ import org.apache.pdfbox.pdmodel.PDDocument;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.general.OverlayPdfsRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.GeneralUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class PdfOverlayController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(value = "/overlay-pdfs", consumes = "multipart/form-data")
+    @StandardPdfResponse
     @Operation(
             summary = "Overlay PDF files in various modes",
             description =
@@ -65,13 +66,17 @@ public class PdfOverlayController {
 
             try (PDDocument basePdf = pdfDocumentFactory.load(baseFile);
                     Overlay overlay = new Overlay()) {
+                JobProgressTracker progressTracker =
+                        jobProgressService.tracker(basePdf.getNumberOfPages() + 1);
+                boolean trackProgress = progressTracker.isEnabled();
                 Map<Integer, String> overlayGuide =
                         prepareOverlayGuide(
                                 basePdf.getNumberOfPages(),
                                 overlayPdfFiles,
                                 mode,
                                 counts,
-                                tempFiles);
+                                tempFiles,
+                                progressTracker);
 
                 overlay.setInputPDF(basePdf);
                 if (overlayPos == 0) {
@@ -82,6 +87,13 @@ public class PdfOverlayController {
 
                 ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
                 overlay.overlay(overlayGuide).save(outputStream);
+
+                if (trackProgress) {
+                    progressTracker.advance();
+                    progressTracker.complete();
+                } else {
+                    jobProgressService.updateProgress(100, null);
+                }
                 byte[] data = outputStream.toByteArray();
                 String outputFilename =
                         Filenames.toSimpleFileName(baseFile.getOriginalFilename())
@@ -106,18 +118,25 @@ public class PdfOverlayController {
     }
 
     private Map<Integer, String> prepareOverlayGuide(
-            int basePageCount, File[] overlayFiles, String mode, int[] counts, List<File> tempFiles)
+            int basePageCount,
+            File[] overlayFiles,
+            String mode,
+            int[] counts,
+            List<File> tempFiles,
+            JobProgressTracker progressTracker)
             throws IOException {
         Map<Integer, String> overlayGuide = new HashMap<>();
         switch (mode) {
             case "SequentialOverlay":
-                sequentialOverlay(overlayGuide, overlayFiles, basePageCount, tempFiles);
+                sequentialOverlay(
+                        overlayGuide, overlayFiles, basePageCount, tempFiles, progressTracker);
                 break;
             case "InterleavedOverlay":
-                interleavedOverlay(overlayGuide, overlayFiles, basePageCount);
+                interleavedOverlay(overlayGuide, overlayFiles, basePageCount, progressTracker);
                 break;
             case "FixedRepeatOverlay":
-                fixedRepeatOverlay(overlayGuide, overlayFiles, counts, basePageCount);
+                fixedRepeatOverlay(
+                        overlayGuide, overlayFiles, counts, basePageCount, progressTracker);
                 break;
             default:
                 throw new IllegalArgumentException("Invalid overlay mode");
@@ -129,10 +148,12 @@ public class PdfOverlayController {
             Map<Integer, String> overlayGuide,
             File[] overlayFiles,
             int basePageCount,
-            List<File> tempFiles)
+            List<File> tempFiles,
+            JobProgressTracker progressTracker)
             throws IOException {
         int overlayFileIndex = 0;
         int pageCountInCurrentOverlay = 0;
+        boolean trackProgress = progressTracker.isEnabled();
 
         for (int basePageIndex = 1; basePageIndex <= basePageCount; basePageIndex++) {
             if (pageCountInCurrentOverlay == 0
@@ -154,6 +175,10 @@ public class PdfOverlayController {
             }
 
             pageCountInCurrentOverlay++;
+
+            if (trackProgress) {
+                progressTracker.advance();
+            }
         }
     }
 
@@ -164,8 +189,12 @@ public class PdfOverlayController {
     }
 
     private void interleavedOverlay(
-            Map<Integer, String> overlayGuide, File[] overlayFiles, int basePageCount)
+            Map<Integer, String> overlayGuide,
+            File[] overlayFiles,
+            int basePageCount,
+            JobProgressTracker progressTracker)
             throws IOException {
+        boolean trackProgress = progressTracker.isEnabled();
         for (int basePageIndex = 1; basePageIndex <= basePageCount; basePageIndex++) {
             File overlayFile = overlayFiles[(basePageIndex - 1) % overlayFiles.length];
 
@@ -176,17 +205,26 @@ public class PdfOverlayController {
                     overlayGuide.put(basePageIndex, overlayFile.getAbsolutePath());
                 }
             }
+
+            if (trackProgress) {
+                progressTracker.advance();
+            }
         }
     }
 
     private void fixedRepeatOverlay(
-            Map<Integer, String> overlayGuide, File[] overlayFiles, int[] counts, int basePageCount)
+            Map<Integer, String> overlayGuide,
+            File[] overlayFiles,
+            int[] counts,
+            int basePageCount,
+            JobProgressTracker progressTracker)
             throws IOException {
         if (overlayFiles.length != counts.length) {
             throw new IllegalArgumentException(
                     "Counts array length must match the number of overlay files");
         }
         int currentPage = 1;
+        boolean trackProgress = progressTracker.isEnabled();
         for (int i = 0; i < overlayFiles.length; i++) {
             File overlayFile = overlayFiles[i];
             int repeatCount = counts[i];
@@ -198,6 +236,9 @@ public class PdfOverlayController {
                     for (int page = 0; page < overlayPageCount; page++) {
                         if (currentPage > basePageCount) break;
                         overlayGuide.put(currentPage++, overlayFile.getAbsolutePath());
+                        if (trackProgress) {
+                            progressTracker.advance();
+                        }
                     }
                 }
             }

app/core/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java

@@ -9,36 +9,37 @@ import org.apache.pdfbox.pdmodel.PDDocument;
 import org.apache.pdfbox.pdmodel.PDPage;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.SortTypes;
 import stirling.software.SPDF.model.api.PDFWithPageNums;
 import stirling.software.SPDF.model.api.general.RearrangePagesRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.GeneralUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
+@GeneralApi
 @Slf4j
-@Tag(name = "General", description = "General APIs")
 @RequiredArgsConstructor
 public class RearrangePagesPDFController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/remove-pages")
+    @StandardPdfResponse
     @Operation(
             summary = "Remove pages from a PDF file",
             description =
@@ -61,9 +62,20 @@ public class RearrangePagesPDFController {
 
         Collections.sort(pagesToRemove);
 
+        JobProgressTracker progressTracker =
+                jobProgressService.tracker(Math.max(1, pagesToRemove.size()));
+        boolean trackProgress = progressTracker.isEnabled();
+
         for (int i = pagesToRemove.size() - 1; i >= 0; i--) {
             int pageIndex = pagesToRemove.get(i);
             document.removePage(pageIndex);
+            if (trackProgress) {
+                progressTracker.advance();
+            }
+        }
+
+        if (trackProgress) {
+            progressTracker.complete();
         }
         return WebResponseUtils.pdfDocToWebResponse(
                 document,
@@ -238,6 +250,7 @@ public class RearrangePagesPDFController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/rearrange-pages")
+    @StandardPdfResponse
     @Operation(
             summary = "Rearrange pages in a PDF file",
             description =
@@ -273,14 +286,30 @@ public class RearrangePagesPDFController {
                 newPages.add(document.getPage(newPageOrder.get(i)));
             }
 
+            int removalSteps = document.getNumberOfPages();
+            int additionSteps = newPages.size();
+            JobProgressTracker progressTracker =
+                    jobProgressService.tracker(Math.max(1, removalSteps + additionSteps));
+            boolean trackProgress = progressTracker.isEnabled();
+
             // Remove all the pages from the original document
             for (int i = document.getNumberOfPages() - 1; i >= 0; i--) {
                 document.removePage(i);
+                if (trackProgress) {
+                    progressTracker.advance();
+                }
             }
 
             // Add the pages in the new order
             for (PDPage page : newPages) {
                 document.addPage(page);
+                if (trackProgress) {
+                    progressTracker.advance();
+                }
+            }
+
+            if (trackProgress) {
+                progressTracker.complete();
             }
 
             return WebResponseUtils.pdfDocToWebResponse(

app/core/src/main/java/stirling/software/SPDF/controller/api/RotationController.java

@@ -7,31 +7,32 @@ import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.PDPageTree;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.general.RotatePDFRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class RotationController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/rotate-pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Rotate a PDF file",
             description =
@@ -53,9 +54,19 @@ public class RotationController {
 
         // Get the list of pages in the document
         PDPageTree pages = document.getPages();
+        int totalPages = Math.max(1, pages.getCount());
+        JobProgressTracker progressTracker = jobProgressService.tracker(totalPages);
+        boolean trackProgress = progressTracker.isEnabled();
 
         for (PDPage page : pages) {
             page.setRotation(page.getRotation() + angle);
+            if (trackProgress) {
+                progressTracker.advance();
+            }
+        }
+
+        if (trackProgress) {
+            progressTracker.complete();
         }
 
         return WebResponseUtils.pdfDocToWebResponse(

app/core/src/main/java/stirling/software/SPDF/controller/api/ScalePagesController.java

@@ -14,31 +14,32 @@ import org.apache.pdfbox.pdmodel.graphics.form.PDFormXObject;
 import org.apache.pdfbox.util.Matrix;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.general.ScalePagesRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class ScalePagesController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(value = "/scale-pages", consumes = "multipart/form-data")
+    @StandardPdfResponse
     @Operation(
             summary = "Change the size of a PDF page/document",
             description =
@@ -57,6 +58,8 @@ public class ScalePagesController {
         PDRectangle targetSize = getTargetSize(targetPDRectangle, sourceDocument);
 
         int totalPages = sourceDocument.getNumberOfPages();
+        JobProgressTracker progressTracker = jobProgressService.tracker(Math.max(1, totalPages));
+        boolean trackProgress = progressTracker.isEnabled();
         for (int i = 0; i < totalPages; i++) {
             PDPage sourcePage = sourceDocument.getPage(i);
             PDRectangle sourceSize = sourcePage.getMediaBox();
@@ -89,6 +92,10 @@ public class ScalePagesController {
 
             contentStream.restoreGraphicsState();
             contentStream.close();
+
+            if (trackProgress) {
+                progressTracker.advance();
+            }
         }
 
         ByteArrayOutputStream baos = new ByteArrayOutputStream();
@@ -96,6 +103,10 @@ public class ScalePagesController {
         outputDocument.close();
         sourceDocument.close();
 
+        if (trackProgress) {
+            progressTracker.complete();
+        }
+
         return WebResponseUtils.bytesToWebResponse(
                 baos.toByteArray(),
                 Filenames.toSimpleFileName(file.getOriginalFilename()).replaceFirst("[.][^.]+$", "")

app/core/src/main/java/stirling/software/SPDF/controller/api/SettingsController.java

@@ -5,25 +5,21 @@ import java.util.Map;
 
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
-import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestBody;
-import org.springframework.web.bind.annotation.RequestMapping;
 
 import io.swagger.v3.oas.annotations.Hidden;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
 import stirling.software.SPDF.config.EndpointConfiguration;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.SettingsApi;
 import stirling.software.common.configuration.InstallationPathConfig;
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.util.GeneralUtils;
 
-@Controller
-@Tag(name = "Settings", description = "Settings APIs")
-@RequestMapping("/api/v1/settings")
+@SettingsApi
 @RequiredArgsConstructor
 @Hidden
 public class SettingsController {

app/core/src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java

@@ -15,33 +15,34 @@ import org.apache.pdfbox.pdmodel.PDPage;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.MultiFileResponse;
 import stirling.software.SPDF.model.api.PDFWithPageNums;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
+@GeneralApi
 @Slf4j
-@Tag(name = "General", description = "General APIs")
 @RequiredArgsConstructor
 public class SplitPDFController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/split-pages")
+    @MultiFileResponse
     @Operation(
             summary = "Split a PDF file into separate documents",
             description =
@@ -79,6 +80,8 @@ public class SplitPDFController {
             // split the document
             splitDocumentsBoas = new ArrayList<>();
             int previousPageNumber = 0;
+            JobProgressTracker progressTracker = jobProgressService.tracker(pageNumbers.size() + 2);
+            boolean trackProgress = progressTracker.isEnabled();
             for (int splitPoint : pageNumbers) {
                 try (PDDocument splitDocument =
                         pdfDocumentFactory.createNewDocumentBasedOnOldDocument(document)) {
@@ -96,6 +99,10 @@ public class SplitPDFController {
                     splitDocument.save(baos);
 
                     splitDocumentsBoas.add(baos);
+
+                    if (trackProgress) {
+                        progressTracker.advance();
+                    }
                 } catch (Exception e) {
                     ExceptionUtils.logException("document splitting and saving", e);
                     throw e;
@@ -130,11 +137,18 @@ public class SplitPDFController {
                 throw e;
             }
 
+            if (trackProgress) {
+                progressTracker.advance();
+            }
+
             log.debug("Successfully created zip file with split documents: {}", zipFile.toString());
             byte[] data = Files.readAllBytes(zipFile);
             Files.deleteIfExists(zipFile);
 
             // return the Resource in the response
+            if (trackProgress) {
+                progressTracker.complete();
+            }
             return WebResponseUtils.bytesToWebResponse(
                     data, filename + ".zip", MediaType.APPLICATION_OCTET_STREAM);
 

app/core/src/main/java/stirling/software/SPDF/controller/api/SplitPdfByChaptersController.java

@@ -15,13 +15,10 @@ import org.apache.pdfbox.pdmodel.interactive.documentnavigation.outline.PDOutlin
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.AllArgsConstructor;
 import lombok.Data;
@@ -30,24 +27,27 @@ import lombok.NoArgsConstructor;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.MultiFileResponse;
 import stirling.software.SPDF.model.api.SplitPdfByChaptersRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.model.PdfMetadata;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.service.PdfMetadataService;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
+@GeneralApi
 @Slf4j
-@Tag(name = "General", description = "General APIs")
 @RequiredArgsConstructor
 public class SplitPdfByChaptersController {
 
     private final PdfMetadataService pdfMetadataService;
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     private static List<Bookmark> extractOutlineItems(
             PDDocument sourceDocument,
@@ -118,6 +118,7 @@ public class SplitPdfByChaptersController {
     }
 
     @AutoJobPostMapping(value = "/split-pdf-by-chapters", consumes = "multipart/form-data")
+    @MultiFileResponse
     @Operation(
             summary = "Split PDFs by Chapters",
             description = "Splits a PDF into chapters and returns a ZIP file.")
@@ -180,8 +181,12 @@ public class SplitPdfByChaptersController {
                         bookmark.getStartPage(),
                         bookmark.getEndPage());
             }
+            JobProgressTracker progressTracker = jobProgressService.tracker(bookmarks.size() + 1);
+            boolean trackProgress = progressTracker.isEnabled();
+
             List<ByteArrayOutputStream> splitDocumentsBoas =
-                    getSplitDocumentsBoas(sourceDocument, bookmarks, includeMetadata);
+                    getSplitDocumentsBoas(
+                            sourceDocument, bookmarks, includeMetadata, progressTracker);
 
             zipFile = createZipFile(bookmarks, splitDocumentsBoas);
 
@@ -192,6 +197,14 @@ public class SplitPdfByChaptersController {
                     Filenames.toSimpleFileName(file.getOriginalFilename())
                             .replaceFirst("[.][^.]+$", "");
             sourceDocument.close();
+
+            if (trackProgress) {
+                progressTracker.advance();
+                progressTracker.complete();
+            } else {
+                jobProgressService.updateProgress(100, null);
+            }
+
             return WebResponseUtils.bytesToWebResponse(
                     data, filename + ".zip", MediaType.APPLICATION_OCTET_STREAM);
         } finally {
@@ -267,13 +280,17 @@ public class SplitPdfByChaptersController {
     }
 
     public List<ByteArrayOutputStream> getSplitDocumentsBoas(
-            PDDocument sourceDocument, List<Bookmark> bookmarks, boolean includeMetadata)
+            PDDocument sourceDocument,
+            List<Bookmark> bookmarks,
+            boolean includeMetadata,
+            JobProgressTracker progressTracker)
             throws Exception {
         List<ByteArrayOutputStream> splitDocumentsBoas = new ArrayList<>();
         PdfMetadata metadata = null;
         if (includeMetadata) {
             metadata = pdfMetadataService.extractMetadataFromPdf(sourceDocument);
         }
+        boolean trackProgress = progressTracker.isEnabled();
         for (Bookmark bookmark : bookmarks) {
             try (PDDocument splitDocument = new PDDocument()) {
                 boolean isSinglePage = (bookmark.getStartPage() == bookmark.getEndPage());
@@ -293,6 +310,9 @@ public class SplitPdfByChaptersController {
                 splitDocument.save(baos);
 
                 splitDocumentsBoas.add(baos);
+                if (trackProgress) {
+                    progressTracker.advance();
+                }
             } catch (Exception e) {
                 ExceptionUtils.logException("document splitting and saving", e);
                 throw e;

app/core/src/main/java/stirling/software/SPDF/controller/api/SplitPdfBySectionsController.java

@@ -20,30 +20,31 @@ import org.apache.pdfbox.util.Matrix;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.MultiFileResponse;
 import stirling.software.SPDF.model.api.SplitPdfBySectionsRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class SplitPdfBySectionsController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(value = "/split-pdf-by-sections", consumes = "multipart/form-data")
+    @MultiFileResponse
     @Operation(
             summary = "Split PDF pages into smaller sections",
             description =
@@ -61,15 +62,27 @@ public class SplitPdfBySectionsController {
         int horiz = request.getHorizontalDivisions() + 1;
         int verti = request.getVerticalDivisions() + 1;
         boolean merge = Boolean.TRUE.equals(request.getMerge());
-        List<PDDocument> splitDocuments = splitPdfPages(sourceDocument, verti, horiz);
+        int totalSections = sourceDocument.getNumberOfPages() * horiz * verti;
+        JobProgressTracker progressTracker = jobProgressService.tracker(totalSections + 1);
+        boolean trackProgress = progressTracker.isEnabled();
+        List<PDDocument> splitDocuments =
+                splitPdfPages(sourceDocument, verti, horiz, progressTracker);
 
         String filename =
                 Filenames.toSimpleFileName(file.getOriginalFilename())
                         .replaceFirst("[.][^.]+$", "");
         if (merge) {
-            MergeController mergeController = new MergeController(pdfDocumentFactory);
             ByteArrayOutputStream baos = new ByteArrayOutputStream();
-            mergeController.mergeDocuments(splitDocuments).save(baos);
+            if (trackProgress) {
+                progressTracker.advance();
+            }
+            mergeDocuments(splitDocuments).save(baos);
+            for (PDDocument doc : splitDocuments) {
+                doc.close();
+            }
+            if (trackProgress) {
+                progressTracker.complete();
+            }
             return WebResponseUtils.bytesToWebResponse(baos.toByteArray(), filename + "_split.pdf");
         }
         for (PDDocument doc : splitDocuments) {
@@ -101,6 +114,10 @@ public class SplitPdfBySectionsController {
 
             zipOut.finish();
             data = Files.readAllBytes(zipFile);
+            if (trackProgress) {
+                progressTracker.advance();
+                progressTracker.complete();
+            }
             return WebResponseUtils.bytesToWebResponse(
                     data, filename + "_split.zip", MediaType.APPLICATION_OCTET_STREAM);
 
@@ -109,11 +126,28 @@ public class SplitPdfBySectionsController {
         }
     }
 
+    private PDDocument mergeDocuments(List<PDDocument> documents) throws IOException {
+        PDDocument merged = pdfDocumentFactory.createNewDocument();
+        for (PDDocument doc : documents) {
+            for (PDPage page : doc.getPages()) {
+                merged.addPage(page);
+            }
+        }
+        return merged;
+    }
+
     public List<PDDocument> splitPdfPages(
-            PDDocument document, int horizontalDivisions, int verticalDivisions)
+            PDDocument document,
+            int horizontalDivisions,
+            int verticalDivisions,
+            JobProgressTracker progressTracker)
             throws IOException {
         List<PDDocument> splitDocuments = new ArrayList<>();
 
+        int totalSections = document.getNumberOfPages() * horizontalDivisions * verticalDivisions;
+        int sectionCounter = 0;
+        boolean trackProgress = progressTracker.isEnabled();
+
         for (PDPage originalPage : document.getPages()) {
             PDRectangle originalMediaBox = originalPage.getMediaBox();
             float width = originalMediaBox.getWidth();
@@ -153,6 +187,10 @@ public class SplitPdfBySectionsController {
                     }
 
                     splitDocuments.add(subDoc);
+                    sectionCounter++;
+                    if (trackProgress) {
+                        progressTracker.advance();
+                    }
                 }
             }
         }

app/core/src/main/java/stirling/software/SPDF/controller/api/SplitPdfBySizeController.java

@@ -12,34 +12,35 @@ import org.apache.pdfbox.pdmodel.PDPage;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.MultiFileResponse;
 import stirling.software.SPDF.model.api.general.SplitPdfBySizeOrCountRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.GeneralUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
+@GeneralApi
 @Slf4j
-@Tag(name = "General", description = "General APIs")
 @RequiredArgsConstructor
 public class SplitPdfBySizeController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(value = "/split-by-size-or-count", consumes = "multipart/form-data")
+    @MultiFileResponse
     @Operation(
             summary = "Auto split PDF pages into separate documents based on size or count",
             description =
@@ -80,21 +81,28 @@ public class SplitPdfBySizeController {
                     String value = request.getSplitValue();
                     log.debug("Split type: {}, Split value: {}", type, value);
 
+                    JobProgressTracker progressTracker =
+                            jobProgressService.tracker(sourceDocument.getNumberOfPages() + 2);
+                    boolean trackProgress = progressTracker.isEnabled();
+
                     if (type == 0) {
                         log.debug("Processing split by size");
                         long maxBytes = GeneralUtils.convertSizeToBytes(value);
                         log.debug("Max bytes per document: {}", maxBytes);
-                        handleSplitBySize(sourceDocument, maxBytes, zipOut, filename);
+                        handleSplitBySize(
+                                sourceDocument, maxBytes, zipOut, filename, progressTracker);
                     } else if (type == 1) {
                         log.debug("Processing split by page count");
                         int pageCount = Integer.parseInt(value);
                         log.debug("Pages per document: {}", pageCount);
-                        handleSplitByPageCount(sourceDocument, pageCount, zipOut, filename);
+                        handleSplitByPageCount(
+                                sourceDocument, pageCount, zipOut, filename, progressTracker);
                     } else if (type == 2) {
                         log.debug("Processing split by document count");
                         int documentCount = Integer.parseInt(value);
                         log.debug("Total number of documents: {}", documentCount);
-                        handleSplitByDocCount(sourceDocument, documentCount, zipOut, filename);
+                        handleSplitByDocCount(
+                                sourceDocument, documentCount, zipOut, filename, progressTracker);
                     } else {
                         log.error("Invalid split type: {}", type);
                         throw ExceptionUtils.createIllegalArgumentException(
@@ -104,6 +112,13 @@ public class SplitPdfBySizeController {
                     }
 
                     log.debug("PDF splitting completed successfully");
+
+                    if (trackProgress) {
+                        progressTracker.advance();
+                        progressTracker.complete();
+                    } else {
+                        jobProgressService.updateProgress(100, null);
+                    }
                 } catch (Exception e) {
                     ExceptionUtils.logException("PDF document loading or processing", e);
                     throw e;
@@ -140,7 +155,11 @@ public class SplitPdfBySizeController {
     }
 
     private void handleSplitBySize(
-            PDDocument sourceDocument, long maxBytes, ZipOutputStream zipOut, String baseFilename)
+            PDDocument sourceDocument,
+            long maxBytes,
+            ZipOutputStream zipOut,
+            String baseFilename,
+            JobProgressTracker progressTracker)
             throws IOException {
         log.debug("Starting handleSplitBySize with maxBytes={}", maxBytes);
 
@@ -149,6 +168,7 @@ public class SplitPdfBySizeController {
         int fileIndex = 1;
         int totalPages = sourceDocument.getNumberOfPages();
         int pageAdded = 0;
+        boolean trackProgress = progressTracker.isEnabled();
 
         // Smart size check frequency - check more often with larger documents
         int baseCheckFrequency = 5;
@@ -253,6 +273,9 @@ public class SplitPdfBySizeController {
                     }
                 }
             }
+            if (trackProgress) {
+                progressTracker.setStepsCompleted(Math.min(totalPages, pageIndex + 1));
+            }
         }
 
         // Save final document if it has any pages
@@ -262,13 +285,20 @@ public class SplitPdfBySizeController {
                     currentDoc.getNumberOfPages(),
                     fileIndex);
             saveDocumentToZip(currentDoc, zipOut, baseFilename, fileIndex++);
+            if (trackProgress) {
+                progressTracker.setStepsCompleted(totalPages);
+            }
         }
 
         log.debug("Completed handleSplitBySize with {} document parts created", fileIndex - 1);
     }
 
     private void handleSplitByPageCount(
-            PDDocument sourceDocument, int pageCount, ZipOutputStream zipOut, String baseFilename)
+            PDDocument sourceDocument,
+            int pageCount,
+            ZipOutputStream zipOut,
+            String baseFilename,
+            JobProgressTracker progressTracker)
             throws IOException {
         log.debug("Starting handleSplitByPageCount with pageCount={}", pageCount);
         int currentPageCount = 0;
@@ -286,12 +316,17 @@ public class SplitPdfBySizeController {
         int pageIndex = 0;
         int totalPages = sourceDocument.getNumberOfPages();
         log.debug("Processing {} pages", totalPages);
+        boolean trackProgress = progressTracker.isEnabled();
 
         try {
             for (PDPage page : sourceDocument.getPages()) {
                 pageIndex++;
                 log.debug("Processing page {} of {}", pageIndex, totalPages);
 
+                if (trackProgress) {
+                    progressTracker.setStepsCompleted(pageIndex);
+                }
+
                 try {
                     log.debug("Adding page {} to current document", pageIndex);
                     currentDoc.addPage(page);
@@ -349,6 +384,9 @@ public class SplitPdfBySizeController {
                     log.error("Error saving final document part {}", fileIndex - 1, e);
                     throw e;
                 }
+                if (trackProgress) {
+                    progressTracker.setStepsCompleted(totalPages);
+                }
             } else {
                 log.debug("Final document has no pages, skipping");
             }
@@ -372,7 +410,8 @@ public class SplitPdfBySizeController {
             PDDocument sourceDocument,
             int documentCount,
             ZipOutputStream zipOut,
-            String baseFilename)
+            String baseFilename,
+            JobProgressTracker progressTracker)
             throws IOException {
         log.debug("Starting handleSplitByDocCount with documentCount={}", documentCount);
         int totalPageCount = sourceDocument.getNumberOfPages();
@@ -384,6 +423,7 @@ public class SplitPdfBySizeController {
 
         int currentPageIndex = 0;
         int fileIndex = 1;
+        boolean trackProgress = progressTracker.isEnabled();
 
         for (int i = 0; i < documentCount; i++) {
             log.debug("Creating document {} of {}", i + 1, documentCount);
@@ -409,6 +449,9 @@ public class SplitPdfBySizeController {
                     currentDoc.addPage(sourceDocument.getPage(currentPageIndex));
                     log.debug("Successfully added page {} to document {}", j + 1, i + 1);
                     currentPageIndex++;
+                    if (trackProgress) {
+                        progressTracker.setStepsCompleted(currentPageIndex);
+                    }
                 } catch (Exception e) {
                     log.error("Error adding page {} to document {}", j + 1, i + 1, e);
                     throw ExceptionUtils.createFileProcessingException("split", e);

app/core/src/main/java/stirling/software/SPDF/controller/api/ToSinglePageController.java

@@ -12,28 +12,29 @@ import org.apache.pdfbox.pdmodel.common.PDRectangle;
 import org.apache.pdfbox.pdmodel.graphics.form.PDFormXObject;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.GeneralApi;
 import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.JobProgressService;
+import stirling.software.common.service.JobProgressTracker;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/general")
-@Tag(name = "General", description = "General APIs")
+@GeneralApi
 @RequiredArgsConstructor
 public class ToSinglePageController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final JobProgressService jobProgressService;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf-to-single-page")
+    @StandardPdfResponse
     @Operation(
             summary = "Convert a multi-page PDF into a single long page PDF",
             description =
@@ -47,6 +48,10 @@ public class ToSinglePageController {
         // Load the source document
         PDDocument sourceDocument = pdfDocumentFactory.load(request);
 
+        int totalPages = Math.max(1, sourceDocument.getNumberOfPages());
+        JobProgressTracker progressTracker = jobProgressService.tracker(totalPages + 1);
+        boolean trackProgress = progressTracker.isEnabled();
+
         // Calculate total height and max width
         float totalHeight = 0;
         float maxWidth = 0;
@@ -81,6 +86,9 @@ public class ToSinglePageController {
             layerUtility.appendFormAsLayer(newPage, form, af, defaultLayerName);
             yOffset -= page.getMediaBox().getHeight();
             pageIndex++;
+            if (trackProgress) {
+                progressTracker.advance();
+            }
         }
 
         ByteArrayOutputStream baos = new ByteArrayOutputStream();
@@ -88,6 +96,10 @@ public class ToSinglePageController {
         newDocument.close();
         sourceDocument.close();
 
+        if (trackProgress) {
+            progressTracker.complete();
+        }
+
         byte[] result = baos.toByteArray();
         return WebResponseUtils.bytesToWebResponse(
                 result,

app/core/src/main/java/stirling/software/SPDF/controller/api/UIDataController.java

@@ -15,14 +15,11 @@ import org.springframework.core.io.Resource;
 import org.springframework.core.io.ResourceLoader;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.Data;
 import lombok.extern.slf4j.Slf4j;
@@ -30,6 +27,7 @@ import lombok.extern.slf4j.Slf4j;
 import stirling.software.SPDF.model.Dependency;
 import stirling.software.SPDF.model.SignatureFile;
 import stirling.software.SPDF.service.SignatureService;
+import stirling.software.common.annotations.api.UiDataApi;
 import stirling.software.common.configuration.InstallationPathConfig;
 import stirling.software.common.configuration.RuntimePathConfig;
 import stirling.software.common.model.ApplicationProperties;
@@ -38,9 +36,7 @@ import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.GeneralUtils;
 
 @Slf4j
-@RestController
-@RequestMapping("/api/v1/ui-data")
-@Tag(name = "UI Data", description = "APIs for React UI data")
+@UiDataApi
 public class UIDataController {
 
     private final ApplicationProperties applicationProperties;

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertEmlToPDF.java

@@ -8,18 +8,17 @@ import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.configuration.RuntimePathConfig;
 import stirling.software.common.model.api.converters.EmlToPdfRequest;
 import stirling.software.common.service.CustomPDFDocumentFactory;
@@ -28,9 +27,7 @@ import stirling.software.common.util.EmlToPdf;
 import stirling.software.common.util.TempFileManager;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/convert")
-@Tag(name = "Convert", description = "Convert APIs")
+@ConvertApi
 @Slf4j
 @RequiredArgsConstructor
 public class ConvertEmlToPDF {
@@ -41,6 +38,7 @@ public class ConvertEmlToPDF {
     private final CustomHtmlSanitizer customHtmlSanitizer;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/eml/pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Convert EML to PDF",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertHtmlToPDF.java

@@ -2,17 +2,16 @@ package stirling.software.SPDF.controller.api.converters;
 
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.configuration.RuntimePathConfig;
 import stirling.software.common.model.api.converters.HTMLToPdfRequest;
 import stirling.software.common.service.CustomPDFDocumentFactory;
@@ -22,9 +21,7 @@ import stirling.software.common.util.FileToPdf;
 import stirling.software.common.util.TempFileManager;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@Tag(name = "Convert", description = "Convert APIs")
-@RequestMapping("/api/v1/convert")
+@ConvertApi
 @RequiredArgsConstructor
 public class ConvertHtmlToPDF {
 
@@ -37,6 +34,7 @@ public class ConvertHtmlToPDF {
     private final CustomHtmlSanitizer customHtmlSanitizer;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/html/pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Convert an HTML or ZIP (containing HTML and CSS) to PDF",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java

@@ -19,20 +19,20 @@ import org.apache.pdfbox.rendering.ImageType;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.MultiFileResponse;
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.converters.ConvertToImageRequest;
 import stirling.software.SPDF.model.api.converters.ConvertToPdfRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.CheckProgramInstall;
 import stirling.software.common.util.ExceptionUtils;
@@ -42,16 +42,15 @@ import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/convert")
+@ConvertApi
 @Slf4j
-@Tag(name = "Convert", description = "Convert APIs")
 @RequiredArgsConstructor
 public class ConvertImgPDFController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/img")
+    @MultiFileResponse
     @Operation(
             summary = "Convert PDF to image(s)",
             description =
@@ -212,6 +211,7 @@ public class ConvertImgPDFController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/img/pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Convert images to a PDF file",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertMarkdownToPdf.java

@@ -12,17 +12,16 @@ import org.commonmark.renderer.html.AttributeProvider;
 import org.commonmark.renderer.html.HtmlRenderer;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.configuration.RuntimePathConfig;
 import stirling.software.common.model.api.GeneralFile;
 import stirling.software.common.service.CustomPDFDocumentFactory;
@@ -32,9 +31,7 @@ import stirling.software.common.util.FileToPdf;
 import stirling.software.common.util.TempFileManager;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@Tag(name = "Convert", description = "Convert APIs")
-@RequestMapping("/api/v1/convert")
+@ConvertApi
 @RequiredArgsConstructor
 public class ConvertMarkdownToPdf {
 
@@ -46,6 +43,7 @@ public class ConvertMarkdownToPdf {
     private final CustomHtmlSanitizer customHtmlSanitizer;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/markdown/pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Convert a Markdown file to PDF",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertOfficeController.java

@@ -13,17 +13,15 @@ import org.apache.commons.io.FilenameUtils;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.configuration.RuntimePathConfig;
 import stirling.software.common.model.api.GeneralFile;
 import stirling.software.common.service.CustomPDFDocumentFactory;
@@ -32,9 +30,7 @@ import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@Tag(name = "Convert", description = "Convert APIs")
-@RequestMapping("/api/v1/convert")
+@ConvertApi
 @RequiredArgsConstructor
 public class ConvertOfficeController {
 

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToHtml.java

@@ -2,20 +2,17 @@ package stirling.software.SPDF.controller.api.converters;
 
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
+import stirling.software.SPDF.config.swagger.HtmlConversionResponse;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.util.PDFToFile;
 
-@RestController
-@Tag(name = "Convert", description = "Convert APIs")
-@RequestMapping("/api/v1/convert")
+@ConvertApi
 public class ConvertPDFToHtml {
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/html")
@@ -23,6 +20,7 @@ public class ConvertPDFToHtml {
             summary = "Convert PDF to HTML",
             description =
                     "This endpoint converts a PDF file to HTML format. Input:PDF Output:HTML Type:SISO")
+    @HtmlConversionResponse
     public ResponseEntity<byte[]> processPdfToHTML(@ModelAttribute PDFFile file) throws Exception {
         MultipartFile inputFile = file.getFileInput();
         PDFToFile pdfToFile = new PDFToFile();

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToOffice.java

@@ -7,34 +7,35 @@ import org.apache.pdfbox.text.PDFTextStripper;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.PowerPointConversionResponse;
+import stirling.software.SPDF.config.swagger.TextPlainConversionResponse;
+import stirling.software.SPDF.config.swagger.WordConversionResponse;
+import stirling.software.SPDF.config.swagger.XmlConversionResponse;
 import stirling.software.SPDF.model.api.converters.PdfToPresentationRequest;
 import stirling.software.SPDF.model.api.converters.PdfToTextOrRTFRequest;
 import stirling.software.SPDF.model.api.converters.PdfToWordRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.PDFToFile;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/convert")
-@Tag(name = "Convert", description = "Convert APIs")
+@ConvertApi
 @RequiredArgsConstructor
 public class ConvertPDFToOffice {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/presentation")
+    @PowerPointConversionResponse
     @Operation(
             summary = "Convert PDF to Presentation format",
             description =
@@ -50,6 +51,7 @@ public class ConvertPDFToOffice {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/text")
+    @TextPlainConversionResponse
     @Operation(
             summary = "Convert PDF to Text or RTF format",
             description =
@@ -78,6 +80,7 @@ public class ConvertPDFToOffice {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/word")
+    @WordConversionResponse
     @Operation(
             summary = "Convert PDF to Word document",
             description =
@@ -92,6 +95,7 @@ public class ConvertPDFToOffice {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/xml")
+    @XmlConversionResponse
     @Operation(
             summary = "Convert PDF to XML",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToPDFA.java

@@ -55,30 +55,28 @@ import org.apache.xmpbox.xml.XmpSerializer;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.converters.PdfToPdfARequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/convert")
+@ConvertApi
 @Slf4j
-@Tag(name = "Convert", description = "Convert APIs")
 public class ConvertPDFToPDFA {
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/pdfa")
+    @StandardPdfResponse
     @Operation(
             summary = "Convert a PDF to a PDF/A",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertWebsiteToPDF.java

@@ -9,17 +9,16 @@ import java.util.List;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.converters.UrlToPdfRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.configuration.RuntimePathConfig;
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.service.CustomPDFDocumentFactory;
@@ -29,10 +28,8 @@ import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@Tag(name = "Convert", description = "Convert APIs")
+@ConvertApi
 @Slf4j
-@RequestMapping("/api/v1/convert")
 @RequiredArgsConstructor
 public class ConvertWebsiteToPDF {
 
@@ -41,6 +38,7 @@ public class ConvertWebsiteToPDF {
     private final ApplicationProperties applicationProperties;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/url/pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Convert a URL to a PDF",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ExtractCSVController.java

@@ -18,18 +18,17 @@ import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.CsvConversionResponse;
 import stirling.software.SPDF.model.api.PDFWithPageNums;
 import stirling.software.SPDF.pdf.FlexibleCSVWriter;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.ConvertApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 
 import technology.tabula.ObjectExtractor;
@@ -37,9 +36,7 @@ import technology.tabula.Page;
 import technology.tabula.Table;
 import technology.tabula.extractors.SpreadsheetExtractionAlgorithm;
 
-@RestController
-@RequestMapping("/api/v1/convert")
-@Tag(name = "Convert", description = "Convert APIs")
+@ConvertApi
 @Slf4j
 @RequiredArgsConstructor
 public class ExtractCSVController {
@@ -47,6 +44,7 @@ public class ExtractCSVController {
     private final CustomPDFDocumentFactory pdfDocumentFactory;
 
     @AutoJobPostMapping(value = "/pdf/csv", consumes = "multipart/form-data")
+    @CsvConversionResponse
     @Operation(
             summary = "Extracts a CSV document from a PDF",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/filters/FilterController.java

@@ -7,16 +7,14 @@ import org.apache.pdfbox.pdmodel.PDPage;
 import org.apache.pdfbox.pdmodel.common.PDRectangle;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 
+import stirling.software.SPDF.config.swagger.FilterResponse;
 import stirling.software.SPDF.model.api.PDFComparisonAndCount;
 import stirling.software.SPDF.model.api.PDFWithPageNums;
 import stirling.software.SPDF.model.api.filter.ContainsTextRequest;
@@ -24,20 +22,20 @@ import stirling.software.SPDF.model.api.filter.FileSizeRequest;
 import stirling.software.SPDF.model.api.filter.PageRotationRequest;
 import stirling.software.SPDF.model.api.filter.PageSizeRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.FilterApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.PdfUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/filter")
-@Tag(name = "Filter", description = "Filter APIs")
+@FilterApi
 @RequiredArgsConstructor
 public class FilterController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/filter-contains-text")
+    @FilterResponse
     @Operation(
             summary = "Checks if a PDF contains set text, returns true if does",
             description = "Input:PDF Output:Boolean Type:SISO")
@@ -56,6 +54,7 @@ public class FilterController {
 
     // TODO
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/filter-contains-image")
+    @FilterResponse
     @Operation(
             summary = "Checks if a PDF contains an image",
             description = "Input:PDF Output:Boolean Type:SISO")
@@ -72,6 +71,7 @@ public class FilterController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/filter-page-count")
+    @FilterResponse
     @Operation(
             summary = "Checks if a PDF is greater, less or equal to a setPageCount",
             description = "Input:PDF Output:Boolean Type:SISO")
@@ -105,6 +105,7 @@ public class FilterController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/filter-page-size")
+    @FilterResponse
     @Operation(
             summary = "Checks if a PDF is of a certain size",
             description = "Input:PDF Output:Boolean Type:SISO")
@@ -148,6 +149,7 @@ public class FilterController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/filter-file-size")
+    @FilterResponse
     @Operation(
             summary = "Checks if a PDF is a set file size",
             description = "Input:PDF Output:Boolean Type:SISO")
@@ -181,6 +183,7 @@ public class FilterController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/filter-page-rotation")
+    @FilterResponse
     @Operation(
             summary = "Checks if a PDF is of a certain rotation",
             description = "Input:PDF Output:Boolean Type:SISO")

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AttachmentController.java

@@ -6,28 +6,25 @@ import java.util.List;
 import org.apache.pdfbox.pdmodel.PDDocument;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.misc.AddAttachmentRequest;
 import stirling.software.SPDF.service.AttachmentServiceInterface;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.MiscApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.WebResponseUtils;
 
+@MiscApi
 @Slf4j
-@RestController
 @RequiredArgsConstructor
-@RequestMapping("/api/v1/misc")
-@Tag(name = "Misc", description = "Miscellaneous APIs")
 public class AttachmentController {
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
@@ -35,6 +32,7 @@ public class AttachmentController {
     private final AttachmentServiceInterface pdfAttachmentService;
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/add-attachments")
+    @StandardPdfResponse
     @Operation(
             summary = "Add attachments to PDF",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AutoRenameController.java

@@ -10,26 +10,22 @@ import org.apache.pdfbox.text.PDFTextStripper;
 import org.apache.pdfbox.text.TextPosition;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.SPDF.model.api.misc.ExtractHeaderRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.MiscApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/misc")
+@MiscApi
 @Slf4j
-@Tag(name = "Misc", description = "Miscellaneous APIs")
 @RequiredArgsConstructor
 public class AutoRenameController {
 

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AutoSplitPdfController.java

@@ -19,8 +19,6 @@ import org.apache.pdfbox.rendering.PDFRenderer;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import com.google.zxing.*;
@@ -28,20 +26,19 @@ import com.google.zxing.common.HybridBinarizer;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.SPDF.config.swagger.MultiFileResponse;
 import stirling.software.SPDF.model.api.misc.AutoSplitPdfRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.MiscApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/misc")
+@MiscApi
 @Slf4j
-@Tag(name = "Misc", description = "Miscellaneous APIs")
 @RequiredArgsConstructor
 public class AutoSplitPdfController {
 
@@ -103,6 +100,7 @@ public class AutoSplitPdfController {
     }
 
     @AutoJobPostMapping(value = "/auto-split-pdf", consumes = "multipart/form-data")
+    @MultiFileResponse
     @Operation(
             summary = "Auto split PDF pages into separate documents",
             description =

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java

@@ -17,27 +17,23 @@ import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.SPDF.model.api.misc.RemoveBlankPagesRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.MiscApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.PdfUtils;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/misc")
+@MiscApi
 @Slf4j
-@Tag(name = "Misc", description = "Miscellaneous APIs")
 @RequiredArgsConstructor
 public class BlankPageController {
 

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/CompressController.java

@@ -34,13 +34,10 @@ import org.apache.pdfbox.pdmodel.graphics.form.PDFormXObject;
 import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.ModelAttribute;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 import io.github.pixee.security.Filenames;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
 
 import lombok.AllArgsConstructor;
 import lombok.Data;
@@ -50,8 +47,10 @@ import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.SPDF.config.EndpointConfiguration;
+import stirling.software.SPDF.config.swagger.StandardPdfResponse;
 import stirling.software.SPDF.model.api.misc.OptimizePdfRequest;
 import stirling.software.common.annotations.AutoJobPostMapping;
+import stirling.software.common.annotations.api.MiscApi;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.GeneralUtils;
@@ -59,10 +58,8 @@ import stirling.software.common.util.ProcessExecutor;
 import stirling.software.common.util.ProcessExecutor.ProcessExecutorResult;
 import stirling.software.common.util.WebResponseUtils;
 
-@RestController
-@RequestMapping("/api/v1/misc")
+@MiscApi
 @Slf4j
-@Tag(name = "Misc", description = "Miscellaneous APIs")
 @RequiredArgsConstructor
 public class CompressController {
 
@@ -659,6 +656,7 @@ public class CompressController {
     }
 
     @AutoJobPostMapping(consumes = "multipart/form-data", value = "/compress-pdf")
+    @StandardPdfResponse
     @Operation(
             summary = "Optimize PDF file",
             description =