Paths to be app paths

Missed import
Merge remote-tracking branch 'origin/V2' into codex/analyze-frontend-tools-for-backend-dependency
2025-10-31 17:21:15 +00:00 · 2025-10-31 17:12:34 +00:00 · 2025-10-31 17:11:32 +00:00 · 2025-10-31 14:38:03 +00:00 · 2025-10-29 11:58:04 +00:00 · 2025-10-29 09:56:16 +00:00
853 changed files with 26001 additions and 4941 deletions
@@ -31,10 +31,15 @@ jobs:
      project: ${{ steps.changes.outputs.project }}
      openapi: ${{ steps.changes.outputs.openapi }}
    steps:
-      - uses: actions/checkout@v4.3.0
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

      - name: Check for file changes
-        uses: dorny/paths-filter@v3.0.2
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
        id: changes
        with:
          filters: .github/config/.files.yaml
@@ -51,19 +56,19 @@ jobs:
        spring-security: [true, false]
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
        with:
          egress-policy: audit
      - name: Checkout repository
-        uses: actions/checkout@v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

      - name: Set up JDK ${{ matrix.jdk-version }}
-        uses: actions/setup-java@v4.7.1
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
        with:
          java-version: ${{ matrix.jdk-version }}
          distribution: "temurin"
      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4.4.2
+        uses: gradle/actions/setup-gradle@4d9f0ba0025fe599b4ebab900eb7f3a1d93ef4c2 # v5.0.0
        with:
          gradle-version: 8.14
      - name: Build with Gradle and spring security ${{ matrix.spring-security }}
@@ -89,7 +94,7 @@ jobs:
          done
      - name: Upload Test Reports
        if: always()
-        uses: actions/upload-artifact@v4.6.2
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: test-reports-jdk-${{ matrix.jdk-version }}-spring-security-${{ matrix.spring-security }}
          path: |
@@ -106,26 +111,26 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@v2.13.0
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
        with:
          egress-policy: audit

      - name: Checkout repository
-        uses: actions/checkout@v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

      - name: Set up JDK 17
-        uses: actions/setup-java@v4.7.1
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
        with:
          java-version: "17"
          distribution: "temurin"
-      - uses: gradle/actions/setup-gradle@v4.4.2
+      - uses: gradle/actions/setup-gradle@4d9f0ba0025fe599b4ebab900eb7f3a1d93ef4c2 # v5.0.0
      - name: Generate OpenAPI documentation
        run: ./gradlew :stirling-pdf:generateOpenApiDocs
        env:
          DISABLE_ADDITIONAL_FEATURES: true
      
      - name: Upload OpenAPI Documentation
-        uses: actions/upload-artifact@v4.6.2
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: openapi-docs
          path: ./SwaggerDoc.json
@@ -134,19 +139,21 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@v2.12.2
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
        with:
          egress-policy: audit
      - name: Checkout repository
-        uses: actions/checkout@v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
      - name: Set up Node.js
-        uses: actions/setup-node@v4.1.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
        with:
-          node-version: '20'
+          node-version: '22'
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json
      - name: Install frontend dependencies
        run: cd frontend && npm ci
+      - name: Type-check frontend
+        run: cd frontend && npm run prebuild && npm run typecheck:all
      - name: Lint frontend
        run: cd frontend && npm run lint
      - name: Build frontend
@@ -154,7 +161,7 @@ jobs:
      - name: Run frontend tests
        run: cd frontend && npm run test -- --run
      - name: Upload frontend build artifacts
-        uses: actions/upload-artifact@v4.6.2
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: frontend-build
          path: frontend/dist/
@@ -166,13 +173,13 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
        with:
          egress-policy: audit
      - name: Checkout repository
-        uses: actions/checkout@v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
      - name: Set up JDK 17
-        uses: actions/setup-java@v4.7.1
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
        with:
          java-version: "17"
          distribution: "temurin"
@@ -180,7 +187,7 @@ jobs:
        run: ./gradlew clean checkLicense
      - name: FAILED - check the licenses for compatibility
        if: failure()
-        uses: actions/upload-artifact@v4.6.2
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: dependencies-without-allowed-license.json
          path: build/reports/dependency-license/dependencies-without-allowed-license.json
@@ -207,15 +214,15 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
        with:
          egress-policy: audit

      - name: Checkout Repository
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

      - name: Set up Java 17
-        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
        with:
          java-version: "17"
          distribution: "temurin"
@@ -225,11 +232,11 @@ jobs:

      - name: Install Docker Compose
        run: |
-          sudo curl -SL "https://github.com/docker/compose/releases/download/v2.37.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+          sudo curl -SL "https://github.com/docker/compose/releases/download/v2.39.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
          sudo chmod +x /usr/local/bin/docker-compose

      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
        with:
          python-version: "3.12"
          cache: 'pip' # caching pip dependencies
@@ -256,21 +263,21 @@ jobs:
        docker-rev: ["Dockerfile", "Dockerfile.ultra-lite", "Dockerfile.fat"]
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
        with:
          egress-policy: audit

      - name: Checkout Repository
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

      - name: Set up JDK 17
-        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
        with:
          java-version: "17"
          distribution: "temurin"

      - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2
+        uses: gradle/actions/setup-gradle@4d9f0ba0025fe599b4ebab900eb7f3a1d93ef4c2 # v5.0.0
        with:
          gradle-version: 8.14

@@ -1,104 +0,0 @@
-# Frontend TODO: Revocation Status Migration
-
-## Background
-The backend has removed the deprecated `notRevoked` boolean field in favor of `revocationStatus` string field.
-
-**revocationStatus values**:
- `"not-checked"` - revocation checking was disabled
- `"good"` - certificate was checked and is not revoked
- `"revoked"` - certificate is revoked
- `"soft-fail"` - revocation status couldn't be determined (network error, etc.)
- `"unknown"` - other failure scenarios
-
-## Files That Need Changes
-
-### 1. `/frontend/src/hooks/tools/validateSignature/utils/signatureUtils.ts`
-
-Add mappings for new backend fields in `normalizeBackendResult()`:
-```typescript
-export const normalizeBackendResult = (
-  item: SignatureValidationBackendResult,
-  stirlingFile: StirlingFile,
-  index: number
-): SignatureValidationSignature => ({
-  id: `${stirlingFile.fileId}-${index}`,
-  valid: Boolean(item.valid),
-  chainValid: Boolean(item.chainValid),
-  trustValid: Boolean(item.trustValid),
-  chainValidationError: item.chainValidationError ?? null,  // ADD THIS
-  certPathLength: item.certPathLength ?? null,              // ADD THIS
-  notExpired: Boolean(item.notExpired),
-  revocationChecked: item.revocationChecked ?? null,        // ADD THIS
-  revocationStatus: item.revocationStatus ?? null,          // ADD THIS
-  validationTimeSource: item.validationTimeSource ?? null,  // ADD THIS
-  signerName: coerceString(item.signerName),
-  // ... rest of fields
-})
-```
-
-### 2. `/frontend/src/hooks/tools/validateSignature/utils/signatureStatus.ts`
-
-**Current code** (lines 42-43):
-```typescript
-// Use new revocationStatus field if available, fallback to notRevoked for backward compatibility
-const revStatus = signature.revocationStatus || (signature.notRevoked ? 'good' : 'unknown');
-```
-
-**Change to**:
-```typescript
-const revStatus = signature.revocationStatus || 'unknown';
-```
-
-### 3. `/frontend/src/hooks/tools/validateSignature/utils/signatureCsv.ts`
-
-**Current code** (lines 12, 42):
-```typescript
-'notRevoked',  // line 12 in CSV header
-booleanToString(signature.notRevoked),  // line 42 in data row
-```
-
-**Recommended change** - replace with detailed status:
-```typescript
-// Header:
-'revocationStatus',
-
-// Data:
-signature.revocationStatus || 'unknown',
-```
-
-### 4. `/frontend/src/hooks/tools/validateSignature/utils/reportStatus.ts`
-
-**Current code** (line 24):
-```typescript
-(sig) => sig.valid && sig.chainValid && sig.trustValid && sig.notExpired && sig.notRevoked
-```
-
-**Change to**:
-```typescript
-(sig) => sig.valid && sig.chainValid && sig.trustValid && sig.notExpired && sig.revocationStatus === 'good'
-```
-
-### 5. `/frontend/src/components/tools/validateSignature/ValidateSignatureResults.tsx`
-
-**Current code** (line 33):
-```typescript
-signature.notRevoked;
-```
-
-**Change to**:
-```typescript
-signature.revocationStatus === 'good'
-```
-
-## Migration Pattern
-
-**For boolean contexts** (if statements, filters):
-```typescript
-// Old: signature.notRevoked
-// New: signature.revocationStatus === 'good'
-```
-
-**For display/logging**:
-```typescript
-signature.revocationStatus  // "good" | "revoked" | "soft-fail" | "not-checked" | "unknown"
-```
@@ -115,46 +115,46 @@ Stirling-PDF currently supports 40 languages!

 | Language                                     | Progress                               |
 | -------------------------------------------- | -------------------------------------- |
-| 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)   |
+| Arabic (العربية) (ar_AR)                        | ![83%](https://geps.dev/progress/83)   |
+| Azerbaijani (Azərbaycan Dili) (az_AZ)        | ![32%](https://geps.dev/progress/32)   |
+| Basque (Euskara) (eu_ES)                     | ![18%](https://geps.dev/progress/18)   |
+| Bulgarian (Български) (bg_BG)                | ![35%](https://geps.dev/progress/35)   |
+| Catalan (Català) (ca_CA)                     | ![34%](https://geps.dev/progress/34)   |
+| Croatian (Hrvatski) (hr_HR)                  | ![31%](https://geps.dev/progress/31)   |
+| Czech (Česky) (cs_CZ)                        | ![34%](https://geps.dev/progress/34)   |
+| Danish (Dansk) (da_DK)                       | ![30%](https://geps.dev/progress/30)   |
+| Dutch (Nederlands) (nl_NL)                   | ![30%](https://geps.dev/progress/30)   |
 | 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)                    | ![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)   |
+| French (Français) (fr_FR)                    | ![82%](https://geps.dev/progress/82)   |
+| German (Deutsch) (de_DE)                     | ![84%](https://geps.dev/progress/84)   |
+| Greek (Ελληνικά) (el_GR)                     | ![34%](https://geps.dev/progress/34)   |
+| Hindi (हिंदी) (hi_IN)                          | ![34%](https://geps.dev/progress/34)   |
+| Hungarian (Magyar) (hu_HU)                   | ![38%](https://geps.dev/progress/38)   |
+| Indonesian (Bahasa Indonesia) (id_ID)        | ![31%](https://geps.dev/progress/31)   |
+| Irish (Gaeilge) (ga_IE)                      | ![34%](https://geps.dev/progress/34)   |
+| Italian (Italiano) (it_IT)                   | ![84%](https://geps.dev/progress/84)   |
+| Japanese (日本語) (ja_JP)                    | ![62%](https://geps.dev/progress/62)   |
+| Korean (한국어) (ko_KR)                      | ![34%](https://geps.dev/progress/34)   |
+| Norwegian (Norsk) (no_NB)                    | ![32%](https://geps.dev/progress/32)   |
+| Persian (فارسی) (fa_IR)                      | ![34%](https://geps.dev/progress/34)   |
+| Polish (Polski) (pl_PL)                      | ![36%](https://geps.dev/progress/36)   |
+| Portuguese (Português) (pt_PT)               | ![34%](https://geps.dev/progress/34)   |
+| Portuguese Brazilian (Português) (pt_BR)     | ![83%](https://geps.dev/progress/83)   |
+| Romanian (Română) (ro_RO)                    | ![28%](https://geps.dev/progress/28)   |
+| Russian (Русский) (ru_RU)                    | ![83%](https://geps.dev/progress/83)   |
+| Serbian Latin alphabet (Srpski) (sr_LATN_RS) | ![37%](https://geps.dev/progress/37)   |
+| Simplified Chinese (简体中文) (zh_CN)         | ![85%](https://geps.dev/progress/85)   |
+| Slovakian (Slovensky) (sk_SK)                | ![26%](https://geps.dev/progress/26)   |
+| Slovenian (Slovenščina) (sl_SI)              | ![36%](https://geps.dev/progress/36)   |
+| Spanish (Español) (es_ES)                    | ![84%](https://geps.dev/progress/84)   |
+| Swedish (Svenska) (sv_SE)                    | ![33%](https://geps.dev/progress/33)   |
+| Thai (ไทย) (th_TH)                           | ![31%](https://geps.dev/progress/31)   |
 | Tibetan (བོད་ཡིག་) (bo_CN)                     | ![65%](https://geps.dev/progress/65) |
-| 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)   |
+| Traditional Chinese (繁體中文) (zh_TW)        | ![38%](https://geps.dev/progress/38)   |
+| Turkish (Türkçe) (tr_TR)                     | ![37%](https://geps.dev/progress/37)   |
+| Ukrainian (Українська) (uk_UA)               | ![36%](https://geps.dev/progress/36)   |
+| Vietnamese (Tiếng Việt) (vi_VN)              | ![28%](https://geps.dev/progress/28)   |
 | Malayalam (മലയാളം) (ml_IN)              | ![73%](https://geps.dev/progress/73)   |

 ## Stirling PDF Enterprise
@@ -74,8 +74,7 @@ public class AppConfig {

    @Bean(name = "appName")
    public String appName() {
-        String homeTitle = applicationProperties.getUi().getAppName();
-        return (homeTitle != null) ? homeTitle : "Stirling PDF";
+        return "Stirling PDF";
    }

    @Bean(name = "appVersion")
@@ -93,9 +92,7 @@ public class AppConfig {

    @Bean(name = "homeText")
    public String homeText() {
-        return (applicationProperties.getUi().getHomeDescription() != null)
-                ? applicationProperties.getUi().getHomeDescription()
-                : "null";
+        return "null";
    }

    @Bean(name = "languages")
@@ -110,11 +107,8 @@ public class AppConfig {

    @Bean(name = "navBarText")
    public String navBarText() {
-        String defaultNavBar =
-                applicationProperties.getUi().getAppNameNavbar() != null
-                        ? applicationProperties.getUi().getAppNameNavbar()
-                        : applicationProperties.getUi().getAppName();
-        return (defaultNavBar != null) ? defaultNavBar : "Stirling PDF";
+        String navBar = applicationProperties.getUi().getAppNameNavbar();
+        return (navBar != null) ? navBar : "Stirling PDF";
    }

    @Bean(name = "enableAlphaFunctionality")
@@ -307,7 +307,6 @@ public class ApplicationProperties {
            private boolean enableKeyRotation = false;
            private boolean enableKeyCleanup = true;
            private int keyRetentionDays = 7;
-            private boolean secureCookie;
        }

        @Data
@@ -356,6 +355,8 @@ public class ApplicationProperties {
        private String tessdataDir;
        private Boolean enableAlphaFunctionality;
        private Boolean enableAnalytics;
+        private Boolean enablePosthog;
+        private Boolean enableScarf;
        private Datasource datasource;
        private Boolean disableSanitize;
        private int maxDPI;
@@ -364,10 +365,23 @@ public class ApplicationProperties {
        private CustomPaths customPaths = new CustomPaths();
        private String fileUploadLimit;
        private TempFileManagement tempFileManagement = new TempFileManagement();
+        private List<String> corsAllowedOrigins = new ArrayList<>();

        public boolean isAnalyticsEnabled() {
            return this.getEnableAnalytics() != null && this.getEnableAnalytics();
        }
+
+        public boolean isPosthogEnabled() {
+            // Treat null as enabled when analytics is enabled
+            return this.isAnalyticsEnabled()
+                    && (this.getEnablePosthog() == null || this.getEnablePosthog());
+        }
+
+        public boolean isScarfEnabled() {
+            // Treat null as enabled when analytics is enabled
+            return this.isAnalyticsEnabled()
+                    && (this.getEnableScarf() == null || this.getEnableScarf());
+        }
    }

    @Data
@@ -476,21 +490,9 @@ public class ApplicationProperties {

    @Data
    public static class Ui {
-        private String appName;
-        private String homeDescription;
        private String appNameNavbar;
        private List<String> languages;

-        public String getAppName() {
-            return appName != null && appName.trim().length() > 0 ? appName : null;
-        }
-
-        public String getHomeDescription() {
-            return homeDescription != null && homeDescription.trim().length() > 0
-                    ? homeDescription
-                    : null;
-        }
-
        public String getAppNameNavbar() {
            return appNameNavbar != null && appNameNavbar.trim().length() > 0
                    ? appNameNavbar
@@ -546,6 +548,7 @@ public class ApplicationProperties {
    @Data
    public static class Mail {
        private boolean enabled;
+        private boolean enableInvites = false;
        private String host;
        private int port;
        private String username;
@@ -56,7 +56,7 @@ public class PostHogService {
    }

    private void captureSystemInfo() {
-        if (!applicationProperties.getSystem().isAnalyticsEnabled()) {
+        if (!applicationProperties.getSystem().isPosthogEnabled()) {
            return;
        }
        try {
@@ -67,7 +67,7 @@ public class PostHogService {
    }

    public void captureEvent(String eventName, Map<String, Object> properties) {
-        if (!applicationProperties.getSystem().isAnalyticsEnabled()) {
+        if (!applicationProperties.getSystem().isPosthogEnabled()) {
            return;
        }

@@ -325,13 +325,16 @@ public class PostHogService {
                properties,
                "system_enableAnalytics",
                applicationProperties.getSystem().isAnalyticsEnabled());
-
-        // Capture UI properties
-        addIfNotEmpty(properties, "ui_appName", applicationProperties.getUi().getAppName());
        addIfNotEmpty(
                properties,
-                "ui_homeDescription",
-                applicationProperties.getUi().getHomeDescription());
+                "system_enablePosthog",
+                applicationProperties.getSystem().isPosthogEnabled());
+        addIfNotEmpty(
+                properties,
+                "system_enableScarf",
+                applicationProperties.getSystem().isScarfEnabled());
+
+        // Capture UI properties
        addIfNotEmpty(
                properties, "ui_appNameNavbar", applicationProperties.getUi().getAppNameNavbar());

@@ -6,4 +6,6 @@ public interface UserServiceInterface {
    String getCurrentUsername();

    long getTotalUsersCount();
+
+    boolean isCurrentUserAdmin();
 }
@@ -0,0 +1,29 @@
+package stirling.software.common.util;
+
+import java.util.List;
+import java.util.concurrent.atomic.AtomicReference;
+
+import org.springframework.boot.ApplicationArguments;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.stereotype.Component;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Captures application command-line arguments at startup so they can be reused for restart
+ * operations. This allows the application to restart with the same configuration.
+ */
+@Slf4j
+@Component
+public class AppArgsCapture implements ApplicationRunner {
+
+    public static final AtomicReference<List<String>> APP_ARGS = new AtomicReference<>(List.of());
+
+    @Override
+    public void run(ApplicationArguments args) {
+        APP_ARGS.set(List.of(args.getSourceArgs()));
+        log.debug(
+                "Captured {} application arguments for restart capability",
+                args.getSourceArgs().length);
+    }
+}
@@ -0,0 +1,84 @@
+package stirling.software.common.util;
+
+import java.io.File;
+import java.net.URISyntaxException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+import lombok.extern.slf4j.Slf4j;
+
+/** Utility class to locate JAR files at runtime for restart operations */
+@Slf4j
+public class JarPathUtil {
+
+    /**
+     * Gets the path to the currently running JAR file
+     *
+     * @return Path to the current JAR, or null if not running from a JAR
+     */
+    public static Path currentJar() {
+        try {
+            Path jar =
+                    Paths.get(
+                                    JarPathUtil.class
+                                            .getProtectionDomain()
+                                            .getCodeSource()
+                                            .getLocation()
+                                            .toURI())
+                            .toAbsolutePath();
+
+            // Check if we're actually running from a JAR (not from IDE/classes directory)
+            if (jar.toString().endsWith(".jar")) {
+                log.debug("Current JAR located at: {}", jar);
+                return jar;
+            } else {
+                log.warn("Not running from JAR, current location: {}", jar);
+                return null;
+            }
+        } catch (URISyntaxException e) {
+            log.error("Failed to determine current JAR location", e);
+            return null;
+        }
+    }
+
+    /**
+     * Gets the path to the restart-helper.jar file Expected to be in the same directory as the main
+     * JAR
+     *
+     * @return Path to restart-helper.jar, or null if not found
+     */
+    public static Path restartHelperJar() {
+        Path appJar = currentJar();
+        if (appJar == null) {
+            return null;
+        }
+
+        Path helperJar = appJar.getParent().resolve("restart-helper.jar");
+
+        if (Files.isRegularFile(helperJar)) {
+            log.debug("Restart helper JAR located at: {}", helperJar);
+            return helperJar;
+        } else {
+            log.warn("Restart helper JAR not found at: {}", helperJar);
+            return null;
+        }
+    }
+
+    /**
+     * Gets the java binary path for the current JVM
+     *
+     * @return Path to java executable
+     */
+    public static String javaExecutable() {
+        String javaHome = System.getProperty("java.home");
+        String javaBin = javaHome + File.separator + "bin" + File.separator + "java";
+
+        // On Windows, add .exe extension
+        if (System.getProperty("os.name").toLowerCase().contains("win")) {
+            javaBin += ".exe";
+        }
+
+        return javaBin;
+    }
+}
@@ -112,19 +112,11 @@ class ApplicationPropertiesLogicTest {
    @Test
    void ui_getters_return_null_for_blank() {
        ApplicationProperties.Ui ui = new ApplicationProperties.Ui();
-        ui.setAppName("   ");
-        ui.setHomeDescription("");
        ui.setAppNameNavbar(null);

-        assertNull(ui.getAppName());
-        assertNull(ui.getHomeDescription());
        assertNull(ui.getAppNameNavbar());

-        ui.setAppName("Stirling-PDF");
-        ui.setHomeDescription("Home");
        ui.setAppNameNavbar("Nav");
-        assertEquals("Stirling-PDF", ui.getAppName());
-        assertEquals("Home", ui.getHomeDescription());
        assertEquals("Nav", ui.getAppNameNavbar());
    }

@@ -1,22 +1,49 @@
 package stirling.software.SPDF.config;

 import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.CorsRegistry;
 import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

 import lombok.RequiredArgsConstructor;

+import stirling.software.common.model.ApplicationProperties;
+
@Configuration
@RequiredArgsConstructor
 public class WebMvcConfig implements WebMvcConfigurer {

    private final EndpointInterceptor endpointInterceptor;
+    private final ApplicationProperties applicationProperties;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(endpointInterceptor);
    }

+    @Override
+    public void addCorsMappings(CorsRegistry registry) {
+        // Only configure CORS if allowed origins are specified
+        if (applicationProperties.getSystem() != null
+                && applicationProperties.getSystem().getCorsAllowedOrigins() != null
+                && !applicationProperties.getSystem().getCorsAllowedOrigins().isEmpty()) {
+
+            String[] allowedOrigins =
+                    applicationProperties
+                            .getSystem()
+                            .getCorsAllowedOrigins()
+                            .toArray(new String[0]);
+
+            registry.addMapping("/**")
+                    .allowedOrigins(allowedOrigins)
+                    .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH")
+                    .allowedHeaders("*")
+                    .allowCredentials(true)
+                    .maxAge(3600);
+        }
+        // If no origins are configured, CORS is not enabled (secure by default)
+    }
+
    // @Override
    // public void addResourceHandlers(ResourceHandlerRegistry registry) {
    //     // Handler for external static resources - DISABLED in backend-only mode
@@ -1,12 +1,15 @@
 package stirling.software.SPDF.controller.api;

 import java.io.IOException;
+import java.util.HashMap;
 import java.util.Map;

 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestParam;

 import io.swagger.v3.oas.annotations.Hidden;

@@ -29,7 +32,7 @@ public class SettingsController {

    @AutoJobPostMapping("/update-enable-analytics")
    @Hidden
-    public ResponseEntity<String> updateApiKey(@RequestBody Boolean enabled) throws IOException {
+    public ResponseEntity<String> updateApiKey(@RequestParam Boolean enabled) throws IOException {
        if (applicationProperties.getSystem().getEnableAnalytics() != null) {
            return ResponseEntity.status(HttpStatus.ALREADY_REPORTED)
                    .body(
@@ -46,4 +49,392 @@ public class SettingsController {
    public ResponseEntity<Map<String, Boolean>> getDisabledEndpoints() {
        return ResponseEntity.ok(endpointConfiguration.getEndpointStatuses());
    }
+
+    // ========== GENERAL SETTINGS ==========
+
+    @GetMapping("/admin/settings/general")
+    @Hidden
+    public ResponseEntity<Map<String, Object>> getGeneralSettings() {
+        Map<String, Object> settings = new HashMap<>();
+        settings.put("ui", applicationProperties.getUi());
+        settings.put(
+                "system",
+                Map.of(
+                        "defaultLocale", applicationProperties.getSystem().getDefaultLocale(),
+                        "showUpdate", applicationProperties.getSystem().isShowUpdate(),
+                        "showUpdateOnlyAdmin",
+                                applicationProperties.getSystem().getShowUpdateOnlyAdmin(),
+                        "customHTMLFiles", applicationProperties.getSystem().isCustomHTMLFiles(),
+                        "fileUploadLimit", applicationProperties.getSystem().getFileUploadLimit()));
+        return ResponseEntity.ok(settings);
+    }
+
+    @PostMapping("/admin/settings/general")
+    @Hidden
+    public ResponseEntity<String> updateGeneralSettings(@RequestBody Map<String, Object> settings)
+            throws IOException {
+        // Update UI settings
+        if (settings.containsKey("ui")) {
+            Map<String, String> ui = (Map<String, String>) settings.get("ui");
+            if (ui.containsKey("appNameNavbar")) {
+                GeneralUtils.saveKeyToSettings("ui.appNameNavbar", ui.get("appNameNavbar"));
+                applicationProperties.getUi().setAppNameNavbar(ui.get("appNameNavbar"));
+            }
+        }
+
+        // Update System settings
+        if (settings.containsKey("system")) {
+            Map<String, Object> system = (Map<String, Object>) settings.get("system");
+            if (system.containsKey("defaultLocale")) {
+                GeneralUtils.saveKeyToSettings("system.defaultLocale", system.get("defaultLocale"));
+                applicationProperties
+                        .getSystem()
+                        .setDefaultLocale((String) system.get("defaultLocale"));
+            }
+            if (system.containsKey("showUpdate")) {
+                GeneralUtils.saveKeyToSettings("system.showUpdate", system.get("showUpdate"));
+                applicationProperties.getSystem().setShowUpdate((Boolean) system.get("showUpdate"));
+            }
+            if (system.containsKey("showUpdateOnlyAdmin")) {
+                GeneralUtils.saveKeyToSettings(
+                        "system.showUpdateOnlyAdmin", system.get("showUpdateOnlyAdmin"));
+                applicationProperties
+                        .getSystem()
+                        .setShowUpdateOnlyAdmin((Boolean) system.get("showUpdateOnlyAdmin"));
+            }
+            if (system.containsKey("fileUploadLimit")) {
+                GeneralUtils.saveKeyToSettings(
+                        "system.fileUploadLimit", system.get("fileUploadLimit"));
+                applicationProperties
+                        .getSystem()
+                        .setFileUploadLimit((String) system.get("fileUploadLimit"));
+            }
+        }
+
+        return ResponseEntity.ok(
+                "General settings updated. Restart required for changes to take effect.");
+    }
+
+    // ========== SECURITY SETTINGS ==========
+
+    @GetMapping("/admin/settings/security")
+    @Hidden
+    public ResponseEntity<Map<String, Object>> getSecuritySettings() {
+        Map<String, Object> settings = new HashMap<>();
+        ApplicationProperties.Security security = applicationProperties.getSecurity();
+
+        settings.put("enableLogin", security.getEnableLogin());
+        settings.put("csrfDisabled", security.getCsrfDisabled());
+        settings.put("loginMethod", security.getLoginMethod());
+        settings.put("loginAttemptCount", security.getLoginAttemptCount());
+        settings.put("loginResetTimeMinutes", security.getLoginResetTimeMinutes());
+        settings.put(
+                "initialLogin",
+                Map.of(
+                        "username",
+                        security.getInitialLogin().getUsername() != null
+                                ? security.getInitialLogin().getUsername()
+                                : ""));
+
+        // JWT settings
+        ApplicationProperties.Security.Jwt jwt = security.getJwt();
+        settings.put(
+                "jwt",
+                Map.of(
+                        "enableKeystore", jwt.isEnableKeystore(),
+                        "enableKeyRotation", jwt.isEnableKeyRotation(),
+                        "enableKeyCleanup", jwt.isEnableKeyCleanup(),
+                        "keyRetentionDays", jwt.getKeyRetentionDays()));
+
+        return ResponseEntity.ok(settings);
+    }
+
+    @PostMapping("/admin/settings/security")
+    @Hidden
+    public ResponseEntity<String> updateSecuritySettings(@RequestBody Map<String, Object> settings)
+            throws IOException {
+        if (settings.containsKey("enableLogin")) {
+            GeneralUtils.saveKeyToSettings("security.enableLogin", settings.get("enableLogin"));
+            applicationProperties
+                    .getSecurity()
+                    .setEnableLogin((Boolean) settings.get("enableLogin"));
+        }
+        if (settings.containsKey("csrfDisabled")) {
+            GeneralUtils.saveKeyToSettings("security.csrfDisabled", settings.get("csrfDisabled"));
+            applicationProperties
+                    .getSecurity()
+                    .setCsrfDisabled((Boolean) settings.get("csrfDisabled"));
+        }
+        if (settings.containsKey("loginMethod")) {
+            GeneralUtils.saveKeyToSettings("security.loginMethod", settings.get("loginMethod"));
+            applicationProperties
+                    .getSecurity()
+                    .setLoginMethod((String) settings.get("loginMethod"));
+        }
+        if (settings.containsKey("loginAttemptCount")) {
+            GeneralUtils.saveKeyToSettings(
+                    "security.loginAttemptCount", settings.get("loginAttemptCount"));
+            applicationProperties
+                    .getSecurity()
+                    .setLoginAttemptCount((Integer) settings.get("loginAttemptCount"));
+        }
+        if (settings.containsKey("loginResetTimeMinutes")) {
+            GeneralUtils.saveKeyToSettings(
+                    "security.loginResetTimeMinutes", settings.get("loginResetTimeMinutes"));
+            applicationProperties
+                    .getSecurity()
+                    .setLoginResetTimeMinutes(
+                            ((Number) settings.get("loginResetTimeMinutes")).longValue());
+        }
+
+        // JWT settings
+        if (settings.containsKey("jwt")) {
+            Map<String, Object> jwt = (Map<String, Object>) settings.get("jwt");
+            if (jwt.containsKey("keyRetentionDays")) {
+                GeneralUtils.saveKeyToSettings(
+                        "security.jwt.keyRetentionDays", jwt.get("keyRetentionDays"));
+                applicationProperties
+                        .getSecurity()
+                        .getJwt()
+                        .setKeyRetentionDays((Integer) jwt.get("keyRetentionDays"));
+            }
+        }
+
+        return ResponseEntity.ok(
+                "Security settings updated. Restart required for changes to take effect.");
+    }
+
+    // ========== CONNECTIONS SETTINGS (OAuth/SAML) ==========
+
+    @GetMapping("/admin/settings/connections")
+    @Hidden
+    public ResponseEntity<Map<String, Object>> getConnectionsSettings() {
+        Map<String, Object> settings = new HashMap<>();
+        ApplicationProperties.Security security = applicationProperties.getSecurity();
+
+        // OAuth2 settings
+        ApplicationProperties.Security.OAUTH2 oauth2 = security.getOauth2();
+        settings.put(
+                "oauth2",
+                Map.of(
+                        "enabled", oauth2.getEnabled(),
+                        "issuer", oauth2.getIssuer() != null ? oauth2.getIssuer() : "",
+                        "clientId", oauth2.getClientId() != null ? oauth2.getClientId() : "",
+                        "provider", oauth2.getProvider() != null ? oauth2.getProvider() : "",
+                        "autoCreateUser", oauth2.getAutoCreateUser(),
+                        "blockRegistration", oauth2.getBlockRegistration(),
+                        "useAsUsername",
+                                oauth2.getUseAsUsername() != null
+                                        ? oauth2.getUseAsUsername()
+                                        : ""));
+
+        // SAML2 settings
+        ApplicationProperties.Security.SAML2 saml2 = security.getSaml2();
+        settings.put(
+                "saml2",
+                Map.of(
+                        "enabled", saml2.getEnabled(),
+                        "provider", saml2.getProvider() != null ? saml2.getProvider() : "",
+                        "autoCreateUser", saml2.getAutoCreateUser(),
+                        "blockRegistration", saml2.getBlockRegistration(),
+                        "registrationId", saml2.getRegistrationId()));
+
+        return ResponseEntity.ok(settings);
+    }
+
+    @PostMapping("/admin/settings/connections")
+    @Hidden
+    public ResponseEntity<String> updateConnectionsSettings(
+            @RequestBody Map<String, Object> settings) throws IOException {
+        // OAuth2 settings
+        if (settings.containsKey("oauth2")) {
+            Map<String, Object> oauth2 = (Map<String, Object>) settings.get("oauth2");
+            if (oauth2.containsKey("enabled")) {
+                GeneralUtils.saveKeyToSettings("security.oauth2.enabled", oauth2.get("enabled"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setEnabled((Boolean) oauth2.get("enabled"));
+            }
+            if (oauth2.containsKey("issuer")) {
+                GeneralUtils.saveKeyToSettings("security.oauth2.issuer", oauth2.get("issuer"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setIssuer((String) oauth2.get("issuer"));
+            }
+            if (oauth2.containsKey("clientId")) {
+                GeneralUtils.saveKeyToSettings("security.oauth2.clientId", oauth2.get("clientId"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setClientId((String) oauth2.get("clientId"));
+            }
+            if (oauth2.containsKey("clientSecret")) {
+                GeneralUtils.saveKeyToSettings(
+                        "security.oauth2.clientSecret", oauth2.get("clientSecret"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setClientSecret((String) oauth2.get("clientSecret"));
+            }
+            if (oauth2.containsKey("provider")) {
+                GeneralUtils.saveKeyToSettings("security.oauth2.provider", oauth2.get("provider"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setProvider((String) oauth2.get("provider"));
+            }
+            if (oauth2.containsKey("autoCreateUser")) {
+                GeneralUtils.saveKeyToSettings(
+                        "security.oauth2.autoCreateUser", oauth2.get("autoCreateUser"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setAutoCreateUser((Boolean) oauth2.get("autoCreateUser"));
+            }
+            if (oauth2.containsKey("blockRegistration")) {
+                GeneralUtils.saveKeyToSettings(
+                        "security.oauth2.blockRegistration", oauth2.get("blockRegistration"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setBlockRegistration((Boolean) oauth2.get("blockRegistration"));
+            }
+            if (oauth2.containsKey("useAsUsername")) {
+                GeneralUtils.saveKeyToSettings(
+                        "security.oauth2.useAsUsername", oauth2.get("useAsUsername"));
+                applicationProperties
+                        .getSecurity()
+                        .getOauth2()
+                        .setUseAsUsername((String) oauth2.get("useAsUsername"));
+            }
+        }
+
+        // SAML2 settings
+        if (settings.containsKey("saml2")) {
+            Map<String, Object> saml2 = (Map<String, Object>) settings.get("saml2");
+            if (saml2.containsKey("enabled")) {
+                GeneralUtils.saveKeyToSettings("security.saml2.enabled", saml2.get("enabled"));
+                applicationProperties
+                        .getSecurity()
+                        .getSaml2()
+                        .setEnabled((Boolean) saml2.get("enabled"));
+            }
+            if (saml2.containsKey("provider")) {
+                GeneralUtils.saveKeyToSettings("security.saml2.provider", saml2.get("provider"));
+                applicationProperties
+                        .getSecurity()
+                        .getSaml2()
+                        .setProvider((String) saml2.get("provider"));
+            }
+            if (saml2.containsKey("autoCreateUser")) {
+                GeneralUtils.saveKeyToSettings(
+                        "security.saml2.autoCreateUser", saml2.get("autoCreateUser"));
+                applicationProperties
+                        .getSecurity()
+                        .getSaml2()
+                        .setAutoCreateUser((Boolean) saml2.get("autoCreateUser"));
+            }
+            if (saml2.containsKey("blockRegistration")) {
+                GeneralUtils.saveKeyToSettings(
+                        "security.saml2.blockRegistration", saml2.get("blockRegistration"));
+                applicationProperties
+                        .getSecurity()
+                        .getSaml2()
+                        .setBlockRegistration((Boolean) saml2.get("blockRegistration"));
+            }
+        }
+
+        return ResponseEntity.ok(
+                "Connection settings updated. Restart required for changes to take effect.");
+    }
+
+    // ========== PRIVACY SETTINGS ==========
+
+    @GetMapping("/admin/settings/privacy")
+    @Hidden
+    public ResponseEntity<Map<String, Object>> getPrivacySettings() {
+        Map<String, Object> settings = new HashMap<>();
+
+        settings.put("enableAnalytics", applicationProperties.getSystem().getEnableAnalytics());
+        settings.put("googleVisibility", applicationProperties.getSystem().getGooglevisibility());
+        settings.put("metricsEnabled", applicationProperties.getMetrics().getEnabled());
+
+        return ResponseEntity.ok(settings);
+    }
+
+    @PostMapping("/admin/settings/privacy")
+    @Hidden
+    public ResponseEntity<String> updatePrivacySettings(@RequestBody Map<String, Object> settings)
+            throws IOException {
+        if (settings.containsKey("enableAnalytics")) {
+            GeneralUtils.saveKeyToSettings(
+                    "system.enableAnalytics", settings.get("enableAnalytics"));
+            applicationProperties
+                    .getSystem()
+                    .setEnableAnalytics((Boolean) settings.get("enableAnalytics"));
+        }
+        if (settings.containsKey("googleVisibility")) {
+            GeneralUtils.saveKeyToSettings(
+                    "system.googlevisibility", settings.get("googleVisibility"));
+            applicationProperties
+                    .getSystem()
+                    .setGooglevisibility((Boolean) settings.get("googleVisibility"));
+        }
+        if (settings.containsKey("metricsEnabled")) {
+            GeneralUtils.saveKeyToSettings("metrics.enabled", settings.get("metricsEnabled"));
+            applicationProperties.getMetrics().setEnabled((Boolean) settings.get("metricsEnabled"));
+        }
+
+        return ResponseEntity.ok(
+                "Privacy settings updated. Restart required for changes to take effect.");
+    }
+
+    // ========== ADVANCED SETTINGS ==========
+
+    @GetMapping("/admin/settings/advanced")
+    @Hidden
+    public ResponseEntity<Map<String, Object>> getAdvancedSettings() {
+        Map<String, Object> settings = new HashMap<>();
+
+        settings.put("endpoints", applicationProperties.getEndpoints());
+        settings.put(
+                "enableAlphaFunctionality",
+                applicationProperties.getSystem().getEnableAlphaFunctionality());
+        settings.put("maxDPI", applicationProperties.getSystem().getMaxDPI());
+        settings.put("enableUrlToPDF", applicationProperties.getSystem().getEnableUrlToPDF());
+        settings.put("customPaths", applicationProperties.getSystem().getCustomPaths());
+        settings.put(
+                "tempFileManagement", applicationProperties.getSystem().getTempFileManagement());
+
+        return ResponseEntity.ok(settings);
+    }
+
+    @PostMapping("/admin/settings/advanced")
+    @Hidden
+    public ResponseEntity<String> updateAdvancedSettings(@RequestBody Map<String, Object> settings)
+            throws IOException {
+        if (settings.containsKey("enableAlphaFunctionality")) {
+            GeneralUtils.saveKeyToSettings(
+                    "system.enableAlphaFunctionality", settings.get("enableAlphaFunctionality"));
+            applicationProperties
+                    .getSystem()
+                    .setEnableAlphaFunctionality(
+                            (Boolean) settings.get("enableAlphaFunctionality"));
+        }
+        if (settings.containsKey("maxDPI")) {
+            GeneralUtils.saveKeyToSettings("system.maxDPI", settings.get("maxDPI"));
+            applicationProperties.getSystem().setMaxDPI((Integer) settings.get("maxDPI"));
+        }
+        if (settings.containsKey("enableUrlToPDF")) {
+            GeneralUtils.saveKeyToSettings("system.enableUrlToPDF", settings.get("enableUrlToPDF"));
+            applicationProperties
+                    .getSystem()
+                    .setEnableUrlToPDF((Boolean) settings.get("enableUrlToPDF"));
+        }
+
+        return ResponseEntity.ok(
+                "Advanced settings updated. Restart required for changes to take effect.");
+    }
 }
@@ -15,6 +15,7 @@ import stirling.software.common.annotations.api.ConfigApi;
 import stirling.software.common.configuration.AppConfig;
 import stirling.software.common.model.ApplicationProperties;
 import stirling.software.common.service.ServerCertificateServiceInterface;
+import stirling.software.common.service.UserServiceInterface;

@ConfigApi
@Hidden
@@ -24,17 +25,21 @@ public class ConfigController {
    private final ApplicationContext applicationContext;
    private final EndpointConfiguration endpointConfiguration;
    private final ServerCertificateServiceInterface serverCertificateService;
+    private final UserServiceInterface userService;

    public ConfigController(
            ApplicationProperties applicationProperties,
            ApplicationContext applicationContext,
            EndpointConfiguration endpointConfiguration,
            @org.springframework.beans.factory.annotation.Autowired(required = false)
-                    ServerCertificateServiceInterface serverCertificateService) {
+                    ServerCertificateServiceInterface serverCertificateService,
+            @org.springframework.beans.factory.annotation.Autowired(required = false)
+                    UserServiceInterface userService) {
        this.applicationProperties = applicationProperties;
        this.applicationContext = applicationContext;
        this.endpointConfiguration = endpointConfiguration;
        this.serverCertificateService = serverCertificateService;
+        this.userService = userService;
    }

    @GetMapping("/app-config")
@@ -51,20 +56,34 @@ public class ConfigController {
            configData.put("serverPort", appConfig.getServerPort());

            // Extract values from ApplicationProperties
-            configData.put("appName", applicationProperties.getUi().getAppName());
            configData.put("appNameNavbar", applicationProperties.getUi().getAppNameNavbar());
-            configData.put("homeDescription", applicationProperties.getUi().getHomeDescription());
            configData.put("languages", applicationProperties.getUi().getLanguages());

            // Security settings
            configData.put("enableLogin", applicationProperties.getSecurity().getEnableLogin());

+            // Mail settings
+            configData.put("enableEmailInvites", applicationProperties.getMail().isEnableInvites());
+
+            // Check if user is admin using UserServiceInterface
+            boolean isAdmin = false;
+            if (userService != null) {
+                try {
+                    isAdmin = userService.isCurrentUserAdmin();
+                } catch (Exception e) {
+                    // If there's an error, isAdmin remains false
+                }
+            }
+            configData.put("isAdmin", isAdmin);
+
            // System settings
            configData.put(
                    "enableAlphaFunctionality",
                    applicationProperties.getSystem().getEnableAlphaFunctionality());
            configData.put(
                    "enableAnalytics", applicationProperties.getSystem().getEnableAnalytics());
+            configData.put("enablePosthog", applicationProperties.getSystem().getEnablePosthog());
+            configData.put("enableScarf", applicationProperties.getSystem().getEnableScarf());

            // Premium/Enterprise settings
            configData.put("premiumEnabled", applicationProperties.getPremium().isEnabled());
@@ -2,7 +2,7 @@ multipart.enabled=true
 logging.level.org.springframework=WARN
 logging.level.org.hibernate=WARN
 logging.level.org.eclipse.jetty=WARN
-#logging.level.org.springframework.security.saml2=TRACE
+#logging.level.org.springframework.security.oauth2=DEBUG
 #logging.level.org.springframework.security=DEBUG
 #logging.level.org.opensaml=DEBUG
 #logging.level.stirling.software.proprietary.security=DEBUG
@@ -35,12 +35,12 @@ spring.datasource.username=sa
 spring.datasource.password=
 spring.h2.console.enabled=false
 spring.jpa.hibernate.ddl-auto=update
-# Defer datasource initialization to ensure that the database is fully set up 
-# before Hibernate attempts to access it. This is particularly useful when 
+# Defer datasource initialization to ensure that the database is fully set up
+# before Hibernate attempts to access it. This is particularly useful when
 # using database initialization scripts or tools.
 spring.jpa.defer-datasource-initialization=true

-# Disable SQL logging to avoid cluttering the logs in production. Enable this 
+# Disable SQL logging to avoid cluttering the logs in production. Enable this
 # property during development if you need to debug SQL queries.
 spring.jpa.show-sql=false
 server.servlet.session.timeout:30m
@@ -60,4 +60,4 @@ spring.main.allow-bean-definition-overriding=true
 java.io.tmpdir=${stirling.tempfiles.directory:${java.io.tmpdir}/stirling-pdf}

 # V2 features
-v2=false
+v2=true
@@ -633,6 +633,11 @@ permissions.tags=read,write,edit,print
 home.removePages.title=Remove
 home.removePages.desc=Delete unwanted pages from your PDF document.
 removePages.tags=Remove pages,delete pages
+removePages.processingMode.label=Processing mode
+removePages.processingMode.backend=Backend
+removePages.processingMode.frontend=Browser
+removePages.processingMode.backendDescription=Use the server to remove pages (required for complex formulas).
+removePages.processingMode.frontendDescription=Remove the selected pages locally in your browser.

 home.addPassword.title=Add Password
 home.addPassword.desc=Encrypt your PDF document with a password.
@@ -1056,6 +1061,11 @@ AddStampRequest.overrideY=Override Y Coordinate
 AddStampRequest.customMargin=Custom Margin
 AddStampRequest.customColor=Custom Text Colour
 AddStampRequest.submit=Submit
+addStamp.processingMode.label=Processing mode
+addStamp.processingMode.backend=Backend
+addStamp.processingMode.frontend=Browser
+addStamp.processingMode.backendDescription=Use the server to stamp pages (required for custom page formulas).
+addStamp.processingMode.frontendDescription=Stamp selected pages directly in your browser.


 #sanitizePDF
@@ -1104,6 +1114,11 @@ adjustContrast.download=Download
 crop.title=Crop
 crop.header=Crop PDF
 crop.submit=Submit
+crop.processingMode.label=Processing mode
+crop.processingMode.backend=Backend
+crop.processingMode.frontend=Browser
+crop.processingMode.backendDescription=Use the server to crop pages (recommended for very large files).
+crop.processingMode.frontendDescription=Crop each page locally without uploading the PDF.


 #autoSplitPDF
@@ -1480,6 +1495,11 @@ watermark.selectText.10=Convert PDF to PDF-Image
 watermark.submit=Add Watermark
 watermark.type.1=Text
 watermark.type.2=Image
+watermark.processingMode.label=Processing mode
+watermark.processingMode.backend=Backend
+watermark.processingMode.frontend=Browser
+watermark.processingMode.backendDescription=Use the server to apply the watermark (recommended for large files or flattening).
+watermark.processingMode.frontendDescription=Process the watermark directly in your browser without uploading files.


 #Change permissions
@@ -64,7 +64,6 @@ security:
    enableKeyRotation: true # Set to 'true' to enable key pair rotation
    enableKeyCleanup: true # Set to 'true' to enable key pair cleanup
    keyRetentionDays: 7 # Number of days to retain old keys. The default is 7 days.
-    secureCookie: false # Set to 'true' to use secure cookies for JWTs
  validation: # PDF signature validation settings
    trust:
      serverAsAnchor: true # Trust server certificate as anchor for PDF signatures (if configured and self-signed or CA)
@@ -100,6 +99,7 @@ premium:

 mail:
  enabled: false # set to 'true' to enable sending emails
+  enableInvites: false # set to 'true' to enable email invites for user management (requires mail.enabled and security.enableLogin)
  host: smtp.example.com # SMTP server hostname
  port: 587 # SMTP server port
  username: '' # SMTP server username
@@ -107,8 +107,8 @@ mail:
  from: '' # sender email address

 legal:
-  termsAndConditions: https://www.stirlingpdf.com/terms # URL to the terms and conditions of your application (e.g. https://example.com/terms). Empty string to disable or filename to load from local file in static folder
-  privacyPolicy: https://www.stirlingpdf.com/privacy-policy # URL to the privacy policy of your application (e.g. https://example.com/privacy). Empty string to disable or filename to load from local file in static folder
+  termsAndConditions: https://www.stirling.com/legal/terms-of-service # URL to the terms and conditions of your application (e.g. https://example.com/terms). Empty string to disable or filename to load from local file in static folder
+  privacyPolicy: https://www.stirling.com/legal/privacy-policy # URL to the privacy policy of your application (e.g. https://example.com/privacy). Empty string to disable or filename to load from local file in static folder
  accessibilityStatement: '' # URL to the accessibility statement of your application (e.g. https://example.com/accessibility). Empty string to disable or filename to load from local file in static folder
  cookiePolicy: '' # URL to the cookie policy of your application (e.g. https://example.com/cookie). Empty string to disable or filename to load from local file in static folder
  impressum: '' # URL to the impressum of your application (e.g. https://example.com/impressum). Empty string to disable or filename to load from local file in static folder
@@ -121,10 +121,13 @@ system:
  showUpdateOnlyAdmin: false # only admins can see when a new update is available, depending on showUpdate it must be set to 'true'
  customHTMLFiles: false # enable to have files placed in /customFiles/templates override the existing template HTML files
  tessdataDir: /usr/share/tessdata # path to the directory containing the Tessdata files. This setting is relevant for Windows systems. For Windows users, this path should be adjusted to point to the appropriate directory where the Tessdata files are stored.
-  enableAnalytics: null # set to 'true' to enable analytics, set to 'false' to disable analytics; for enterprise users, this is set to true
+  enableAnalytics: null # Master toggle for analytics: set to 'true' to enable all analytics, 'false' to disable all analytics, or leave as 'null' to prompt admin on first launch
+  enablePosthog: null # Enable PostHog analytics (open-source product analytics): set to 'true' to enable, 'false' to disable, or 'null' to enable by default when analytics is enabled
+  enableScarf: null # Enable Scarf tracking pixel: set to 'true' to enable, 'false' to disable, or 'null' to enable by default when analytics is enabled
  enableUrlToPDF: false # Set to 'true' to enable URL to PDF, INTERNAL ONLY, known security issues, should not be used externally
  disableSanitize: false # set to true to disable Sanitize HTML; (can lead to injections in HTML)
  maxDPI: 500 # Maximum allowed DPI for PDF to image conversion
+  corsAllowedOrigins: [] # List of allowed origins for CORS (e.g. ['http://localhost:5173', 'https://app.example.com']). Leave empty to disable CORS.
  serverCertificate:
    enabled: true # Enable server-side certificate for "Sign with Stirling-PDF" option
    organizationName: Stirling-PDF # Organization name for generated certificates
@@ -169,8 +172,6 @@ system:
    cleanupSystemTemp: false # Whether to clean broader system temp directory

 ui:
-  appName: '' # application's visible name
-  homeDescription: '' # short description or tagline shown on the homepage
  appNameNavbar: '' # name displayed on the navigation bar
  languages: [] # If empty, all languages are enabled. To display only German and Polish ["de_DE", "pl_PL"]. British English is always enabled.

@@ -41,10 +41,11 @@ class CertificateValidationServiceTest {
        when(validation.getTrust()).thenReturn(trust);
        when(validation.getRevocation()).thenReturn(revocation);
        when(validation.isAllowAIA()).thenReturn(false);
-        when(validation.isEnableEUTL()).thenReturn(false);
        when(trust.isServerAsAnchor()).thenReturn(false);
        when(trust.isUseSystemTrust()).thenReturn(false);
        when(trust.isUseMozillaBundle()).thenReturn(false);
+        when(trust.isUseAATL()).thenReturn(false);
+        when(trust.isUseEUTL()).thenReturn(false);
        when(revocation.getMode()).thenReturn("none");
        when(revocation.isHardFail()).thenReturn(false);

@@ -85,22 +86,6 @@ class CertificateValidationServiceTest {
        assertTrue(result, "Expired certificate should be outside validity period");
    }

-    @Test
-    @SuppressWarnings("deprecation")
-    void testDeprecatedIsRevoked_ValidCertificate() {
-        // Test deprecated method for backwards compatibility
-        boolean result = validationService.isRevoked(validCertificate);
-        assertFalse(result, "Valid certificate should not be considered revoked");
-    }
-
-    @Test
-    @SuppressWarnings("deprecation")
-    void testDeprecatedIsRevoked_ExpiredCertificate() {
-        // Test deprecated method for backwards compatibility
-        boolean result = validationService.isRevoked(expiredCertificate);
-        assertTrue(result, "Expired certificate should be considered revoked (legacy behavior)");
-    }
-
    // Note: Full integration tests for buildAndValidatePath() would require
    // real certificate chains and trust anchors. These would be better as
    // integration tests using actual signed PDFs from the test-signed-pdfs directory.
@@ -53,7 +53,6 @@ import stirling.software.proprietary.security.session.SessionPersistentRegistry;

@Slf4j
@ProprietaryUiDataApi
-@EnterpriseEndpoint
 public class ProprietaryUIDataController {

    private final ApplicationProperties applicationProperties;
@@ -89,6 +88,7 @@ public class ProprietaryUIDataController {

    @GetMapping("/audit-dashboard")
    @PreAuthorize("hasRole('ADMIN')")
+    @EnterpriseEndpoint
    @Operation(summary = "Get audit dashboard data")
    public ResponseEntity<AuditDashboardData> getAuditDashboardData() {
        AuditDashboardData data = new AuditDashboardData();
@@ -57,7 +57,6 @@ public class CustomAuthenticationSuccessHandler
            String jwt =
                    jwtService.generateToken(
                            authentication, Map.of("authType", AuthenticationType.WEB));
-            jwtService.addToken(response, jwt);
            log.debug("JWT generated for user: {}", userName);

            getRedirectStrategy().sendRedirect(request, response, "/");
@@ -72,7 +72,6 @@ public class CustomLogoutSuccessHandler extends SimpleUrlLogoutSuccessHandler {
                    getRedirectStrategy().sendRedirect(request, response, LOGOUT_PATH);
                }
            } else if (!jwtService.extractToken(request).isBlank()) {
-                jwtService.clearToken(response);
                getRedirectStrategy().sendRedirect(request, response, LOGOUT_PATH);
            } else {
                // Redirect to login page after logout
@@ -115,8 +114,12 @@ public class CustomLogoutSuccessHandler extends SimpleUrlLogoutSuccessHandler {
            // Set service provider keys for the SamlClient
            samlClient.setSPKeys(certificate, privateKey);

-            // Redirect to identity provider for logout. todo: add relay state
-            samlClient.redirectToIdentityProvider(response, null, nameIdValue);
+            // Build relay state to return user to login page after IdP logout
+            String relayState =
+                    UrlUtils.getOrigin(request) + request.getContextPath() + LOGOUT_PATH;
+
+            // Redirect to identity provider for logout with relay state
+            samlClient.redirectToIdentityProvider(response, relayState, nameIdValue);
        } catch (Exception e) {
            log.error(
                    "Error retrieving logout URL from Provider {} for user {}",
@@ -13,7 +13,7 @@ public class RateLimitResetScheduler {

    private final IPRateLimitingFilter rateLimitingFilter;

-    @Scheduled(cron = "0 0 0 * * MON") // At 00:00 every Monday TODO: configurable
+    @Scheduled(cron = "${security.rate-limit.reset-schedule:0 0 0 * * MON}")
    public void resetRateLimit() {
        rateLimitingFilter.resetRequestCounts();
    }
@@ -39,7 +39,6 @@ import stirling.software.proprietary.security.CustomLogoutSuccessHandler;
 import stirling.software.proprietary.security.JwtAuthenticationEntryPoint;
 import stirling.software.proprietary.security.database.repository.JPATokenRepositoryImpl;
 import stirling.software.proprietary.security.database.repository.PersistentLoginRepository;
-import stirling.software.proprietary.security.filter.FirstLoginFilter;
 import stirling.software.proprietary.security.filter.IPRateLimitingFilter;
 import stirling.software.proprietary.security.filter.JwtAuthenticationFilter;
 import stirling.software.proprietary.security.filter.UserAuthenticationFilter;
@@ -74,7 +73,6 @@ public class SecurityConfiguration {
    private final JwtServiceInterface jwtService;
    private final JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint;
    private final LoginAttemptService loginAttemptService;
-    private final FirstLoginFilter firstLoginFilter;
    private final SessionPersistentRegistry sessionRegistry;
    private final PersistentLoginRepository persistentLoginRepository;
    private final GrantedAuthoritiesMapper oAuth2userAuthoritiesMapper;
@@ -93,7 +91,6 @@ public class SecurityConfiguration {
            JwtServiceInterface jwtService,
            JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint,
            LoginAttemptService loginAttemptService,
-            FirstLoginFilter firstLoginFilter,
            SessionPersistentRegistry sessionRegistry,
            @Autowired(required = false) GrantedAuthoritiesMapper oAuth2userAuthoritiesMapper,
            @Autowired(required = false)
@@ -110,7 +107,6 @@ public class SecurityConfiguration {
        this.jwtService = jwtService;
        this.jwtAuthenticationEntryPoint = jwtAuthenticationEntryPoint;
        this.loginAttemptService = loginAttemptService;
-        this.firstLoginFilter = firstLoginFilter;
        this.sessionRegistry = sessionRegistry;
        this.persistentLoginRepository = persistentLoginRepository;
        this.oAuth2userAuthoritiesMapper = oAuth2userAuthoritiesMapper;
@@ -132,19 +128,14 @@ public class SecurityConfiguration {
        if (loginEnabledValue) {
            boolean v2Enabled = appConfig.v2Enabled();

-            if (v2Enabled) {
-                http.addFilterBefore(
-                                jwtAuthenticationFilter(),
-                                UsernamePasswordAuthenticationFilter.class)
-                        .exceptionHandling(
-                                exceptionHandling ->
-                                        exceptionHandling.authenticationEntryPoint(
-                                                jwtAuthenticationEntryPoint));
-            }
            http.addFilterBefore(
                            userAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)
-                    .addFilterAfter(rateLimitingFilter(), UserAuthenticationFilter.class)
-                    .addFilterAfter(firstLoginFilter, UsernamePasswordAuthenticationFilter.class);
+                    .addFilterBefore(
+                            rateLimitingFilter(), UsernamePasswordAuthenticationFilter.class);
+
+            if (v2Enabled) {
+                http.addFilterBefore(jwtAuthenticationFilter(), UserAuthenticationFilter.class);
+            }

            if (!securityProperties.getCsrfDisabled()) {
                CookieCsrfTokenRepository cookieRepo =
@@ -156,6 +147,13 @@ public class SecurityConfiguration {
                        csrf ->
                                csrf.ignoringRequestMatchers(
                                                request -> {
+                                                    String uri = request.getRequestURI();
+
+                                                    // Ignore CSRF for auth endpoints
+                                                    if (uri.startsWith("/api/v1/auth/")) {
+                                                        return true;
+                                                    }
+
                                                    String apiKey = request.getHeader("X-API-KEY");
                                                    // If there's no API key, don't ignore CSRF
                                                    // (return false)
@@ -238,9 +236,12 @@ public class SecurityConfiguration {
                                                                : uri;
                                                return trimmedUri.startsWith("/login")
                                                        || trimmedUri.startsWith("/oauth")
+                                                        || trimmedUri.startsWith("/oauth2")
                                                        || trimmedUri.startsWith("/saml2")
                                                        || trimmedUri.endsWith(".svg")
                                                        || trimmedUri.startsWith("/register")
+                                                        || trimmedUri.startsWith("/signup")
+                                                        || trimmedUri.startsWith("/auth/callback")
                                                        || trimmedUri.startsWith("/error")
                                                        || trimmedUri.startsWith("/images/")
                                                        || trimmedUri.startsWith("/public/")
@@ -252,6 +253,16 @@ public class SecurityConfiguration {
                                                        || trimmedUri.startsWith("/favicon")
                                                        || trimmedUri.startsWith(
                                                                "/api/v1/info/status")
+                                                        || trimmedUri.startsWith("/api/v1/config")
+                                                        || trimmedUri.startsWith(
+                                                                "/api/v1/auth/register")
+                                                        || trimmedUri.startsWith(
+                                                                "/api/v1/user/register")
+                                                        || trimmedUri.startsWith(
+                                                                "/api/v1/auth/login")
+                                                        || trimmedUri.startsWith(
+                                                                "/api/v1/auth/refresh")
+                                                        || trimmedUri.startsWith("/api/v1/auth/me")
                                                        || trimmedUri.startsWith("/v1/api-docs")
                                                        || uri.contains("/v1/api-docs");
                                            })
@@ -277,33 +288,40 @@ public class SecurityConfiguration {
            // Handle OAUTH2 Logins
            if (securityProperties.isOauth2Active()) {
                http.oauth2Login(
-                        oauth2 ->
-                                oauth2.loginPage("/oauth2")
-                                        /*
-                                        This Custom handler is used to check if the OAUTH2 user trying to log in, already exists in the database.
-                                        If user exists, login proceeds as usual. If user does not exist, then it is auto-created but only if 'OAUTH2AutoCreateUser'
-                                        is set as true, else login fails with an error message advising the same.
-                                         */
-                                        .successHandler(
-                                                new CustomOAuth2AuthenticationSuccessHandler(
-                                                        loginAttemptService,
-                                                        securityProperties.getOauth2(),
-                                                        userService,
-                                                        jwtService))
-                                        .failureHandler(
-                                                new CustomOAuth2AuthenticationFailureHandler())
-                                        // Add existing Authorities from the database
-                                        .userInfoEndpoint(
-                                                userInfoEndpoint ->
-                                                        userInfoEndpoint
-                                                                .oidcUserService(
-                                                                        new CustomOAuth2UserService(
-                                                                                securityProperties,
-                                                                                userService,
-                                                                                loginAttemptService))
-                                                                .userAuthoritiesMapper(
-                                                                        oAuth2userAuthoritiesMapper))
-                                        .permitAll());
+                        oauth2 -> {
+                            // v1: Use /oauth2 as login page for Thymeleaf templates
+                            if (!v2Enabled) {
+                                oauth2.loginPage("/oauth2");
+                            }
+
+                            // v2: Don't set loginPage, let default OAuth2 flow handle it
+                            oauth2
+                                    /*
+                                       This Custom handler is used to check if the OAUTH2 user trying to log in, already exists in the database.
+                                       If user exists, login proceeds as usual. If user does not exist, then it is auto-created but only if 'OAUTH2AutoCreateUser'
+                                       is set as true, else login fails with an error message advising the same.
+                                    */
+                                    .successHandler(
+                                            new CustomOAuth2AuthenticationSuccessHandler(
+                                                    loginAttemptService,
+                                                    securityProperties.getOauth2(),
+                                                    userService,
+                                                    jwtService))
+                                    .failureHandler(new CustomOAuth2AuthenticationFailureHandler())
+                                    // Add existing Authorities from the database
+                                    .userInfoEndpoint(
+                                            userInfoEndpoint ->
+                                                    userInfoEndpoint
+                                                            .oidcUserService(
+                                                                    new CustomOAuth2UserService(
+                                                                            securityProperties
+                                                                                    .getOauth2(),
+                                                                            userService,
+                                                                            loginAttemptService))
+                                                            .userAuthoritiesMapper(
+                                                                    oAuth2userAuthoritiesMapper))
+                                    .permitAll();
+                        });
            }
            // Handle SAML
            if (securityProperties.isSaml2Active() && runningProOrHigher) {
@@ -1,19 +1,27 @@
 package stirling.software.proprietary.security.controller.api;

 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
 import java.util.HashSet;
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.regex.Pattern;

+import org.springframework.boot.SpringApplication;
+import org.springframework.context.ApplicationContext;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestParam;
@@ -32,7 +40,9 @@ import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.annotations.api.AdminApi;
 import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.util.AppArgsCapture;
 import stirling.software.common.util.GeneralUtils;
+import stirling.software.common.util.JarPathUtil;
 import stirling.software.proprietary.security.model.api.admin.SettingValueResponse;
 import stirling.software.proprietary.security.model.api.admin.UpdateSettingValueRequest;
 import stirling.software.proprietary.security.model.api.admin.UpdateSettingsRequest;
@@ -45,6 +55,7 @@ public class AdminSettingsController {

    private final ApplicationProperties applicationProperties;
    private final ObjectMapper objectMapper;
+    private final ApplicationContext applicationContext;

    // Track settings that have been modified but not yet applied (require restart)
    private static final ConcurrentHashMap<String, Object> pendingChanges =
@@ -195,7 +206,8 @@ public class AdminSettingsController {
    @Operation(
            summary = "Get specific settings section",
            description =
-                    "Retrieve settings for a specific section (e.g., security, system, ui). Admin access required.")
+                    "Retrieve settings for a specific section (e.g., security, system, ui). "
+                            + "By default includes pending changes with awaitingRestart flags. Admin access required.")
    @ApiResponses(
            value = {
                @ApiResponse(
@@ -206,7 +218,9 @@ public class AdminSettingsController {
                        responseCode = "403",
                        description = "Access denied - Admin role required")
            })
-    public ResponseEntity<?> getSettingsSection(@PathVariable String sectionName) {
+    public ResponseEntity<?> getSettingsSection(
+            @PathVariable String sectionName,
+            @RequestParam(defaultValue = "true") boolean includePending) {
        try {
            Object sectionData = getSectionData(sectionName);
            if (sectionData == null) {
@@ -217,8 +231,24 @@ public class AdminSettingsController {
                                        + ". Valid sections: "
                                        + String.join(", ", VALID_SECTION_NAMES));
            }
-            log.debug("Admin requested settings section: {}", sectionName);
-            return ResponseEntity.ok(sectionData);
+
+            // Convert to Map for manipulation
+            @SuppressWarnings("unchecked")
+            Map<String, Object> sectionMap = objectMapper.convertValue(sectionData, Map.class);
+
+            if (includePending && !pendingChanges.isEmpty()) {
+                // Add pending changes block for this section
+                Map<String, Object> sectionPending = extractPendingForSection(sectionName);
+                if (!sectionPending.isEmpty()) {
+                    sectionMap.put("_pending", sectionPending);
+                }
+            }
+
+            log.debug(
+                    "Admin requested settings section: {} (includePending={})",
+                    sectionName,
+                    includePending);
+            return ResponseEntity.ok(sectionMap);
        } catch (IllegalArgumentException e) {
            log.error("Invalid section name {}: {}", sectionName, e.getMessage(), e);
            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
@@ -388,6 +418,101 @@ public class AdminSettingsController {
        }
    }

+    @PostMapping("/restart")
+    @Operation(
+            summary = "Restart the application",
+            description =
+                    "Triggers a graceful restart of the Spring Boot application to apply pending settings changes. Uses a restart helper to ensure proper restart. Admin access required.")
+    @ApiResponses(
+            value = {
+                @ApiResponse(responseCode = "200", description = "Restart initiated successfully"),
+                @ApiResponse(
+                        responseCode = "403",
+                        description = "Access denied - Admin role required"),
+                @ApiResponse(responseCode = "500", description = "Failed to initiate restart")
+            })
+    public ResponseEntity<String> restartApplication() {
+        try {
+            log.warn("Admin initiated application restart");
+
+            // Get paths to current JAR and restart helper
+            Path appJar = JarPathUtil.currentJar();
+            Path helperJar = JarPathUtil.restartHelperJar();
+
+            if (appJar == null) {
+                log.error("Cannot restart: not running from JAR (likely development mode)");
+                return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                        .body(
+                                "Restart not available in development mode. Please restart the application manually.");
+            }
+
+            if (helperJar == null || !Files.isRegularFile(helperJar)) {
+                log.error("Cannot restart: restart-helper.jar not found at expected location");
+                return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                        .body("Restart helper not found. Please restart the application manually.");
+            }
+
+            // Get current application arguments
+            List<String> appArgs = AppArgsCapture.APP_ARGS.get();
+
+            // Write args to temp file to avoid command-line quoting issues
+            Path argsFile = Files.createTempFile("stirling-app-args-", ".txt");
+            Files.write(argsFile, appArgs, StandardCharsets.UTF_8);
+
+            // Get current process PID and java executable
+            long pid = ProcessHandle.current().pid();
+            String javaBin = JarPathUtil.javaExecutable();
+
+            // Build command to launch restart helper
+            List<String> cmd = new ArrayList<>();
+            cmd.add(javaBin);
+            cmd.add("-jar");
+            cmd.add(helperJar.toString());
+            cmd.add("--pid");
+            cmd.add(Long.toString(pid));
+            cmd.add("--app");
+            cmd.add(appJar.toString());
+            cmd.add("--argsFile");
+            cmd.add(argsFile.toString());
+            cmd.add("--backoffMs");
+            cmd.add("1000");
+
+            log.info("Launching restart helper: {}", String.join(" ", cmd));
+
+            // Launch restart helper process
+            new ProcessBuilder(cmd)
+                    .directory(appJar.getParent().toFile())
+                    .inheritIO() // Forward logs
+                    .start();
+
+            // Clear pending changes since we're restarting
+            pendingChanges.clear();
+
+            // Give the HTTP response time to complete, then exit
+            new Thread(
+                            () -> {
+                                try {
+                                    Thread.sleep(1000);
+                                    log.info("Shutting down for restart...");
+                                    SpringApplication.exit(applicationContext, () -> 0);
+                                    System.exit(0);
+                                } catch (InterruptedException e) {
+                                    log.error("Restart interrupted: {}", e.getMessage(), e);
+                                    Thread.currentThread().interrupt();
+                                }
+                            })
+                    .start();
+
+            return ResponseEntity.ok(
+                    "Application restart initiated. The server will be back online shortly.");
+
+        } catch (Exception e) {
+            log.error("Failed to initiate restart: {}", e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body("Failed to initiate application restart: " + e.getMessage());
+        }
+    }
+
    private Object getSectionData(String sectionName) {
        if (sectionName == null || sectionName.trim().isEmpty()) {
            return null;
@@ -626,4 +751,62 @@ public class AdminSettingsController {

        return mergedSettings;
    }
+
+    /**
+     * Extract pending changes for a specific section
+     *
+     * @param sectionName The section name (e.g., "security", "system")
+     * @return Map of pending changes with nested structure for this section
+     */
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> extractPendingForSection(String sectionName) {
+        Map<String, Object> result = new HashMap<>();
+        String sectionPrefix = sectionName.toLowerCase() + ".";
+
+        // Find all pending changes for this section
+        for (Map.Entry<String, Object> entry : pendingChanges.entrySet()) {
+            String pendingKey = entry.getKey();
+
+            if (pendingKey.toLowerCase().startsWith(sectionPrefix)) {
+                // Extract the path within the section (e.g., "security.enableLogin" ->
+                // "enableLogin")
+                String pathInSection = pendingKey.substring(sectionPrefix.length());
+                Object pendingValue = entry.getValue();
+
+                // Build nested structure from dot notation
+                setNestedValue(result, pathInSection, pendingValue);
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Set a value in a nested map using dot notation
+     *
+     * @param map The root map
+     * @param dotPath The dot notation path (e.g., "oauth2.clientSecret")
+     * @param value The value to set
+     */
+    @SuppressWarnings("unchecked")
+    private void setNestedValue(Map<String, Object> map, String dotPath, Object value) {
+        String[] parts = dotPath.split("\\.");
+        Map<String, Object> current = map;
+
+        // Navigate/create nested maps for all parts except the last
+        for (int i = 0; i < parts.length - 1; i++) {
+            String part = parts[i];
+            Object nested = current.get(part);
+
+            if (!(nested instanceof Map)) {
+                nested = new HashMap<String, Object>();
+                current.put(part, nested);
+            }
+
+            current = (Map<String, Object>) nested;
+        }
+
+        // Set the final value
+        current.put(parts[parts.length - 1], value);
+    }
 }
@@ -0,0 +1,238 @@
+package stirling.software.proprietary.security.controller.api;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.AuthenticationException;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UsernameNotFoundException;
+import org.springframework.web.bind.annotation.*;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.proprietary.security.model.AuthenticationType;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.model.api.user.UsernameAndPass;
+import stirling.software.proprietary.security.service.CustomUserDetailsService;
+import stirling.software.proprietary.security.service.JwtServiceInterface;
+import stirling.software.proprietary.security.service.UserService;
+
+/** REST API Controller for authentication operations. */
+@RestController
+@RequestMapping("/api/v1/auth")
+@RequiredArgsConstructor
+@Slf4j
+@Tag(name = "Authentication", description = "Endpoints for user authentication and registration")
+public class AuthController {
+
+    private final UserService userService;
+    private final JwtServiceInterface jwtService;
+    private final CustomUserDetailsService userDetailsService;
+
+    /**
+     * Login endpoint - replaces Supabase signInWithPassword
+     *
+     * @param request Login credentials (email/username and password)
+     * @param response HTTP response to set JWT cookie
+     * @return User and session information
+     */
+    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
+    @PostMapping("/login")
+    public ResponseEntity<?> login(
+            @RequestBody UsernameAndPass request, HttpServletResponse response) {
+        try {
+            // Validate input parameters
+            if (request.getUsername() == null || request.getUsername().trim().isEmpty()) {
+                log.warn("Login attempt with null or empty username");
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Username is required"));
+            }
+
+            if (request.getPassword() == null || request.getPassword().isEmpty()) {
+                log.warn(
+                        "Login attempt with null or empty password for user: {}",
+                        request.getUsername());
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Password is required"));
+            }
+
+            log.debug("Login attempt for user: {}", request.getUsername());
+
+            UserDetails userDetails =
+                    userDetailsService.loadUserByUsername(request.getUsername().trim());
+            User user = (User) userDetails;
+
+            if (!userService.isPasswordCorrect(user, request.getPassword())) {
+                log.warn("Invalid password for user: {}", request.getUsername());
+                return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                        .body(Map.of("error", "Invalid credentials"));
+            }
+
+            if (!user.isEnabled()) {
+                log.warn("Disabled user attempted login: {}", request.getUsername());
+                return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                        .body(Map.of("error", "User account is disabled"));
+            }
+
+            Map<String, Object> claims = new HashMap<>();
+            claims.put("authType", AuthenticationType.WEB.toString());
+            claims.put("role", user.getRolesAsString());
+
+            String token = jwtService.generateToken(user.getUsername(), claims);
+
+            log.info("Login successful for user: {}", request.getUsername());
+
+            return ResponseEntity.ok(
+                    Map.of(
+                            "user", buildUserResponse(user),
+                            "session", Map.of("access_token", token, "expires_in", 3600)));
+
+        } catch (UsernameNotFoundException e) {
+            log.warn("User not found: {}", request.getUsername());
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "Invalid username or password"));
+        } catch (AuthenticationException e) {
+            log.error("Authentication failed for user: {}", request.getUsername(), e);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "Invalid credentials"));
+        } catch (Exception e) {
+            log.error("Login error for user: {}", request.getUsername(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body(Map.of("error", "Internal server error"));
+        }
+    }
+
+    /**
+     * Get current user
+     *
+     * @return Current authenticated user information
+     */
+    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
+    @GetMapping("/me")
+    public ResponseEntity<?> getCurrentUser() {
+        try {
+            Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+
+            if (auth == null
+                    || !auth.isAuthenticated()
+                    || auth.getPrincipal().equals("anonymousUser")) {
+                return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                        .body(Map.of("error", "Not authenticated"));
+            }
+
+            UserDetails userDetails = (UserDetails) auth.getPrincipal();
+            User user = (User) userDetails;
+
+            return ResponseEntity.ok(Map.of("user", buildUserResponse(user)));
+
+        } catch (Exception e) {
+            log.error("Get current user error", e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body(Map.of("error", "Internal server error"));
+        }
+    }
+
+    /**
+     * Logout endpoint
+     *
+     * @param response HTTP response
+     * @return Success message
+     */
+    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
+    @PostMapping("/logout")
+    public ResponseEntity<?> logout(HttpServletResponse response) {
+        try {
+            SecurityContextHolder.clearContext();
+
+            log.debug("User logged out successfully");
+
+            return ResponseEntity.ok(Map.of("message", "Logged out successfully"));
+
+        } catch (Exception e) {
+            log.error("Logout error", e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body(Map.of("error", "Internal server error"));
+        }
+    }
+
+    /**
+     * Refresh token
+     *
+     * @param request HTTP request containing current JWT cookie
+     * @param response HTTP response to set new JWT cookie
+     * @return New token information
+     */
+    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
+    @PostMapping("/refresh")
+    public ResponseEntity<?> refresh(HttpServletRequest request, HttpServletResponse response) {
+        try {
+            String token = jwtService.extractToken(request);
+
+            if (token == null) {
+                return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                        .body(Map.of("error", "No token found"));
+            }
+
+            jwtService.validateToken(token);
+            String username = jwtService.extractUsername(token);
+
+            UserDetails userDetails = userDetailsService.loadUserByUsername(username);
+            User user = (User) userDetails;
+
+            Map<String, Object> claims = new HashMap<>();
+            claims.put("authType", user.getAuthenticationType());
+            claims.put("role", user.getRolesAsString());
+
+            String newToken = jwtService.generateToken(username, claims);
+
+            log.debug("Token refreshed for user: {}", username);
+
+            return ResponseEntity.ok(Map.of("access_token", newToken, "expires_in", 3600));
+
+        } catch (Exception e) {
+            log.error("Token refresh error", e);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "Token refresh failed"));
+        }
+    }
+
+    /**
+     * Helper method to build user response object
+     *
+     * @param user User entity
+     * @return Map containing user information
+     */
+    private Map<String, Object> buildUserResponse(User user) {
+        Map<String, Object> userMap = new HashMap<>();
+        userMap.put("id", user.getId());
+        userMap.put("email", user.getUsername()); // Use username as email
+        userMap.put("username", user.getUsername());
+        userMap.put("role", user.getRolesAsString());
+        userMap.put("enabled", user.isEnabled());
+
+        // Add metadata for OAuth compatibility
+        Map<String, Object> appMetadata = new HashMap<>();
+        appMetadata.put("provider", user.getAuthenticationType()); // Default to email provider
+        userMap.put("app_metadata", appMetadata);
+
+        return userMap;
+    }
+
+    // ===========================
+    // Request/Response DTOs
+    // ===========================
+
+    /** Login request DTO */
+    public record LoginRequest(String email, String password) {}
+}
@@ -2,21 +2,19 @@ package stirling.software.proprietary.security.controller.api;

 import java.io.IOException;
 import java.io.InputStream;
-import java.net.URI;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;

-import org.eclipse.jetty.http.HttpStatus;
 import org.springframework.context.annotation.Conditional;
 import org.springframework.core.io.InputStreamResource;
 import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;
-import org.springframework.web.servlet.mvc.support.RedirectAttributes;

 import io.swagger.v3.oas.annotations.Hidden;
 import io.swagger.v3.oas.annotations.Operation;
@@ -42,15 +40,19 @@ public class DatabaseController {
            summary = "Import a database backup file",
            description = "Uploads and imports a database backup SQL file.")
    @PostMapping(consumes = "multipart/form-data", value = "import-database")
-    public String importDatabase(
+    public ResponseEntity<?> importDatabase(
            @Parameter(description = "SQL file to import", required = true)
                    @RequestParam("fileInput")
-                    MultipartFile file,
-            RedirectAttributes redirectAttributes)
+                    MultipartFile file)
            throws IOException {
        if (file == null || file.isEmpty()) {
-            redirectAttributes.addAttribute("error", "fileNullOrEmpty");
-            return "redirect:/database";
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(
+                            java.util.Map.of(
+                                    "error",
+                                    "fileNullOrEmpty",
+                                    "message",
+                                    "File is null or empty"));
        }
        log.info("Received file: {}", file.getOriginalFilename());
        Path tempTemplatePath = Files.createTempFile("backup_", ".sql");
@@ -58,15 +60,31 @@ public class DatabaseController {
            Files.copy(in, tempTemplatePath, StandardCopyOption.REPLACE_EXISTING);
            boolean importSuccess = databaseService.importDatabaseFromUI(tempTemplatePath);
            if (importSuccess) {
-                redirectAttributes.addAttribute("infoMessage", "importIntoDatabaseSuccessed");
+                return ResponseEntity.ok(
+                        java.util.Map.of(
+                                "message",
+                                "importIntoDatabaseSuccessed",
+                                "description",
+                                "Database imported successfully"));
            } else {
-                redirectAttributes.addAttribute("error", "failedImportFile");
+                return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                        .body(
+                                java.util.Map.of(
+                                        "error",
+                                        "failedImportFile",
+                                        "message",
+                                        "Failed to import database file"));
            }
        } catch (Exception e) {
            log.error("Error importing database: {}", e.getMessage());
-            redirectAttributes.addAttribute("error", "failedImportFile");
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body(
+                            java.util.Map.of(
+                                    "error",
+                                    "failedImportFile",
+                                    "message",
+                                    "Failed to import database: " + e.getMessage()));
        }
-        return "redirect:/database";
    }

    @Hidden
@@ -74,11 +92,17 @@ public class DatabaseController {
            summary = "Import database backup by filename",
            description = "Imports a database backup file from the server using its file name.")
    @GetMapping("/import-database-file/{fileName}")
-    public String importDatabaseFromBackupUI(
+    public ResponseEntity<?> importDatabaseFromBackupUI(
            @Parameter(description = "Name of the file to import", required = true) @PathVariable
                    String fileName) {
        if (fileName == null || fileName.isEmpty()) {
-            return "redirect:/database?error=fileNullOrEmpty";
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(
+                            java.util.Map.of(
+                                    "error",
+                                    "fileNullOrEmpty",
+                                    "message",
+                                    "File name is null or empty"));
        }
        // Check if the file exists in the backup list
        boolean fileExists =
@@ -86,14 +110,31 @@ public class DatabaseController {
                        .anyMatch(backup -> backup.getFileName().equals(fileName));
        if (!fileExists) {
            log.error("File {} not found in backup list", fileName);
-            return "redirect:/database?error=fileNotFound";
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(
+                            java.util.Map.of(
+                                    "error",
+                                    "fileNotFound",
+                                    "message",
+                                    "File not found in backup list"));
        }
        log.info("Received file: {}", fileName);
        if (databaseService.importDatabaseFromUI(fileName)) {
            log.info("File {} imported to database", fileName);
-            return "redirect:/database?infoMessage=importIntoDatabaseSuccessed";
+            return ResponseEntity.ok(
+                    java.util.Map.of(
+                            "message",
+                            "importIntoDatabaseSuccessed",
+                            "description",
+                            "Database backup imported successfully"));
        }
-        return "redirect:/database?error=failedImportFile";
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(
+                        java.util.Map.of(
+                                "error",
+                                "failedImportFile",
+                                "message",
+                                "Failed to import database file"));
    }

    @Hidden
@@ -101,24 +142,42 @@ public class DatabaseController {
            summary = "Delete a database backup file",
            description = "Deletes a specified database backup file from the server.")
    @GetMapping("/delete/{fileName}")
-    public String deleteFile(
+    public ResponseEntity<?> deleteFile(
            @Parameter(description = "Name of the file to delete", required = true) @PathVariable
                    String fileName) {
        if (fileName == null || fileName.isEmpty()) {
-            throw new IllegalArgumentException("File must not be null or empty");
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(
+                            java.util.Map.of(
+                                    "error",
+                                    "invalidFileName",
+                                    "message",
+                                    "File must not be null or empty"));
        }
        try {
            if (databaseService.deleteBackupFile(fileName)) {
                log.info("Deleted file: {}", fileName);
+                return ResponseEntity.ok(java.util.Map.of("message", "File deleted successfully"));
            } else {
                log.error("Failed to delete file: {}", fileName);
-                return "redirect:/database?error=failedToDeleteFile";
+                return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                        .body(
+                                java.util.Map.of(
+                                        "error",
+                                        "failedToDeleteFile",
+                                        "message",
+                                        "Failed to delete backup file"));
            }
        } catch (IOException e) {
            log.error("Error deleting file: {}", e.getMessage());
-            return "redirect:/database?error=" + e.getMessage();
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body(
+                            java.util.Map.of(
+                                    "error",
+                                    "deleteError",
+                                    "message",
+                                    "Error deleting file: " + e.getMessage()));
        }
-        return "redirect:/database";
    }

    @Hidden
@@ -142,22 +201,29 @@ public class DatabaseController {
                    .body(resource);
        } catch (IOException e) {
            log.error("Error downloading file: {}", e.getMessage());
-            return ResponseEntity.status(HttpStatus.SEE_OTHER_303)
-                    .location(URI.create("/database?error=downloadFailed"))
-                    .build();
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body(
+                            java.util.Map.of(
+                                    "error",
+                                    "downloadFailed",
+                                    "message",
+                                    "Failed to download file: " + e.getMessage()));
        }
    }

    @Operation(
            summary = "Create a database backup",
-            description =
-                    "This endpoint triggers the creation of a database backup and redirects to the"
-                            + " database management page.")
+            description = "This endpoint triggers the creation of a database backup.")
    @GetMapping("/createDatabaseBackup")
-    public String createDatabaseBackup() {
+    public ResponseEntity<?> createDatabaseBackup() {
        log.info("Starting database backup creation...");
        databaseService.exportDatabase();
        log.info("Database backup successfully created.");
-        return "redirect:/database?infoMessage=backupCreated";
+        return ResponseEntity.ok(
+                java.util.Map.of(
+                        "message",
+                        "backupCreated",
+                        "description",
+                        "Database backup created successfully"));
    }
 }
@@ -1,10 +1,12 @@
 package stirling.software.proprietary.security.controller.api;

+import java.util.Map;
 import java.util.Optional;

+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.*;
-import org.springframework.web.servlet.view.RedirectView;

 import jakarta.transaction.Transactional;

@@ -30,98 +32,113 @@ public class TeamController {

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/create")
-    public RedirectView createTeam(@RequestParam("name") String name) {
+    public ResponseEntity<?> createTeam(@RequestParam("name") String name) {
        if (teamRepository.existsByNameIgnoreCase(name)) {
-            return new RedirectView("/teams?messageType=teamExists");
+            return ResponseEntity.status(HttpStatus.CONFLICT)
+                    .body(Map.of("error", "Team name already exists."));
        }
        Team team = new Team();
        team.setName(name);
        teamRepository.save(team);
-        return new RedirectView("/teams?messageType=teamCreated");
+        return ResponseEntity.ok(Map.of("message", "Team created successfully"));
    }

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/rename")
-    public RedirectView renameTeam(
+    public ResponseEntity<?> renameTeam(
            @RequestParam("teamId") Long teamId, @RequestParam("newName") String newName) {
        Optional<Team> existing = teamRepository.findById(teamId);
        if (existing.isEmpty()) {
-            return new RedirectView("/teams?messageType=teamNotFound");
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "Team not found."));
        }
        if (teamRepository.existsByNameIgnoreCase(newName)) {
-            return new RedirectView("/teams?messageType=teamNameExists");
+            return ResponseEntity.status(HttpStatus.CONFLICT)
+                    .body(Map.of("error", "Team name already exists."));
        }
        Team team = existing.get();

        // Prevent renaming the Internal team
        if (team.getName().equals(TeamService.INTERNAL_TEAM_NAME)) {
-            return new RedirectView("/teams?messageType=internalTeamNotAccessible");
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Cannot rename Internal team."));
        }

        team.setName(newName);
        teamRepository.save(team);
-        return new RedirectView("/teams?messageType=teamRenamed");
+        return ResponseEntity.ok(Map.of("message", "Team renamed successfully"));
    }

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/delete")
    @Transactional
-    public RedirectView deleteTeam(@RequestParam("teamId") Long teamId) {
+    public ResponseEntity<?> deleteTeam(@RequestParam("teamId") Long teamId) {
        Optional<Team> teamOpt = teamRepository.findById(teamId);
        if (teamOpt.isEmpty()) {
-            return new RedirectView("/teams?messageType=teamNotFound");
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "Team not found."));
        }

        Team team = teamOpt.get();

        // Prevent deleting the Internal team
        if (team.getName().equals(TeamService.INTERNAL_TEAM_NAME)) {
-            return new RedirectView("/teams?messageType=internalTeamNotAccessible");
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Cannot delete Internal team."));
        }

        long memberCount = userRepository.countByTeam(team);
        if (memberCount > 0) {
-            return new RedirectView("/teams?messageType=teamHasUsers");
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(
+                            Map.of(
+                                    "error",
+                                    "Team must be empty before deletion. Please remove all members first."));
        }

        teamRepository.delete(team);
-        return new RedirectView("/teams?messageType=teamDeleted");
+        return ResponseEntity.ok(Map.of("message", "Team deleted successfully"));
    }

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/addUser")
    @Transactional
-    public RedirectView addUserToTeam(
+    public ResponseEntity<?> addUserToTeam(
            @RequestParam("teamId") Long teamId, @RequestParam("userId") Long userId) {

        // Find the team
-        Team team =
-                teamRepository
-                        .findById(teamId)
-                        .orElseThrow(() -> new RuntimeException("Team not found"));
+        Optional<Team> teamOpt = teamRepository.findById(teamId);
+        if (teamOpt.isEmpty()) {
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "Team not found."));
+        }
+        Team team = teamOpt.get();

        // Prevent adding users to the Internal team
        if (team.getName().equals(TeamService.INTERNAL_TEAM_NAME)) {
-            return new RedirectView("/teams?error=internalTeamNotAccessible");
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Cannot add users to Internal team."));
        }

        // Find the user
-        User user =
-                userRepository
-                        .findById(userId)
-                        .orElseThrow(() -> new RuntimeException("User not found"));
+        Optional<User> userOpt = userRepository.findById(userId);
+        if (userOpt.isEmpty()) {
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "User not found."));
+        }
+        User user = userOpt.get();

        // Check if user is in the Internal team - prevent moving them
        if (user.getTeam() != null
                && user.getTeam().getName().equals(TeamService.INTERNAL_TEAM_NAME)) {
-            return new RedirectView("/teams/" + teamId + "?error=cannotMoveInternalUsers");
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Cannot move users from Internal team."));
        }

        // Assign user to team
        user.setTeam(team);
        userRepository.save(user);

-        // Redirect back to team details page
-        return new RedirectView("/teams/" + teamId + "?messageType=userAdded");
+        return ResponseEntity.ok(Map.of("message", "User added to team successfully"));
    }
 }
@@ -3,6 +3,7 @@ package stirling.software.proprietary.security.controller.api;
 import java.io.IOException;
 import java.security.Principal;
 import java.sql.SQLException;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -15,10 +16,7 @@ import org.springframework.security.core.session.SessionInformation;
 import org.springframework.security.core.userdetails.UserDetails;
 import org.springframework.security.oauth2.core.user.OAuth2User;
 import org.springframework.security.web.authentication.logout.SecurityContextLogoutHandler;
-import org.springframework.ui.Model;
 import org.springframework.web.bind.annotation.*;
-import org.springframework.web.servlet.mvc.support.RedirectAttributes;
-import org.springframework.web.servlet.view.RedirectView;

 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
@@ -38,6 +36,7 @@ import stirling.software.proprietary.security.model.User;
 import stirling.software.proprietary.security.model.api.user.UsernameAndPass;
 import stirling.software.proprietary.security.repository.TeamRepository;
 import stirling.software.proprietary.security.saml2.CustomSaml2AuthenticatedPrincipal;
+import stirling.software.proprietary.security.service.EmailService;
 import stirling.software.proprietary.security.service.TeamService;
 import stirling.software.proprietary.security.service.UserService;
 import stirling.software.proprietary.security.session.SessionPersistentRegistry;
@@ -53,125 +52,215 @@ public class UserController {
    private final ApplicationProperties applicationProperties;
    private final TeamRepository teamRepository;
    private final UserRepository userRepository;
+    private final Optional<EmailService> emailService;

    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
    @PostMapping("/register")
-    public String register(@ModelAttribute UsernameAndPass requestModel, Model model)
+    public ResponseEntity<?> register(@RequestBody UsernameAndPass usernameAndPass)
            throws SQLException, UnsupportedProviderException {
-        if (userService.usernameExistsIgnoreCase(requestModel.getUsername())) {
-            model.addAttribute("error", "Username already exists");
-            return "register";
-        }
        try {
+            log.debug("Registration attempt for user: {}", usernameAndPass.getUsername());
+
+            if (userService.usernameExistsIgnoreCase(usernameAndPass.getUsername())) {
+                log.warn(
+                        "Registration failed: username already exists: {}",
+                        usernameAndPass.getUsername());
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "User already exists"));
+            }
+
+            if (!userService.isUsernameValid(usernameAndPass.getUsername())) {
+                log.warn(
+                        "Registration failed: invalid username format: {}",
+                        usernameAndPass.getUsername());
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Invalid username format"));
+            }
+
+            if (usernameAndPass.getPassword() == null
+                    || usernameAndPass.getPassword().length() < 6) {
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Password must be at least 6 characters"));
+            }
+
            Team team = teamRepository.findByName(TeamService.DEFAULT_TEAM_NAME).orElse(null);
-            userService.saveUser(
-                    requestModel.getUsername(),
-                    requestModel.getPassword(),
-                    team,
-                    Role.USER.getRoleId(),
-                    false);
+            User user =
+                    userService.saveUser(
+                            usernameAndPass.getUsername(),
+                            usernameAndPass.getPassword(),
+                            team,
+                            Role.USER.getRoleId(),
+                            false);
+
+            log.info("User registered successfully: {}", usernameAndPass.getUsername());
+
+            return ResponseEntity.status(HttpStatus.CREATED)
+                    .body(
+                            Map.of(
+                                    "user",
+                                    buildUserResponse(user),
+                                    "message",
+                                    "Account created successfully. Please log in."));
+
        } catch (IllegalArgumentException e) {
-            return "redirect:/login?messageType=invalidUsername";
+            log.error("Registration validation error: {}", e.getMessage());
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", e.getMessage()));
+        } catch (Exception e) {
+            log.error("Registration error for user: {}", usernameAndPass.getUsername(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body(Map.of("error", "Registration failed: " + e.getMessage()));
        }
-        return "redirect:/login?registered=true";
+    }
+
+    /**
+     * Helper method to build user response object
+     *
+     * @param user User entity
+     * @return Map containing user information
+     */
+    private Map<String, Object> buildUserResponse(User user) {
+        Map<String, Object> userMap = new HashMap<>();
+        userMap.put("id", user.getId());
+        userMap.put("email", user.getUsername()); // Use username as email
+        userMap.put("username", user.getUsername());
+        userMap.put("role", user.getRolesAsString());
+        userMap.put("enabled", user.isEnabled());
+
+        // Add metadata for OAuth compatibility
+        Map<String, Object> appMetadata = new HashMap<>();
+        appMetadata.put("provider", user.getAuthenticationType()); // Default to email provider
+        userMap.put("app_metadata", appMetadata);
+
+        return userMap;
    }

    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
    @PostMapping("/change-username")
-    public RedirectView changeUsername(
+    public ResponseEntity<?> changeUsername(
            Principal principal,
            @RequestParam(name = "currentPasswordChangeUsername") String currentPassword,
            @RequestParam(name = "newUsername") String newUsername,
            HttpServletRequest request,
-            HttpServletResponse response,
-            RedirectAttributes redirectAttributes)
+            HttpServletResponse response)
            throws IOException, SQLException, UnsupportedProviderException {
        if (!userService.isUsernameValid(newUsername)) {
-            return new RedirectView("/account?messageType=invalidUsername", true);
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "invalidUsername", "message", "Invalid username format"));
        }
        if (principal == null) {
-            return new RedirectView("/account?messageType=notAuthenticated", true);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "notAuthenticated", "message", "User not authenticated"));
        }
        // The username MUST be unique when renaming
        Optional<User> userOpt = userService.findByUsername(principal.getName());
        if (userOpt == null || userOpt.isEmpty()) {
-            return new RedirectView("/account?messageType=userNotFound", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "userNotFound", "message", "User not found"));
        }
        User user = userOpt.get();
        if (user.getUsername().equals(newUsername)) {
-            return new RedirectView("/account?messageType=usernameExists", true);
+            return ResponseEntity.status(HttpStatus.CONFLICT)
+                    .body(Map.of("error", "usernameExists", "message", "Username already in use"));
        }
        if (!userService.isPasswordCorrect(user, currentPassword)) {
-            return new RedirectView("/account?messageType=incorrectPassword", true);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "incorrectPassword", "message", "Incorrect password"));
        }
        if (!user.getUsername().equals(newUsername) && userService.usernameExists(newUsername)) {
-            return new RedirectView("/account?messageType=usernameExists", true);
+            return ResponseEntity.status(HttpStatus.CONFLICT)
+                    .body(Map.of("error", "usernameExists", "message", "Username already exists"));
        }
        if (newUsername != null && newUsername.length() > 0) {
            try {
                userService.changeUsername(user, newUsername);
            } catch (IllegalArgumentException e) {
-                return new RedirectView("/account?messageType=invalidUsername", true);
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(
+                                Map.of(
+                                        "error",
+                                        "invalidUsername",
+                                        "message",
+                                        "Invalid username format"));
            }
        }
        // Logout using Spring's utility
        new SecurityContextLogoutHandler().logout(request, response, null);
-        return new RedirectView(LOGIN_MESSAGETYPE_CREDSUPDATED, true);
+        return ResponseEntity.ok(
+                Map.of(
+                        "message",
+                        "credsUpdated",
+                        "description",
+                        "Username changed successfully. Please log in again."));
    }

    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
    @PostMapping("/change-password-on-login")
-    public RedirectView changePasswordOnLogin(
+    public ResponseEntity<?> changePasswordOnLogin(
            Principal principal,
            @RequestParam(name = "currentPassword") String currentPassword,
            @RequestParam(name = "newPassword") String newPassword,
            HttpServletRequest request,
-            HttpServletResponse response,
-            RedirectAttributes redirectAttributes)
+            HttpServletResponse response)
            throws SQLException, UnsupportedProviderException {
        if (principal == null) {
-            return new RedirectView("/change-creds?messageType=notAuthenticated", true);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "notAuthenticated", "message", "User not authenticated"));
        }
        Optional<User> userOpt = userService.findByUsernameIgnoreCase(principal.getName());
        if (userOpt.isEmpty()) {
-            return new RedirectView("/change-creds?messageType=userNotFound", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "userNotFound", "message", "User not found"));
        }
        User user = userOpt.get();
        if (!userService.isPasswordCorrect(user, currentPassword)) {
-            return new RedirectView("/change-creds?messageType=incorrectPassword", true);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "incorrectPassword", "message", "Incorrect password"));
        }
        userService.changePassword(user, newPassword);
        userService.changeFirstUse(user, false);
        // Logout using Spring's utility
        new SecurityContextLogoutHandler().logout(request, response, null);
-        return new RedirectView(LOGIN_MESSAGETYPE_CREDSUPDATED, true);
+        return ResponseEntity.ok(
+                Map.of(
+                        "message",
+                        "credsUpdated",
+                        "description",
+                        "Password changed successfully. Please log in again."));
    }

    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
    @PostMapping("/change-password")
-    public RedirectView changePassword(
+    public ResponseEntity<?> changePassword(
            Principal principal,
            @RequestParam(name = "currentPassword") String currentPassword,
            @RequestParam(name = "newPassword") String newPassword,
            HttpServletRequest request,
-            HttpServletResponse response,
-            RedirectAttributes redirectAttributes)
+            HttpServletResponse response)
            throws SQLException, UnsupportedProviderException {
        if (principal == null) {
-            return new RedirectView("/account?messageType=notAuthenticated", true);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "notAuthenticated", "message", "User not authenticated"));
        }
        Optional<User> userOpt = userService.findByUsernameIgnoreCase(principal.getName());
        if (userOpt.isEmpty()) {
-            return new RedirectView("/account?messageType=userNotFound", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "userNotFound", "message", "User not found"));
        }
        User user = userOpt.get();
        if (!userService.isPasswordCorrect(user, currentPassword)) {
-            return new RedirectView("/account?messageType=incorrectPassword", true);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body(Map.of("error", "incorrectPassword", "message", "Incorrect password"));
        }
        userService.changePassword(user, newPassword);
        // Logout using Spring's utility
        new SecurityContextLogoutHandler().logout(request, response, null);
-        return new RedirectView(LOGIN_MESSAGETYPE_CREDSUPDATED, true);
+        return ResponseEntity.ok(
+                Map.of(
+                        "message",
+                        "credsUpdated",
+                        "description",
+                        "Password changed successfully. Please log in again."));
    }

    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
@@ -189,23 +278,23 @@ public class UserController {
     *     </ul>
     *     Keys not listed above will be ignored.
     * @param principal The currently authenticated user.
-     * @return A redirect string to the account page after updating the settings.
+     * @return A ResponseEntity with success or error information.
     * @throws SQLException If a database error occurs.
     * @throws UnsupportedProviderException If the operation is not supported for the user's
     *     provider.
     */
-    public String updateUserSettings(@RequestBody Map<String, String> updates, Principal principal)
+    public ResponseEntity<?> updateUserSettings(
+            @RequestBody Map<String, String> updates, Principal principal)
            throws SQLException, UnsupportedProviderException {
        log.debug("Processed updates: {}", updates);
        // Assuming you have a method in userService to update the settings for a user
        userService.updateUserSettings(principal.getName(), updates);
-        // Redirect to a page of your choice after updating
-        return "redirect:/account";
+        return ResponseEntity.ok(Map.of("message", "Settings updated successfully"));
    }

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/admin/saveUser")
-    public RedirectView saveUser(
+    public ResponseEntity<?> saveUser(
            @RequestParam(name = "username", required = true) String username,
            @RequestParam(name = "password", required = false) String password,
            @RequestParam(name = "role") String role,
@@ -215,33 +304,42 @@ public class UserController {
                    boolean forceChange)
            throws IllegalArgumentException, SQLException, UnsupportedProviderException {
        if (!userService.isUsernameValid(username)) {
-            return new RedirectView("/adminSettings?messageType=invalidUsername", true);
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(
+                            Map.of(
+                                    "error",
+                                    "Invalid username format. Username must be 3-50 characters."));
        }
        if (applicationProperties.getPremium().isEnabled()
                && applicationProperties.getPremium().getMaxUsers()
                        <= userService.getTotalUsersCount()) {
-            return new RedirectView("/adminSettings?messageType=maxUsersReached", true);
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Maximum number of users reached for your license."));
        }
        Optional<User> userOpt = userService.findByUsernameIgnoreCase(username);
        if (userOpt.isPresent()) {
            User user = userOpt.get();
            if (user.getUsername().equalsIgnoreCase(username)) {
-                return new RedirectView("/adminSettings?messageType=usernameExists", true);
+                return ResponseEntity.status(HttpStatus.CONFLICT)
+                        .body(Map.of("error", "Username already exists."));
            }
        }
        if (userService.usernameExistsIgnoreCase(username)) {
-            return new RedirectView("/adminSettings?messageType=usernameExists", true);
+            return ResponseEntity.status(HttpStatus.CONFLICT)
+                    .body(Map.of("error", "Username already exists."));
        }
        try {
            // Validate the role
            Role roleEnum = Role.fromString(role);
            if (roleEnum == Role.INTERNAL_API_USER) {
                // If the role is INTERNAL_API_USER, reject the request
-                return new RedirectView("/adminSettings?messageType=invalidRole", true);
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Cannot assign INTERNAL_API_USER role."));
            }
        } catch (IllegalArgumentException e) {
-            // If the role ID is not valid, redirect with an error message
-            return new RedirectView("/adminSettings?messageType=invalidRole", true);
+            // If the role ID is not valid, return error
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Invalid role specified."));
        }

        // Use teamId if provided, otherwise use default team
@@ -257,28 +355,144 @@ public class UserController {
            Team selectedTeam = teamRepository.findById(effectiveTeamId).orElse(null);
            if (selectedTeam != null
                    && TeamService.INTERNAL_TEAM_NAME.equals(selectedTeam.getName())) {
-                return new RedirectView(
-                        "/adminSettings?messageType=internalTeamNotAccessible", true);
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Cannot assign users to Internal team."));
            }
        }

        if (authType.equalsIgnoreCase(AuthenticationType.SSO.toString())) {
            userService.saveUser(username, AuthenticationType.SSO, effectiveTeamId, role);
        } else {
-            if (password.isBlank()) {
-                return new RedirectView("/adminSettings?messageType=invalidPassword", true);
+            if (password == null || password.isBlank()) {
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Password is required."));
+            }
+            if (password.length() < 6) {
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Password must be at least 6 characters."));
            }
            userService.saveUser(username, password, effectiveTeamId, role, forceChange);
        }
-        return new RedirectView(
-                "/adminSettings", // Redirect to account page after adding the user
-                true);
+        return ResponseEntity.ok(Map.of("message", "User created successfully"));
+    }
+
+    @PreAuthorize("hasRole('ROLE_ADMIN')")
+    @PostMapping("/admin/inviteUsers")
+    public ResponseEntity<?> inviteUsers(
+            @RequestParam(name = "emails", required = true) String emails,
+            @RequestParam(name = "role", defaultValue = "ROLE_USER") String role,
+            @RequestParam(name = "teamId", required = false) Long teamId)
+            throws SQLException, UnsupportedProviderException {
+
+        // Check if email invites are enabled
+        if (!applicationProperties.getMail().isEnableInvites()) {
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Email invites are not enabled"));
+        }
+
+        // Check if email service is available
+        if (!emailService.isPresent()) {
+            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                    .body(
+                            Map.of(
+                                    "error",
+                                    "Email service is not configured. Please configure SMTP settings."));
+        }
+
+        // Parse comma-separated email addresses
+        String[] emailArray = emails.split(",");
+        if (emailArray.length == 0) {
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "At least one email address is required"));
+        }
+
+        // Check license limits
+        if (applicationProperties.getPremium().isEnabled()) {
+            long currentUserCount = userService.getTotalUsersCount();
+            int maxUsers = applicationProperties.getPremium().getMaxUsers();
+            long availableSlots = maxUsers - currentUserCount;
+            if (availableSlots < emailArray.length) {
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(
+                                Map.of(
+                                        "error",
+                                        "Not enough user slots available. Available: "
+                                                + availableSlots
+                                                + ", Requested: "
+                                                + emailArray.length));
+            }
+        }
+
+        // Validate role
+        try {
+            Role roleEnum = Role.fromString(role);
+            if (roleEnum == Role.INTERNAL_API_USER) {
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Cannot assign INTERNAL_API_USER role"));
+            }
+        } catch (IllegalArgumentException e) {
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Invalid role specified"));
+        }
+
+        // Determine team
+        Long effectiveTeamId = teamId;
+        if (effectiveTeamId == null) {
+            Team defaultTeam =
+                    teamRepository.findByName(TeamService.DEFAULT_TEAM_NAME).orElse(null);
+            if (defaultTeam != null) {
+                effectiveTeamId = defaultTeam.getId();
+            }
+        } else {
+            Team selectedTeam = teamRepository.findById(effectiveTeamId).orElse(null);
+            if (selectedTeam != null
+                    && TeamService.INTERNAL_TEAM_NAME.equals(selectedTeam.getName())) {
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Cannot assign users to Internal team"));
+            }
+        }
+
+        int successCount = 0;
+        int failureCount = 0;
+        StringBuilder errors = new StringBuilder();
+
+        // Process each email
+        for (String email : emailArray) {
+            email = email.trim();
+            if (email.isEmpty()) {
+                continue;
+            }
+
+            InviteResult result = processEmailInvite(email, effectiveTeamId, role);
+            if (result.isSuccess()) {
+                successCount++;
+            } else {
+                failureCount++;
+                errors.append(result.getErrorMessage()).append("; ");
+            }
+        }
+
+        Map<String, Object> response = new HashMap<>();
+        response.put("successCount", successCount);
+        response.put("failureCount", failureCount);
+
+        if (failureCount > 0) {
+            response.put("errors", errors.toString());
+        }
+
+        if (successCount > 0) {
+            response.put("message", successCount + " user(s) invited successfully");
+            return ResponseEntity.ok(response);
+        } else {
+            response.put("error", "Failed to invite any users");
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response);
+        }
    }

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/admin/changeRole")
    @Transactional
-    public RedirectView changeRole(
+    public ResponseEntity<?> changeRole(
            @RequestParam(name = "username") String username,
            @RequestParam(name = "role") String role,
            @RequestParam(name = "teamId", required = false) Long teamId,
@@ -286,27 +500,32 @@ public class UserController {
            throws SQLException, UnsupportedProviderException {
        Optional<User> userOpt = userService.findByUsernameIgnoreCase(username);
        if (!userOpt.isPresent()) {
-            return new RedirectView("/adminSettings?messageType=userNotFound", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "User not found."));
        }
        if (!userService.usernameExistsIgnoreCase(username)) {
-            return new RedirectView("/adminSettings?messageType=userNotFound", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "User not found."));
        }
        // Get the currently authenticated username
        String currentUsername = authentication.getName();
        // Check if the provided username matches the current session's username
        if (currentUsername.equalsIgnoreCase(username)) {
-            return new RedirectView("/adminSettings?messageType=downgradeCurrentUser", true);
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Cannot change your own role."));
        }
        try {
            // Validate the role
            Role roleEnum = Role.fromString(role);
            if (roleEnum == Role.INTERNAL_API_USER) {
                // If the role is INTERNAL_API_USER, reject the request
-                return new RedirectView("/adminSettings?messageType=invalidRole", true);
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(Map.of("error", "Cannot assign INTERNAL_API_USER role."));
            }
        } catch (IllegalArgumentException e) {
-            // If the role ID is not valid, redirect with an error message
-            return new RedirectView("/adminSettings?messageType=invalidRole", true);
+            // If the role ID is not valid, return error
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Invalid role specified."));
        }
        User user = userOpt.get();

@@ -316,15 +535,15 @@ public class UserController {
            if (team != null) {
                // Prevent assigning to Internal team
                if (TeamService.INTERNAL_TEAM_NAME.equals(team.getName())) {
-                    return new RedirectView(
-                            "/adminSettings?messageType=internalTeamNotAccessible", true);
+                    return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                            .body(Map.of("error", "Cannot assign users to Internal team."));
                }

                // Prevent moving users from Internal team
                if (user.getTeam() != null
                        && TeamService.INTERNAL_TEAM_NAME.equals(user.getTeam().getName())) {
-                    return new RedirectView(
-                            "/adminSettings?messageType=cannotMoveInternalUsers", true);
+                    return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                            .body(Map.of("error", "Cannot move users from Internal team."));
                }

                user.setTeam(team);
@@ -333,30 +552,31 @@ public class UserController {
        }

        userService.changeRole(user, role);
-        return new RedirectView(
-                "/adminSettings", // Redirect to account page after adding the user
-                true);
+        return ResponseEntity.ok(Map.of("message", "User role updated successfully"));
    }

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/admin/changeUserEnabled/{username}")
-    public RedirectView changeUserEnabled(
+    public ResponseEntity<?> changeUserEnabled(
            @PathVariable("username") String username,
            @RequestParam("enabled") boolean enabled,
            Authentication authentication)
            throws SQLException, UnsupportedProviderException {
        Optional<User> userOpt = userService.findByUsernameIgnoreCase(username);
        if (userOpt.isEmpty()) {
-            return new RedirectView("/adminSettings?messageType=userNotFound", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "User not found."));
        }
        if (!userService.usernameExistsIgnoreCase(username)) {
-            return new RedirectView("/adminSettings?messageType=userNotFound", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "User not found."));
        }
        // Get the currently authenticated username
        String currentUsername = authentication.getName();
        // Check if the provided username matches the current session's username
        if (currentUsername.equalsIgnoreCase(username)) {
-            return new RedirectView("/adminSettings?messageType=disabledCurrentUser", true);
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Cannot disable your own account."));
        }
        User user = userOpt.get();
        userService.changeUserEnabled(user, enabled);
@@ -383,23 +603,24 @@ public class UserController {
                }
            }
        }
-        return new RedirectView(
-                "/adminSettings", // Redirect to account page after adding the user
-                true);
+        return ResponseEntity.ok(
+                Map.of("message", "User " + (enabled ? "enabled" : "disabled") + " successfully"));
    }

    @PreAuthorize("hasRole('ROLE_ADMIN')")
    @PostMapping("/admin/deleteUser/{username}")
-    public RedirectView deleteUser(
+    public ResponseEntity<?> deleteUser(
            @PathVariable("username") String username, Authentication authentication) {
        if (!userService.usernameExistsIgnoreCase(username)) {
-            return new RedirectView("/adminSettings?messageType=deleteUsernameExists", true);
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body(Map.of("error", "User not found."));
        }
        // Get the currently authenticated username
        String currentUsername = authentication.getName();
        // Check if the provided username matches the current session's username
        if (currentUsername.equalsIgnoreCase(username)) {
-            return new RedirectView("/adminSettings?messageType=deleteCurrentUser", true);
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(Map.of("error", "Cannot delete your own account."));
        }
        // Invalidate all sessions before deleting the user
        List<SessionInformation> sessionsInformations =
@@ -409,7 +630,7 @@ public class UserController {
            sessionRegistry.removeSessionInformation(sessionsInformation.getSessionId());
        }
        userService.deleteUser(username);
-        return new RedirectView("/adminSettings", true);
+        return ResponseEntity.ok(Map.of("message", "User deleted successfully"));
    }

    @PreAuthorize("!hasAuthority('ROLE_DEMO_USER')")
@@ -440,4 +661,73 @@ public class UserController {
        }
        return ResponseEntity.ok(apiKey);
    }
+
+    /**
+     * Helper method to process a single email invitation.
+     *
+     * @param email The email address to invite
+     * @param teamId The team ID to assign the user to
+     * @param role The role to assign to the user
+     * @return InviteResult containing success status and optional error message
+     */
+    private InviteResult processEmailInvite(String email, Long teamId, String role) {
+        try {
+            // Validate email format (basic check)
+            if (!email.contains("@") || !email.contains(".")) {
+                return InviteResult.failure(email + ": Invalid email format");
+            }
+
+            // Check if user already exists
+            if (userService.usernameExistsIgnoreCase(email)) {
+                return InviteResult.failure(email + ": User already exists");
+            }
+
+            // Generate random password
+            String temporaryPassword = java.util.UUID.randomUUID().toString().substring(0, 12);
+
+            // Create user with forceChange=true
+            userService.saveUser(email, temporaryPassword, teamId, role, true);
+
+            // Send invite email
+            try {
+                emailService.get().sendInviteEmail(email, email, temporaryPassword);
+                log.info("Sent invite email to: {}", email);
+                return InviteResult.success();
+            } catch (Exception emailEx) {
+                log.error("Failed to send invite email to {}: {}", email, emailEx.getMessage());
+                return InviteResult.failure(email + ": User created but email failed to send");
+            }
+
+        } catch (Exception e) {
+            log.error("Failed to invite user {}: {}", email, e.getMessage());
+            return InviteResult.failure(email + ": " + e.getMessage());
+        }
+    }
+
+    /** Result object for individual email invite processing. */
+    private static class InviteResult {
+        private final boolean success;
+        private final String errorMessage;
+
+        private InviteResult(boolean success, String errorMessage) {
+            this.success = success;
+            this.errorMessage = errorMessage;
+        }
+
+        static InviteResult success() {
+            return new InviteResult(true, null);
+        }
+
+        static InviteResult failure(String errorMessage) {
+            return new InviteResult(false, errorMessage);
+        }
+
+        boolean isSuccess() {
+            return success;
+        }
+
+        String getErrorMessage() {
+            return errorMessage;
+        }
+    }
 }
@@ -22,6 +22,8 @@ public interface UserRepository extends JpaRepository<User, Long> {

    Optional<User> findByApiKey(String apiKey);

+    Optional<User> findBySsoProviderAndSsoProviderId(String ssoProvider, String ssoProviderId);
+
    List<User> findByAuthenticationTypeIgnoreCase(String authenticationType);

    @Query("SELECT u FROM User u WHERE u.team IS NULL")
@@ -1,77 +0,0 @@
-package stirling.software.proprietary.security.filter;
-
-import java.io.IOException;
-import java.text.SimpleDateFormat;
-import java.util.Date;
-import java.util.Optional;
-
-import org.springframework.context.annotation.Lazy;
-import org.springframework.security.core.Authentication;
-import org.springframework.security.core.context.SecurityContextHolder;
-import org.springframework.stereotype.Component;
-import org.springframework.web.filter.OncePerRequestFilter;
-
-import jakarta.servlet.FilterChain;
-import jakarta.servlet.ServletException;
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;
-import jakarta.servlet.http.HttpSession;
-
-import lombok.extern.slf4j.Slf4j;
-
-import stirling.software.common.util.RequestUriUtils;
-import stirling.software.proprietary.security.model.User;
-import stirling.software.proprietary.security.service.UserService;
-
-@Slf4j
-@Component
-public class FirstLoginFilter extends OncePerRequestFilter {
-
-    @Lazy private final UserService userService;
-
-    public FirstLoginFilter(@Lazy UserService userService) {
-        this.userService = userService;
-    }
-
-    @Override
-    protected void doFilterInternal(
-            HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
-            throws ServletException, IOException {
-        String method = request.getMethod();
-        String requestURI = request.getRequestURI();
-        String contextPath = request.getContextPath();
-        // Check if the request is for static resources
-        boolean isStaticResource = RequestUriUtils.isStaticResource(contextPath, requestURI);
-        // If it's a static resource, just continue the filter chain and skip the logic below
-        if (isStaticResource) {
-            filterChain.doFilter(request, response);
-            return;
-        }
-        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
-        if (authentication != null && authentication.isAuthenticated()) {
-            Optional<User> user = userService.findByUsernameIgnoreCase(authentication.getName());
-            if ("GET".equalsIgnoreCase(method)
-                    && user.isPresent()
-                    && user.get().isFirstLogin()
-                    && !(contextPath + "/change-creds").equals(requestURI)) {
-                response.sendRedirect(contextPath + "/change-creds");
-                return;
-            }
-        }
-        if (log.isDebugEnabled()) {
-            HttpSession session = request.getSession(true);
-            SimpleDateFormat timeFormat = new SimpleDateFormat("HH:mm:ss");
-            String creationTime = timeFormat.format(new Date(session.getCreationTime()));
-            log.debug(
-                    "Request Info - New: {}, creationTimeSession {}, ID:  {}, IP: {}, User-Agent: {}, Referer: {}, Request URL: {}",
-                    session.isNew(),
-                    creationTime,
-                    session.getId(),
-                    request.getRemoteAddr(),
-                    request.getHeader("User-Agent"),
-                    request.getHeader("Referer"),
-                    request.getRequestURL().toString());
-        }
-        filterChain.doFilter(request, response);
-    }
-}
@@ -1,8 +1,9 @@
 package stirling.software.proprietary.security.filter;

 import static stirling.software.common.util.RequestUriUtils.isStaticResource;
-import static stirling.software.proprietary.security.model.AuthenticationType.*;
+import static stirling.software.proprietary.security.model.AuthenticationType.OAUTH2;
 import static stirling.software.proprietary.security.model.AuthenticationType.SAML2;
+import static stirling.software.proprietary.security.model.AuthenticationType.WEB;

 import java.io.IOException;
 import java.sql.SQLException;
@@ -75,29 +76,60 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
            String jwtToken = jwtService.extractToken(request);

            if (jwtToken == null) {
-                // Any unauthenticated requests should redirect to /login
+                // Allow specific auth endpoints to pass through without JWT
                String requestURI = request.getRequestURI();
                String contextPath = request.getContextPath();

-                if (!requestURI.startsWith(contextPath + "/login")) {
-                    response.sendRedirect("/login");
+                // Public auth endpoints that don't require JWT
+                boolean isPublicAuthEndpoint =
+                        requestURI.startsWith(contextPath + "/login")
+                                || requestURI.startsWith(contextPath + "/signup")
+                                || requestURI.startsWith(contextPath + "/auth/")
+                                || requestURI.startsWith(contextPath + "/oauth2")
+                                || requestURI.startsWith(contextPath + "/api/v1/auth/login")
+                                || requestURI.startsWith(contextPath + "/api/v1/auth/register")
+                                || requestURI.startsWith(contextPath + "/api/v1/auth/refresh");
+
+                if (!isPublicAuthEndpoint) {
+                    // For API requests, return 401 JSON
+                    String acceptHeader = request.getHeader("Accept");
+                    if (requestURI.startsWith(contextPath + "/api/")
+                            || (acceptHeader != null
+                                    && acceptHeader.contains("application/json"))) {
+                        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
+                        response.setContentType("application/json");
+                        response.getWriter().write("{\"error\":\"Authentication required\"}");
+                        return;
+                    }
+
+                    // For HTML requests (SPA routes), let React Router handle it (serve
+                    // index.html)
+                    filterChain.doFilter(request, response);
                    return;
                }
+
+                // For public auth endpoints without JWT, continue to the endpoint
+                filterChain.doFilter(request, response);
+                return;
            }

            try {
+                log.debug("Validating JWT token");
                jwtService.validateToken(jwtToken);
+                log.debug("JWT token validated successfully");
            } catch (AuthenticationFailureException e) {
-                jwtService.clearToken(response);
+                log.warn("JWT validation failed: {}", e.getMessage());
                handleAuthenticationFailure(request, response, e);
                return;
            }

            Map<String, Object> claims = jwtService.extractClaims(jwtToken);
            String tokenUsername = claims.get("sub").toString();
+            log.debug("JWT token username: {}", tokenUsername);

            try {
                authenticate(request, claims);
+                log.debug("Authentication successful for user: {}", tokenUsername);
            } catch (SQLException | UnsupportedProviderException e) {
                log.error("Error processing user authentication for user: {}", tokenUsername, e);
                handleAuthenticationFailure(
@@ -175,21 +207,26 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
    private void processUserAuthenticationType(Map<String, Object> claims, String username)
            throws SQLException, UnsupportedProviderException {
        AuthenticationType authenticationType =
-                AuthenticationType.valueOf(claims.getOrDefault("authType", WEB).toString());
+                AuthenticationType.valueOf(
+                        claims.getOrDefault("authType", WEB).toString().toUpperCase());
        log.debug("Processing {} login for {} user", authenticationType, username);

        switch (authenticationType) {
            case OAUTH2 -> {
                ApplicationProperties.Security.OAUTH2 oauth2Properties =
                        securityProperties.getOauth2();
+                // Provider IDs should already be set during initial authentication
+                // Pass null here since this is validating an existing JWT token
                userService.processSSOPostLogin(
-                        username, oauth2Properties.getAutoCreateUser(), OAUTH2);
+                        username, null, null, oauth2Properties.getAutoCreateUser(), OAUTH2);
            }
            case SAML2 -> {
                ApplicationProperties.Security.SAML2 saml2Properties =
                        securityProperties.getSaml2();
+                // Provider IDs should already be set during initial authentication
+                // Pass null here since this is validating an existing JWT token
                userService.processSSOPostLogin(
-                        username, saml2Properties.getAutoCreateUser(), SAML2);
+                        username, null, null, saml2Properties.getAutoCreateUser(), SAML2);
            }
        }
    }
@@ -236,6 +236,10 @@ public class UserAuthenticationFilter extends OncePerRequestFilter {
            contextPath + "/pdfjs/",
            contextPath + "/pdfjs-legacy/",
            contextPath + "/api/v1/info/status",
+            contextPath + "/api/v1/auth/login",
+            contextPath + "/api/v1/auth/register",
+            contextPath + "/api/v1/auth/refresh",
+            contextPath + "/api/v1/auth/me",
            contextPath + "/site.webmanifest"
        };

@@ -1,12 +1,15 @@
 package stirling.software.proprietary.security.model;

 import java.io.Serializable;
+import java.time.LocalDateTime;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
 import java.util.stream.Collectors;

+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.UpdateTimestamp;
 import org.springframework.security.core.userdetails.UserDetails;

 import com.fasterxml.jackson.annotation.JsonIgnore;
@@ -59,12 +62,17 @@ public class User implements UserDetails, Serializable {
    @Column(name = "authenticationtype")
    private String authenticationType;

+    @Column(name = "sso_provider_id")
+    private String ssoProviderId;
+
+    @Column(name = "sso_provider")
+    private String ssoProvider;
+
    @OneToMany(fetch = FetchType.EAGER, cascade = CascadeType.ALL, mappedBy = "user")
    private Set<Authority> authorities = new HashSet<>();

    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "team_id")
-    @JsonIgnore
    private Team team;

    @ElementCollection
@@ -72,8 +80,17 @@ public class User implements UserDetails, Serializable {
    @Lob
    @Column(name = "setting_value", columnDefinition = "text")
    @CollectionTable(name = "user_settings", joinColumns = @JoinColumn(name = "user_id"))
+    @JsonIgnore
    private Map<String, String> settings = new HashMap<>(); // Key-value pairs of settings.

+    @CreationTimestamp
+    @Column(name = "created_at", updatable = false)
+    private LocalDateTime createdAt;
+
+    @UpdateTimestamp
+    @Column(name = "updated_at")
+    private LocalDateTime updatedAt;
+
    public String getRoleName() {
        return Role.getRoleNameByRoleId(getRolesAsString());
    }
@@ -10,6 +10,7 @@ import java.util.Map;
 import org.springframework.security.authentication.LockedException;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
 import org.springframework.security.oauth2.core.user.OAuth2User;
 import org.springframework.security.web.authentication.SavedRequestAwareAuthenticationSuccessHandler;
 import org.springframework.security.web.savedrequest.SavedRequest;
@@ -72,12 +73,6 @@ public class CustomOAuth2AuthenticationSuccessHandler
                throw new LockedException(
                        "Your account has been locked due to too many failed login attempts.");
            }
-            if (jwtService.isJwtEnabled()) {
-                String jwt =
-                        jwtService.generateToken(
-                                authentication, Map.of("authType", AuthenticationType.OAUTH2));
-                jwtService.addToken(response, jwt);
-            }
            if (userService.isUserDisabled(username)) {
                getRedirectStrategy()
                        .sendRedirect(request, response, "/logout?userIsDisabled=true");
@@ -98,14 +93,95 @@ public class CustomOAuth2AuthenticationSuccessHandler
                    response.sendRedirect(contextPath + "/logout?oAuth2AdminBlockedUser=true");
                    return;
                }
-                if (principal instanceof OAuth2User) {
+                if (principal instanceof OAuth2User oAuth2User) {
+                    // Extract SSO provider information from OAuth2User
+                    String ssoProviderId = oAuth2User.getAttribute("sub"); // OIDC ID
+                    // Extract provider from authentication - need to get it from the token/request
+                    // For now, we'll extract it in a more generic way
+                    String ssoProvider = extractProviderFromAuthentication(authentication);
+
                    userService.processSSOPostLogin(
-                            username, oauth2Properties.getAutoCreateUser(), OAUTH2);
+                            username,
+                            ssoProviderId,
+                            ssoProvider,
+                            oauth2Properties.getAutoCreateUser(),
+                            OAUTH2);
+                }
+
+                // Generate JWT if v2 is enabled
+                if (jwtService.isJwtEnabled()) {
+                    String jwt =
+                            jwtService.generateToken(
+                                    authentication, Map.of("authType", AuthenticationType.OAUTH2));
+
+                    // Build context-aware redirect URL based on the original request
+                    String redirectUrl = buildContextAwareRedirectUrl(request, contextPath, jwt);
+
+                    response.sendRedirect(redirectUrl);
+                } else {
+                    // v1: redirect directly to home
+                    response.sendRedirect(contextPath + "/");
                }
-                response.sendRedirect(contextPath + "/");
            } catch (IllegalArgumentException | SQLException | UnsupportedProviderException e) {
                response.sendRedirect(contextPath + "/logout?invalidUsername=true");
            }
        }
    }
+
+    /**
+     * Extracts the OAuth2 provider registration ID from the authentication object.
+     *
+     * @param authentication The authentication object
+     * @return The provider registration ID (e.g., "google", "github"), or null if not available
+     */
+    private String extractProviderFromAuthentication(Authentication authentication) {
+        if (authentication instanceof OAuth2AuthenticationToken oauth2Token) {
+            return oauth2Token.getAuthorizedClientRegistrationId();
+        }
+        return null;
+    }
+
+    /**
+     * Builds a context-aware redirect URL based on the request's origin
+     *
+     * @param request The HTTP request
+     * @param contextPath The application context path
+     * @param jwt The JWT token to include
+     * @return The appropriate redirect URL
+     */
+    private String buildContextAwareRedirectUrl(
+            HttpServletRequest request, String contextPath, String jwt) {
+        // Try to get the origin from the Referer header first
+        String referer = request.getHeader("Referer");
+        if (referer != null && !referer.isEmpty()) {
+            try {
+                java.net.URL refererUrl = new java.net.URL(referer);
+                String origin = refererUrl.getProtocol() + "://" + refererUrl.getHost();
+                if (refererUrl.getPort() != -1
+                        && refererUrl.getPort() != 80
+                        && refererUrl.getPort() != 443) {
+                    origin += ":" + refererUrl.getPort();
+                }
+                return origin + "/auth/callback#access_token=" + jwt;
+            } catch (java.net.MalformedURLException e) {
+                // Fall back to other methods if referer is malformed
+            }
+        }
+
+        // Fall back to building from request host/port
+        String scheme = request.getScheme();
+        String serverName = request.getServerName();
+        int serverPort = request.getServerPort();
+
+        StringBuilder origin = new StringBuilder();
+        origin.append(scheme).append("://").append(serverName);
+
+        // Only add port if it's not the default port for the scheme
+        if ((!"http".equals(scheme) || serverPort != 80)
+                && (!"https".equals(scheme) || serverPort != 443)) {
+            origin.append(":").append(serverPort);
+        }
+
+        return origin.toString() + "/auth/callback#access_token=" + jwt;
+    }
 }
@@ -10,7 +10,6 @@ import java.util.List;
 import java.util.Optional;
 import java.util.Set;

-import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -41,7 +40,7 @@ import stirling.software.proprietary.security.service.UserService;

@Slf4j
@Configuration
-@ConditionalOnBooleanProperty("security.oauth2.enabled")
+@ConditionalOnProperty(prefix = "security", name = "oauth2.enabled", havingValue = "true")
 public class OAuth2Configuration {

    public static final String REDIRECT_URI_PATH = "{baseUrl}/login/oauth2/code/";
@@ -53,6 +52,9 @@ public class OAuth2Configuration {
            ApplicationProperties applicationProperties, @Lazy UserService userService) {
        this.userService = userService;
        this.applicationProperties = applicationProperties;
+        log.info(
+                "OAuth2Configuration initialized - OAuth2 enabled: {}",
+                applicationProperties.getSecurity().getOauth2().getEnabled());
    }

    @Bean
@@ -75,7 +77,7 @@ public class OAuth2Configuration {
    private Optional<ClientRegistration> keycloakClientRegistration() {
        OAUTH2 oauth2 = applicationProperties.getSecurity().getOauth2();

-        if (isOAuth2Enabled(oauth2) || isClientInitialised(oauth2)) {
+        if (isOAuth2Disabled(oauth2) || isClientInitialised(oauth2)) {
            return Optional.empty();
        }

@@ -105,7 +107,7 @@ public class OAuth2Configuration {
    private Optional<ClientRegistration> googleClientRegistration() {
        OAUTH2 oAuth2 = applicationProperties.getSecurity().getOauth2();

-        if (isOAuth2Enabled(oAuth2) || isClientInitialised(oAuth2)) {
+        if (isOAuth2Disabled(oAuth2) || isClientInitialised(oAuth2)) {
            return Optional.empty();
        }

@@ -138,12 +140,23 @@ public class OAuth2Configuration {
    private Optional<ClientRegistration> githubClientRegistration() {
        OAUTH2 oAuth2 = applicationProperties.getSecurity().getOauth2();

-        if (isOAuth2Enabled(oAuth2)) {
+        if (isOAuth2Disabled(oAuth2)) {
+            log.debug("OAuth2 is disabled, skipping GitHub client registration");
            return Optional.empty();
        }

        Client client = oAuth2.getClient();
+        if (client == null) {
+            log.debug("OAuth2 client configuration is null, skipping GitHub");
+            return Optional.empty();
+        }
+
        GitHubProvider githubClient = client.getGithub();
+        if (githubClient == null) {
+            log.debug("GitHub client configuration is null");
+            return Optional.empty();
+        }
+
        Provider github =
                new GitHubProvider(
                        githubClient.getClientId(),
@@ -151,7 +164,15 @@ public class OAuth2Configuration {
                        githubClient.getScopes(),
                        githubClient.getUseAsUsername());

-        return validateProvider(github)
+        boolean isValid = validateProvider(github);
+        log.info(
+                "GitHub OAuth2 provider validation: {} (clientId: {}, clientSecret: {}, scopes: {})",
+                isValid,
+                githubClient.getClientId(),
+                githubClient.getClientSecret() != null ? "***" : "null",
+                githubClient.getScopes());
+
+        return isValid
                ? Optional.of(
                        ClientRegistration.withRegistrationId(github.getName())
                                .clientId(github.getClientId())
@@ -171,7 +192,7 @@ public class OAuth2Configuration {
    private Optional<ClientRegistration> oidcClientRegistration() {
        OAUTH2 oauth = applicationProperties.getSecurity().getOauth2();

-        if (isOAuth2Enabled(oauth) || isClientInitialised(oauth)) {
+        if (isOAuth2Disabled(oauth) || isClientInitialised(oauth)) {
            return Optional.empty();
        }

@@ -207,7 +228,7 @@ public class OAuth2Configuration {
                : Optional.empty();
    }

-    private boolean isOAuth2Enabled(OAUTH2 oAuth2) {
+    private boolean isOAuth2Disabled(OAUTH2 oAuth2) {
        return oAuth2 == null || !oAuth2.getEnabled();
    }

@@ -116,13 +116,41 @@ public class CustomSaml2AuthenticationSuccessHandler
                                contextPath + "/login?errorOAuth=oAuth2AdminBlockedUser");
                        return;
                    }
-                    log.debug("Processing SSO post-login for user: {}", username);
+
+                    // Extract SSO provider information from SAML2 assertion
+                    String ssoProviderId = saml2Principal.nameId();
+                    String ssoProvider = "saml2"; // fixme
+
+                    log.debug(
+                            "Processing SSO post-login for user: {} (Provider: {}, ProviderId: {})",
+                            username,
+                            ssoProvider,
+                            ssoProviderId);
+
                    userService.processSSOPostLogin(
-                            username, saml2Properties.getAutoCreateUser(), SAML2);
+                            username,
+                            ssoProviderId,
+                            ssoProvider,
+                            saml2Properties.getAutoCreateUser(),
+                            SAML2);
                    log.debug("Successfully processed authentication for user: {}", username);

-                    generateJwt(response, authentication);
-                    response.sendRedirect(contextPath + "/");
+                    // Generate JWT if v2 is enabled
+                    if (jwtService.isJwtEnabled()) {
+                        String jwt =
+                                jwtService.generateToken(
+                                        authentication,
+                                        Map.of("authType", AuthenticationType.SAML2));
+
+                        // Build context-aware redirect URL based on the original request
+                        String redirectUrl =
+                                buildContextAwareRedirectUrl(request, contextPath, jwt);
+
+                        response.sendRedirect(redirectUrl);
+                    } else {
+                        // v1: redirect directly to home
+                        response.sendRedirect(contextPath + "/");
+                    }
                } catch (IllegalArgumentException | SQLException | UnsupportedProviderException e) {
                    log.debug(
                            "Invalid username detected for user: {}, redirecting to logout",
@@ -136,12 +164,48 @@ public class CustomSaml2AuthenticationSuccessHandler
        }
    }

-    private void generateJwt(HttpServletResponse response, Authentication authentication) {
-        if (jwtService.isJwtEnabled()) {
-            String jwt =
-                    jwtService.generateToken(
-                            authentication, Map.of("authType", AuthenticationType.SAML2));
-            jwtService.addToken(response, jwt);
+    /**
+     * Builds a context-aware redirect URL based on the request's origin
+     *
+     * @param request The HTTP request
+     * @param contextPath The application context path
+     * @param jwt The JWT token to include
+     * @return The appropriate redirect URL
+     */
+    private String buildContextAwareRedirectUrl(
+            HttpServletRequest request, String contextPath, String jwt) {
+        // Try to get the origin from the Referer header first
+        String referer = request.getHeader("Referer");
+        if (referer != null && !referer.isEmpty()) {
+            try {
+                java.net.URL refererUrl = new java.net.URL(referer);
+                String origin = refererUrl.getProtocol() + "://" + refererUrl.getHost();
+                if (refererUrl.getPort() != -1
+                        && refererUrl.getPort() != 80
+                        && refererUrl.getPort() != 443) {
+                    origin += ":" + refererUrl.getPort();
+                }
+                return origin + "/auth/callback#access_token=" + jwt;
+            } catch (java.net.MalformedURLException e) {
+                log.debug(
+                        "Malformed referer URL: {}, falling back to request-based origin", referer);
+            }
        }
+
+        // Fall back to building from request host/port
+        String scheme = request.getScheme();
+        String serverName = request.getServerName();
+        int serverPort = request.getServerPort();
+
+        StringBuilder origin = new StringBuilder();
+        origin.append(scheme).append("://").append(serverName);
+
+        // Only add port if it's not the default port for the scheme
+        if ((!"http".equals(scheme) || serverPort != 80)
+                && (!"https".equals(scheme) || serverPort != 443)) {
+            origin.append(":").append(serverPort);
+        }
+
+        return origin + "/auth/callback#access_token=" + jwt;
    }
 }
@@ -14,7 +14,6 @@ import org.springframework.security.oauth2.core.oidc.user.OidcUser;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.ApplicationProperties;
-import stirling.software.common.model.ApplicationProperties.Security.OAUTH2;
 import stirling.software.common.model.enumeration.UsernameAttribute;
 import stirling.software.proprietary.security.model.User;

@@ -27,13 +26,13 @@ public class CustomOAuth2UserService implements OAuth2UserService<OidcUserReques

    private final LoginAttemptService loginAttemptService;

-    private final ApplicationProperties.Security securityProperties;
+    private final ApplicationProperties.Security.OAUTH2 oauth2Properties;

    public CustomOAuth2UserService(
-            ApplicationProperties.Security securityProperties,
+            ApplicationProperties.Security.OAUTH2 oauth2Properties,
            UserService userService,
            LoginAttemptService loginAttemptService) {
-        this.securityProperties = securityProperties;
+        this.oauth2Properties = oauth2Properties;
        this.userService = userService;
        this.loginAttemptService = loginAttemptService;
    }
@@ -42,14 +41,22 @@ public class CustomOAuth2UserService implements OAuth2UserService<OidcUserReques
    public OidcUser loadUser(OidcUserRequest userRequest) throws OAuth2AuthenticationException {
        try {
            OidcUser user = delegate.loadUser(userRequest);
-            OAUTH2 oauth2 = securityProperties.getOauth2();
-            UsernameAttribute usernameAttribute =
-                    UsernameAttribute.valueOf(oauth2.getUseAsUsername().toUpperCase());
-            String usernameAttributeKey = usernameAttribute.getName();
+            String usernameAttributeKey =
+                    UsernameAttribute.valueOf(oauth2Properties.getUseAsUsername().toUpperCase())
+                            .getName();

-            // todo: save user by OIDC ID instead of username
-            Optional<User> internalUser =
-                    userService.findByUsernameIgnoreCase(user.getAttribute(usernameAttributeKey));
+            // Extract SSO provider information
+            String ssoProviderId = user.getSubject(); // Standard OIDC 'sub' claim
+            String ssoProvider = userRequest.getClientRegistration().getRegistrationId();
+            String username = user.getAttribute(usernameAttributeKey);
+
+            log.debug(
+                    "OAuth2 login - Provider: {}, ProviderId: {}, Username: {}",
+                    ssoProvider,
+                    ssoProviderId,
+                    username);
+
+            Optional<User> internalUser = userService.findByUsernameIgnoreCase(username);

            if (internalUser.isPresent()) {
                String internalUsername = internalUser.get().getUsername();
@@ -73,4 +73,90 @@ public class EmailService {
        // Sends the email via the configured mail sender
        mailSender.send(message);
    }
+
+    /**
+     * Sends a plain text/HTML email without attachments asynchronously.
+     *
+     * @param to The recipient email address
+     * @param subject The email subject
+     * @param body The email body (can contain HTML)
+     * @param isHtml Whether the body contains HTML content
+     * @throws MessagingException If there is an issue with creating or sending the email.
+     */
+    @Async
+    public void sendPlainEmail(String to, String subject, String body, boolean isHtml)
+            throws MessagingException {
+        // Validate recipient email address
+        if (to == null || to.trim().isEmpty()) {
+            throw new MessagingException("Invalid recipient email address");
+        }
+
+        ApplicationProperties.Mail mailProperties = applicationProperties.getMail();
+
+        // Creates a MimeMessage to represent the email
+        MimeMessage message = mailSender.createMimeMessage();
+
+        // Helper class to set up the message content
+        MimeMessageHelper helper = new MimeMessageHelper(message, false);
+
+        // Sets the recipient, subject, body, and sender email
+        helper.addTo(to);
+        helper.setSubject(subject);
+        helper.setText(body, isHtml);
+        helper.setFrom(mailProperties.getFrom());
+
+        // Sends the email via the configured mail sender
+        mailSender.send(message);
+    }
+
+    /**
+     * Sends an invitation email to a new user with their credentials.
+     *
+     * @param to The recipient email address
+     * @param username The username for the new account
+     * @param temporaryPassword The temporary password
+     * @throws MessagingException If there is an issue with creating or sending the email.
+     */
+    @Async
+    public void sendInviteEmail(String to, String username, String temporaryPassword)
+            throws MessagingException {
+        String subject = "Welcome to Stirling PDF";
+
+        String body =
+                """
+                <html><body style="margin: 0; padding: 0;">
+                <div style="font-family: Arial, sans-serif; background-color: #f8f9fa; padding: 20px;">
+                  <div style="max-width: 600px; margin: auto; background-color: #ffffff; border-radius: 8px; overflow: hidden; border: 1px solid #e0e0e0;">
+                    <!-- Logo -->
+                    <div style="text-align: center; padding: 20px; background-color: #222;">
+                      <img src="https://raw.githubusercontent.com/Stirling-Tools/Stirling-PDF/main/docs/stirling-transparent.svg" alt="Stirling PDF" style="max-height: 60px;">
+                    </div>
+                    <!-- Content -->
+                    <div style="padding: 30px; color: #333;">
+                      <h2 style="color: #222; margin-top: 0;">Welcome to Stirling PDF!</h2>
+                      <p>Hi there,</p>
+                      <p>You have been invited to join the workspace. Below are your login credentials:</p>
+                      <!-- Credentials Box -->
+                      <div style="background-color: #f8f9fa; border-left: 4px solid #007bff; padding: 15px; margin: 20px 0; border-radius: 4px;">
+                        <p style="margin: 0 0 10px 0;"><strong>Username:</strong> %s</p>
+                        <p style="margin: 0;"><strong>Temporary Password:</strong> %s</p>
+                      </div>
+                      <div style="background-color: #fff3cd; border-left: 4px solid #ffc107; padding: 15px; margin: 20px 0; border-radius: 4px;">
+                        <p style="margin: 0; color: #856404;"><strong>⚠️ Important:</strong> You will be required to change your password upon first login for security reasons.</p>
+                      </div>
+                      <p>Please keep these credentials secure and do not share them with anyone.</p>
+                      <p style="margin-bottom: 0;">— The Stirling PDF Team</p>
+                    </div>
+                    <!-- Footer -->
+                    <div style="text-align: center; padding: 15px; font-size: 12px; color: #777; background-color: #f0f0f0;">
+                      &copy; 2025 Stirling PDF. All rights reserved.
+                    </div>
+                  </div>
+                </div>
+                </body></html>
+                """
+                        .formatted(username, temporaryPassword);
+
+        sendPlainEmail(to, subject, body, true);
+    }
 }
@@ -14,14 +14,11 @@ import java.util.function.Function;

 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Qualifier;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.http.ResponseCookie;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.userdetails.UserDetails;
 import org.springframework.security.oauth2.core.user.OAuth2User;
 import org.springframework.stereotype.Service;

-import io.github.pixee.security.Newlines;
 import io.jsonwebtoken.Claims;
 import io.jsonwebtoken.ExpiredJwtException;
 import io.jsonwebtoken.Jwts;
@@ -29,9 +26,7 @@ import io.jsonwebtoken.MalformedJwtException;
 import io.jsonwebtoken.UnsupportedJwtException;
 import io.jsonwebtoken.security.SignatureException;

-import jakarta.servlet.http.Cookie;
 import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;

 import lombok.extern.slf4j.Slf4j;

@@ -43,13 +38,9 @@ import stirling.software.proprietary.security.saml2.CustomSaml2AuthenticatedPrin
@Service
 public class JwtService implements JwtServiceInterface {

-    private static final String JWT_COOKIE_NAME = "stirling_jwt";
-    private static final String ISSUER = "Stirling PDF";
+    private static final String ISSUER = "https://stirling.com";
    private static final long EXPIRATION = 3600000;

-    @Value("${stirling.security.jwt.secureCookie:true}")
-    private boolean secureCookie;
-
    private final KeyPersistenceServiceInterface keyPersistenceService;
    private final boolean v2Enabled;

@@ -59,6 +50,7 @@ public class JwtService implements JwtServiceInterface {
            KeyPersistenceServiceInterface keyPersistenceService) {
        this.v2Enabled = v2Enabled;
        this.keyPersistenceService = keyPersistenceService;
+        log.info("JwtService initialized");
    }

    @Override
@@ -260,47 +252,18 @@ public class JwtService implements JwtServiceInterface {

    @Override
    public String extractToken(HttpServletRequest request) {
-        Cookie[] cookies = request.getCookies();
-
-        if (cookies != null) {
-            for (Cookie cookie : cookies) {
-                if (JWT_COOKIE_NAME.equals(cookie.getName())) {
-                    return cookie.getValue();
-                }
-            }
+        // Extract from Authorization header Bearer token
+        String authHeader = request.getHeader("Authorization");
+        if (authHeader != null && authHeader.startsWith("Bearer ")) {
+            String token = authHeader.substring(7); // Remove "Bearer " prefix
+            log.debug("JWT token extracted from Authorization header");
+            return token;
        }

+        log.debug("No JWT token found in Authorization header");
        return null;
    }

-    @Override
-    public void addToken(HttpServletResponse response, String token) {
-        ResponseCookie cookie =
-                ResponseCookie.from(JWT_COOKIE_NAME, Newlines.stripAll(token))
-                        .httpOnly(true)
-                        .secure(secureCookie)
-                        .sameSite("Strict")
-                        .maxAge(EXPIRATION / 1000)
-                        .path("/")
-                        .build();
-
-        response.addHeader("Set-Cookie", cookie.toString());
-    }
-
-    @Override
-    public void clearToken(HttpServletResponse response) {
-        ResponseCookie cookie =
-                ResponseCookie.from(JWT_COOKIE_NAME, "")
-                        .httpOnly(true)
-                        .secure(secureCookie)
-                        .sameSite("None")
-                        .maxAge(0)
-                        .path("/")
-                        .build();
-
-        response.addHeader("Set-Cookie", cookie.toString());
-    }
-
    @Override
    public boolean isJwtEnabled() {
        return v2Enabled;
@@ -5,7 +5,6 @@ import java.util.Map;
 import org.springframework.security.core.Authentication;

 import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;

 public interface JwtServiceInterface {

@@ -66,21 +65,6 @@ public interface JwtServiceInterface {
     */
    String extractToken(HttpServletRequest request);

-    /**
-     * Add JWT token to HTTP response (header and cookie)
-     *
-     * @param response HTTP servlet response
-     * @param token JWT token to add
-     */
-    void addToken(HttpServletResponse response, String token);
-
-    /**
-     * Clear JWT token from HTTP response (remove cookie)
-     *
-     * @param response HTTP servlet response
-     */
-    void clearToken(HttpServletResponse response);
-
    /**
     * Check if JWT authentication is enabled
     *
@@ -60,19 +60,46 @@ public class UserService implements UserServiceInterface {

    private final ApplicationProperties.Security.OAUTH2 oAuth2;

-    // Handle OAUTH2 login and user auto creation.
    public void processSSOPostLogin(
-            String username, boolean autoCreateUser, AuthenticationType type)
+            String username,
+            String ssoProviderId,
+            String ssoProvider,
+            boolean autoCreateUser,
+            AuthenticationType type)
            throws IllegalArgumentException, SQLException, UnsupportedProviderException {
        if (!isUsernameValid(username)) {
            return;
        }
-        Optional<User> existingUser = findByUsernameIgnoreCase(username);
+
+        // Find user by SSO provider ID first
+        Optional<User> existingUser;
+        if (ssoProviderId != null && ssoProvider != null) {
+            existingUser =
+                    userRepository.findBySsoProviderAndSsoProviderId(ssoProvider, ssoProviderId);
+
+            if (existingUser.isPresent()) {
+                log.debug("User found by SSO provider ID: {}", ssoProviderId);
+                return;
+            }
+        }
+
+        existingUser = findByUsernameIgnoreCase(username);
        if (existingUser.isPresent()) {
+            User user = existingUser.get();
+
+            // Migrate existing user to use provider ID if not already set
+            if (user.getSsoProviderId() == null && ssoProviderId != null && ssoProvider != null) {
+                log.info("Migrating user {} to use SSO provider ID: {}", username, ssoProviderId);
+                user.setSsoProviderId(ssoProviderId);
+                user.setSsoProvider(ssoProvider);
+                userRepository.save(user);
+                databaseService.exportDatabase();
+            }
            return;
        }
+
        if (autoCreateUser) {
-            saveUser(username, type);
+            saveUser(username, ssoProviderId, ssoProvider, type);
        }
    }

@@ -154,6 +181,21 @@ public class UserService implements UserServiceInterface {
        saveUser(username, authenticationType, (Long) null, Role.USER.getRoleId());
    }

+    public void saveUser(
+            String username,
+            String ssoProviderId,
+            String ssoProvider,
+            AuthenticationType authenticationType)
+            throws IllegalArgumentException, SQLException, UnsupportedProviderException {
+        saveUser(
+                username,
+                ssoProviderId,
+                ssoProvider,
+                authenticationType,
+                (Long) null,
+                Role.USER.getRoleId());
+    }
+
    private User saveUser(Optional<User> user, String apiKey) {
        if (user.isPresent()) {
            user.get().setApiKey(apiKey);
@@ -168,6 +210,30 @@ public class UserService implements UserServiceInterface {
        return saveUserCore(
                username, // username
                null, // password
+                null, // ssoProviderId
+                null, // ssoProvider
+                authenticationType, // authenticationType
+                teamId, // teamId
+                null, // team
+                role, // role
+                false, // firstLogin
+                true // enabled
+                );
+    }
+
+    public User saveUser(
+            String username,
+            String ssoProviderId,
+            String ssoProvider,
+            AuthenticationType authenticationType,
+            Long teamId,
+            String role)
+            throws IllegalArgumentException, SQLException, UnsupportedProviderException {
+        return saveUserCore(
+                username, // username
+                null, // password
+                ssoProviderId, // ssoProviderId
+                ssoProvider, // ssoProvider
                authenticationType, // authenticationType
                teamId, // teamId
                null, // team
@@ -183,6 +249,8 @@ public class UserService implements UserServiceInterface {
        return saveUserCore(
                username, // username
                null, // password
+                null, // ssoProviderId
+                null, // ssoProvider
                authenticationType, // authenticationType
                null, // teamId
                team, // team
@@ -197,6 +265,8 @@ public class UserService implements UserServiceInterface {
        return saveUserCore(
                username, // username
                password, // password
+                null, // ssoProviderId
+                null, // ssoProvider
                AuthenticationType.WEB, // authenticationType
                teamId, // teamId
                null, // team
@@ -212,6 +282,8 @@ public class UserService implements UserServiceInterface {
        return saveUserCore(
                username, // username
                password, // password
+                null, // ssoProviderId
+                null, // ssoProvider
                AuthenticationType.WEB, // authenticationType
                null, // teamId
                team, // team
@@ -227,6 +299,8 @@ public class UserService implements UserServiceInterface {
        return saveUserCore(
                username, // username
                password, // password
+                null, // ssoProviderId
+                null, // ssoProvider
                AuthenticationType.WEB, // authenticationType
                teamId, // teamId
                null, // team
@@ -247,6 +321,8 @@ public class UserService implements UserServiceInterface {
        saveUserCore(
                username, // username
                password, // password
+                null, // ssoProviderId
+                null, // ssoProvider
                AuthenticationType.WEB, // authenticationType
                teamId, // teamId
                null, // team
@@ -411,6 +487,8 @@ public class UserService implements UserServiceInterface {
     *
     * @param username Username for the new user
     * @param password Password for the user (may be null for SSO/OAuth users)
+     * @param ssoProviderId Unique identifier from SSO provider (may be null for non-SSO users)
+     * @param ssoProvider Name of the SSO provider (may be null for non-SSO users)
     * @param authenticationType Type of authentication (WEB, SSO, etc.)
     * @param teamId ID of the team to assign (may be null to use default)
     * @param team Team object to assign (takes precedence over teamId if both provided)
@@ -425,6 +503,8 @@ public class UserService implements UserServiceInterface {
    private User saveUserCore(
            String username,
            String password,
+            String ssoProviderId,
+            String ssoProvider,
            AuthenticationType authenticationType,
            Long teamId,
            Team team,
@@ -445,6 +525,12 @@ public class UserService implements UserServiceInterface {
            user.setPassword(passwordEncoder.encode(password));
        }

+        // Set SSO provider details if provided
+        if (ssoProviderId != null && ssoProvider != null) {
+            user.setSsoProviderId(ssoProviderId);
+            user.setSsoProvider(ssoProvider);
+        }
+
        // Set authentication type
        user.setAuthenticationType(authenticationType);

@@ -556,6 +642,21 @@ public class UserService implements UserServiceInterface {
        return null;
    }

+    public boolean isCurrentUserAdmin() {
+        try {
+            Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+            if (authentication != null
+                    && authentication.isAuthenticated()
+                    && !"anonymousUser".equals(authentication.getPrincipal())) {
+                return authentication.getAuthorities().stream()
+                        .anyMatch(auth -> Role.ADMIN.getRoleId().equals(auth.getAuthority()));
+            }
+        } catch (Exception e) {
+            log.debug("Error checking admin status", e);
+        }
+        return false;
+    }
+
    @Transactional
    public void syncCustomApiUser(String customApiKey) {
        if (customApiKey == null || customApiKey.trim().isBlank()) {
@@ -30,6 +30,8 @@ import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.configuration.InstallationPathConfig;
 import stirling.software.common.service.ServerCertificateServiceInterface;
+import stirling.software.proprietary.security.configuration.ee.KeygenLicenseVerifier.License;
+import stirling.software.proprietary.security.configuration.ee.LicenseKeyChecker;

@Service
@Slf4j
@@ -51,6 +53,12 @@ public class ServerCertificateService implements ServerCertificateServiceInterfa
    @Value("${system.serverCertificate.regenerateOnStartup:false}")
    private boolean regenerateOnStartup;

+    private final LicenseKeyChecker licenseKeyChecker;
+
+    public ServerCertificateService(LicenseKeyChecker licenseKeyChecker) {
+        this.licenseKeyChecker = licenseKeyChecker;
+    }
+
    static {
        Security.addProvider(new BouncyCastleProvider());
    }
@@ -59,8 +67,13 @@ public class ServerCertificateService implements ServerCertificateServiceInterfa
        return Paths.get(InstallationPathConfig.getConfigPath(), KEYSTORE_FILENAME);
    }

+    private boolean hasProOrEnterpriseAccess() {
+        License license = licenseKeyChecker.getPremiumLicenseEnabledResult();
+        return license == License.PRO || license == License.ENTERPRISE;
+    }
+
    public boolean isEnabled() {
-        return enabled;
+        return enabled && hasProOrEnterpriseAccess();
    }

    public boolean hasServerCertificate() {
@@ -73,6 +86,11 @@ public class ServerCertificateService implements ServerCertificateServiceInterfa
            return;
        }

+        if (!hasProOrEnterpriseAccess()) {
+            log.info("Server certificate feature requires Pro or Enterprise license");
+            return;
+        }
+
        Path keystorePath = getKeystorePath();

        if (!Files.exists(keystorePath) || regenerateOnStartup) {
@@ -88,6 +106,11 @@ public class ServerCertificateService implements ServerCertificateServiceInterfa
    }

    public KeyStore getServerKeyStore() throws Exception {
+        if (!hasProOrEnterpriseAccess()) {
+            throw new IllegalStateException(
+                    "Server certificate feature requires Pro or Enterprise license");
+        }
+
        if (!enabled || !hasServerCertificate()) {
            throw new IllegalStateException("Server certificate is not available");
        }
@@ -114,6 +137,11 @@ public class ServerCertificateService implements ServerCertificateServiceInterfa
    }

    public void uploadServerCertificate(InputStream p12Stream, String password) throws Exception {
+        if (!hasProOrEnterpriseAccess()) {
+            throw new IllegalStateException(
+                    "Server certificate feature requires Pro or Enterprise license");
+        }
+
        // Validate the uploaded certificate
        KeyStore uploadedKeyStore = KeyStore.getInstance("PKCS12");
        uploadedKeyStore.load(p12Stream, password.toCharArray());
@@ -174,6 +202,11 @@ public class ServerCertificateService implements ServerCertificateServiceInterfa
    }

    private void generateServerCertificate() throws Exception {
+        if (!hasProOrEnterpriseAccess()) {
+            throw new IllegalStateException(
+                    "Server certificate feature requires Pro or Enterprise license");
+        }
+
        // Generate key pair
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA", "BC");
        keyPairGenerator.initialize(2048, new SecureRandom());
@@ -1,6 +1,8 @@
 package stirling.software.proprietary.security;

-import static org.mockito.Mockito.*;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;

 import java.io.IOException;

@@ -38,7 +40,6 @@ class CustomLogoutSuccessHandlerTest {

        when(response.isCommitted()).thenReturn(false);
        when(jwtService.extractToken(request)).thenReturn(token);
-        doNothing().when(jwtService).clearToken(response);
        when(request.getContextPath()).thenReturn("");
        when(response.encodeRedirectURL(logoutPath)).thenReturn(logoutPath);

@@ -56,14 +57,12 @@ class CustomLogoutSuccessHandlerTest {

        when(response.isCommitted()).thenReturn(false);
        when(jwtService.extractToken(request)).thenReturn(token);
-        doNothing().when(jwtService).clearToken(response);
        when(request.getContextPath()).thenReturn("");
        when(response.encodeRedirectURL(logoutPath)).thenReturn(logoutPath);

        customLogoutSuccessHandler.onLogoutSuccess(request, response, null);

        verify(response).sendRedirect(logoutPath);
-        verify(jwtService).clearToken(response);
    }

    @Test
@@ -127,7 +127,6 @@ class JwtAuthenticationFilterTest {
                    .setAuthentication(any(UsernamePasswordAuthenticationToken.class));
            verify(jwtService)
                    .generateToken(any(UsernamePasswordAuthenticationToken.class), eq(claims));
-            verify(jwtService).addToken(response, newToken);
            verify(filterChain).doFilter(request, response);
        }
    }
@@ -8,8 +8,6 @@ import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.Mockito.atLeast;
-import static org.mockito.Mockito.contains;
-import static org.mockito.Mockito.eq;
 import static org.mockito.Mockito.lenient;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.verify;
@@ -17,7 +15,6 @@ import static org.mockito.Mockito.when;

 import java.security.KeyPair;
 import java.security.KeyPairGenerator;
-import java.security.NoSuchAlgorithmException;
 import java.util.Base64;
 import java.util.Collections;
 import java.util.HashMap;
@@ -27,13 +24,10 @@ import java.util.Optional;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.ValueSource;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.security.core.Authentication;

-import jakarta.servlet.http.Cookie;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;

@@ -59,7 +53,7 @@ class JwtServiceTest {
    private JwtVerificationKey testVerificationKey;

    @BeforeEach
-    void setUp() throws NoSuchAlgorithmException {
+    void setUp() throws Exception {
        // Generate a test keypair
        KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
        keyPairGenerator.initialize(2048);
@@ -224,7 +218,8 @@ class JwtServiceTest {
        assertEquals("admin", extractedClaims.get("role"));
        assertEquals("IT", extractedClaims.get("department"));
        assertEquals(username, extractedClaims.get("sub"));
-        assertEquals("Stirling PDF", extractedClaims.get("iss"));
+        // Verify the constant issuer is set correctly
+        assertEquals("https://stirling.com", extractedClaims.get("iss"));
    }

    @Test
@@ -239,62 +234,27 @@ class JwtServiceTest {
    }

    @Test
-    void testExtractTokenWithCookie() {
+    void testExtractTokenWithAuthorizationHeader() {
        String token = "test-token";
-        Cookie[] cookies = {new Cookie("stirling_jwt", token)};
-        when(request.getCookies()).thenReturn(cookies);
+        when(request.getHeader("Authorization")).thenReturn("Bearer " + token);

        assertEquals(token, jwtService.extractToken(request));
    }

    @Test
-    void testExtractTokenWithNoCookies() {
-        when(request.getCookies()).thenReturn(null);
+    void testExtractTokenWithNoAuthorizationHeader() {
+        when(request.getHeader("Authorization")).thenReturn(null);

        assertNull(jwtService.extractToken(request));
    }

    @Test
-    void testExtractTokenWithWrongCookie() {
-        Cookie[] cookies = {new Cookie("OTHER_COOKIE", "value")};
-        when(request.getCookies()).thenReturn(cookies);
+    void testExtractTokenWithInvalidAuthorizationHeaderFormat() {
+        when(request.getHeader("Authorization")).thenReturn("InvalidFormat token");

        assertNull(jwtService.extractToken(request));
    }

-    @Test
-    void testExtractTokenWithInvalidAuthorizationHeader() {
-        when(request.getCookies()).thenReturn(null);
-
-        assertNull(jwtService.extractToken(request));
-    }
-
-    @ParameterizedTest
-    @ValueSource(booleans = {true, false})
-    void testAddToken(boolean secureCookie) throws Exception {
-        String token = "test-token";
-
-        // Create new JwtService instance with the secureCookie parameter
-        JwtService testJwtService = createJwtServiceWithSecureCookie(secureCookie);
-
-        testJwtService.addToken(response, token);
-
-        verify(response).addHeader(eq("Set-Cookie"), contains("stirling_jwt=" + token));
-        verify(response).addHeader(eq("Set-Cookie"), contains("HttpOnly"));
-
-        if (secureCookie) {
-            verify(response).addHeader(eq("Set-Cookie"), contains("Secure"));
-        }
-    }
-
-    @Test
-    void testClearToken() {
-        jwtService.clearToken(response);
-
-        verify(response).addHeader(eq("Set-Cookie"), contains("stirling_jwt="));
-        verify(response).addHeader(eq("Set-Cookie"), contains("Max-Age=0"));
-    }
-
    @Test
    void testGenerateTokenWithKeyId() throws Exception {
        String username = "testuser";
@@ -373,17 +333,4 @@ class JwtServiceTest {
        // Verify fallback logic was used
        verify(keystoreService, atLeast(1)).getActiveKey();
    }
-
-    private JwtService createJwtServiceWithSecureCookie(boolean secureCookie) throws Exception {
-        // Use reflection to create JwtService with custom secureCookie value
-        JwtService testService = new JwtService(true, keystoreService);
-
-        // Set the secureCookie field using reflection
-        java.lang.reflect.Field secureCookieField =
-                JwtService.class.getDeclaredField("secureCookie");
-        secureCookieField.setAccessible(true);
-        secureCookieField.set(testService, secureCookie);
-
-        return testService;
-    }
 }
@@ -629,9 +629,40 @@ tasks.named('bootRun') {
 tasks.named('build') {
    group = 'build'
    description = 'Delegates to :stirling-pdf:bootJar'
-    dependsOn ':stirling-pdf:bootJar'
+    dependsOn ':stirling-pdf:bootJar', 'buildRestartHelper'

    doFirst {
        println "Delegating to :stirling-pdf:bootJar"
    }
 }
+
+// Task to compile RestartHelper.java
+tasks.register('compileRestartHelper', JavaCompile) {
+    group = 'build'
+    description = 'Compiles the RestartHelper utility'
+
+    source = fileTree(dir: 'scripts', include: 'RestartHelper.java')
+    classpath = files()
+    destinationDirectory = file("${buildDir}/restart-helper-classes")
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+}
+
+// Task to create restart-helper.jar
+tasks.register('buildRestartHelper', Jar) {
+    group = 'build'
+    description = 'Builds the restart-helper.jar'
+    dependsOn 'compileRestartHelper'
+
+    from "${buildDir}/restart-helper-classes"
+    archiveFileName = 'restart-helper.jar'
+    destinationDirectory = file("${buildDir}/libs")
+
+    manifest {
+        attributes 'Main-Class': 'RestartHelper'
+    }
+
+    doLast {
+        println "restart-helper.jar created at: ${destinationDirectory.get()}/restart-helper.jar"
+    }
+}
@@ -0,0 +1,141 @@
+# Unified Dockerfile - Frontend + Backend in single container
+# Supports MODE parameter: BOTH (default), FRONTEND, BACKEND
+
+# Stage 1: Build Frontend
+FROM node:20-alpine AS frontend-build
+
+WORKDIR /app
+
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+COPY frontend .
+RUN npm run build
+
+# Stage 2: Build Backend
+FROM gradle:8.14-jdk21 AS backend-build
+
+COPY build.gradle .
+COPY settings.gradle .
+COPY gradlew .
+COPY gradle gradle/
+COPY app/core/build.gradle core/.
+COPY app/common/build.gradle common/.
+COPY app/proprietary/build.gradle proprietary/.
+RUN ./gradlew build -x spotlessApply -x spotlessCheck -x test -x sonarqube || return 0
+
+WORKDIR /app
+COPY . .
+
+RUN DISABLE_ADDITIONAL_FEATURES=false \
+    STIRLING_PDF_DESKTOP_UI=false \
+    ./gradlew clean build -x spotlessApply -x spotlessCheck -x test -x sonarqube
+
+# Stage 3: Final unified image
+FROM alpine:3.22.1
+
+ARG VERSION_TAG
+
+# Labels
+LABEL org.opencontainers.image.title="Stirling-PDF Unified"
+LABEL org.opencontainers.image.description="Unified container for Stirling-PDF - Frontend + Backend with MODE parameter"
+LABEL org.opencontainers.image.source="https://github.com/Stirling-Tools/Stirling-PDF"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.vendor="Stirling-Tools"
+LABEL org.opencontainers.image.url="https://www.stirlingpdf.com"
+LABEL org.opencontainers.image.documentation="https://docs.stirlingpdf.com"
+LABEL maintainer="Stirling-Tools"
+LABEL org.opencontainers.image.authors="Stirling-Tools"
+LABEL org.opencontainers.image.version="${VERSION_TAG}"
+LABEL org.opencontainers.image.keywords="PDF, manipulation, unified, API, Spring Boot, React"
+
+# Copy backend files
+COPY scripts /scripts
+COPY app/core/src/main/resources/static/fonts/*.ttf /usr/share/fonts/opentype/noto/
+COPY --from=backend-build /app/app/core/build/libs/*.jar app.jar
+
+# Copy frontend files
+COPY --from=frontend-build /app/dist /usr/share/nginx/html
+
+# Copy nginx configuration
+COPY docker/unified/nginx.conf /etc/nginx/nginx.conf
+COPY docker/unified/entrypoint.sh /entrypoint.sh
+
+# Environment Variables
+ENV DISABLE_ADDITIONAL_FEATURES=false \
+    VERSION_TAG=$VERSION_TAG \
+    JAVA_BASE_OPTS="-XX:+UnlockExperimentalVMOptions -XX:MaxRAMPercentage=75 -XX:InitiatingHeapOccupancyPercent=20 -XX:+G1PeriodicGCInvokesConcurrent -XX:G1PeriodicGCInterval=10000 -XX:+UseStringDeduplication -XX:G1PeriodicGCSystemLoadThreshold=70" \
+    JAVA_CUSTOM_OPTS="" \
+    HOME=/home/stirlingpdfuser \
+    PUID=1000 \
+    PGID=1000 \
+    UMASK=022 \
+    PYTHONPATH=/usr/lib/libreoffice/program:/opt/venv/lib/python3.12/site-packages \
+    UNO_PATH=/usr/lib/libreoffice/program \
+    URE_BOOTSTRAP=file:///usr/lib/libreoffice/program/fundamentalrc \
+    PATH=$PATH:/opt/venv/bin \
+    STIRLING_TEMPFILES_DIRECTORY=/tmp/stirling-pdf \
+    TMPDIR=/tmp/stirling-pdf \
+    TEMP=/tmp/stirling-pdf \
+    TMP=/tmp/stirling-pdf \
+    MODE=BOTH \
+    BACKEND_INTERNAL_PORT=8081 \
+    VITE_API_BASE_URL=http://localhost:8080
+
+# Install all dependencies
+RUN echo "@main https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/apk/repositories && \
+    echo "@community https://dl-cdn.alpinelinux.org/alpine/edge/community" | tee -a /etc/apk/repositories && \
+    echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing" | tee -a /etc/apk/repositories && \
+    apk upgrade --no-cache -a && \
+    apk add --no-cache \
+    ca-certificates \
+    tzdata \
+    tini \
+    bash \
+    curl \
+    shadow \
+    su-exec \
+    openssl \
+    openssl-dev \
+    openjdk21-jre \
+    nginx \
+    # Doc conversion
+    gcompat \
+    libc6-compat \
+    libreoffice \
+    # pdftohtml
+    poppler-utils \
+    # OCR MY PDF
+    unpaper \
+    tesseract-ocr-data-eng \
+    tesseract-ocr-data-chi_sim \
+    tesseract-ocr-data-deu \
+    tesseract-ocr-data-fra \
+    tesseract-ocr-data-por \
+    ocrmypdf \
+    # CV
+    py3-opencv \
+    python3 \
+    py3-pip \
+    py3-pillow@testing \
+    py3-pdf2image@testing && \
+    python3 -m venv /opt/venv && \
+    /opt/venv/bin/pip install --upgrade pip setuptools && \
+    /opt/venv/bin/pip install --no-cache-dir --upgrade unoserver weasyprint && \
+    ln -s /usr/lib/libreoffice/program/uno.py /opt/venv/lib/python3.12/site-packages/ && \
+    ln -s /usr/lib/libreoffice/program/unohelper.py /opt/venv/lib/python3.12/site-packages/ && \
+    ln -s /usr/lib/libreoffice/program /opt/venv/lib/python3.12/site-packages/LibreOffice && \
+    mv /usr/share/tessdata /usr/share/tessdata-original && \
+    mkdir -p $HOME /configs /logs /customFiles /pipeline/watchedFolders /pipeline/finishedFolders /tmp/stirling-pdf /pipeline/watchedFolders /pipeline/finishedFolders && \
+    mkdir -p /var/lib/nginx/tmp /var/log/nginx && \
+    fc-cache -f -v && \
+    chmod +x /scripts/* && \
+    chmod +x /entrypoint.sh && \
+    # User permissions
+    addgroup -S stirlingpdfgroup && adduser -S stirlingpdfuser -G stirlingpdfgroup && \
+    chown -R stirlingpdfuser:stirlingpdfgroup $HOME /scripts /pipeline /usr/share/fonts/opentype/noto /configs /customFiles /pipeline /tmp/stirling-pdf /var/lib/nginx /var/log/nginx /usr/share/nginx && \
+    chown stirlingpdfuser:stirlingpdfgroup /app.jar
+
+EXPOSE 8080/tcp
+
+ENTRYPOINT ["tini", "--", "/entrypoint.sh"]
@@ -30,6 +30,7 @@ COPY scripts /scripts
 COPY app/core/src/main/resources/static/fonts/*.ttf /usr/share/fonts/opentype/noto/
 # first /app directory is for the build stage, second is for the final image
 COPY --from=build /app/app/core/build/libs/*.jar app.jar
+COPY --from=build /app/build/libs/restart-helper.jar restart-helper.jar

 ARG VERSION_TAG

@@ -113,7 +114,7 @@ RUN echo "@main https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/a
    # User permissions
    addgroup -S stirlingpdfgroup && adduser -S stirlingpdfuser -G stirlingpdfgroup && \
    chown -R stirlingpdfuser:stirlingpdfgroup $HOME /scripts /pipeline /usr/share/fonts/opentype/noto /configs /customFiles /pipeline /tmp/stirling-pdf && \
-    chown stirlingpdfuser:stirlingpdfgroup /app.jar
+    chown stirlingpdfuser:stirlingpdfgroup /app.jar /restart-helper.jar

 EXPOSE 8080/tcp

@@ -30,6 +30,7 @@ COPY scripts /scripts
 COPY app/core/src/main/resources/static/fonts/*.ttf /usr/share/fonts/opentype/noto/
 # first /app directory is for the build stage, second is for the final image
 COPY --from=build /app/app/core/build/libs/*.jar app.jar
+COPY --from=build /app/build/libs/restart-helper.jar restart-helper.jar

 ARG VERSION_TAG

@@ -104,7 +105,7 @@ RUN echo "@main https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/a
    # User permissions
    addgroup -S stirlingpdfgroup && adduser -S stirlingpdfuser -G stirlingpdfgroup && \
    chown -R stirlingpdfuser:stirlingpdfgroup $HOME /scripts /pipeline /usr/share/fonts/opentype/noto /configs /customFiles /pipeline /tmp/stirling-pdf && \
-    chown stirlingpdfuser:stirlingpdfgroup /app.jar
+    chown stirlingpdfuser:stirlingpdfgroup /app.jar /restart-helper.jar

 EXPOSE 8080/tcp
 # Set user and run command
@@ -45,6 +45,7 @@ ENV DISABLE_ADDITIONAL_FEATURES=true \
 COPY scripts/init-without-ocr.sh /scripts/init-without-ocr.sh
 COPY scripts/installFonts.sh /scripts/installFonts.sh
 COPY --from=build /app/app/core/build/libs/*.jar app.jar
+COPY --from=build /app/build/libs/restart-helper.jar restart-helper.jar

 # Set up necessary directories and permissions
 RUN echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /etc/apk/repositories && \
@@ -65,7 +66,7 @@ RUN echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/main" | tee -a /et
    chmod +x /scripts/*.sh && \
    addgroup -S stirlingpdfgroup && adduser -S stirlingpdfuser -G stirlingpdfgroup && \
    chown -R stirlingpdfuser:stirlingpdfgroup $HOME /scripts /pipeline /configs /customFiles /pipeline /tmp/stirling-pdf && \
-    chown stirlingpdfuser:stirlingpdfgroup /app.jar
+    chown stirlingpdfuser:stirlingpdfgroup /app.jar /restart-helper.jar

 # Set environment variables
 ENV ENDPOINTS_GROUPS_TO_REMOVE=CLI
@@ -0,0 +1,58 @@
+# Example Docker Compose for Unified Stirling-PDF Container
+# MODE=BACKEND: Backend API only (no frontend)
+
+services:
+  stirling-pdf-backend-only:
+    container_name: Stirling-PDF-Backend-Only
+    build:
+      context: ../..
+      dockerfile: docker/Dockerfile.unified
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./stirling/data:/usr/share/tessdata:rw
+      - ./stirling/config:/configs:rw
+      - ./stirling/logs:/logs:rw
+      - ./stirling/customFiles:/customFiles:rw
+      - ./stirling/pipeline:/pipeline:rw
+    environment:
+      # MODE parameter: BACKEND only
+      MODE: BACKEND
+
+      # Standard Stirling-PDF configuration
+      DISABLE_ADDITIONAL_FEATURES: "false"
+      DOCKER_ENABLE_SECURITY: "false"
+      PUID: 1000
+      PGID: 1000
+      UMASK: "022"
+
+      # Application settings
+      SYSTEM_DEFAULTLOCALE: en-US
+      UI_APPNAME: Stirling-PDF
+      SYSTEM_MAXFILESIZE: "100"
+      METRICS_ENABLED: "true"
+
+      # Optional: Add OCR languages (comma-separated)
+      # TESSERACT_LANGS: "deu,fra,spa"
+
+      # Optional: Java memory settings
+      # JAVA_CUSTOM_OPTS: "-Xmx4g"
+
+    restart: unless-stopped
+
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+        reservations:
+          memory: 2G
+
+# Access the API at: http://localhost:8080/api
+# Swagger UI at: http://localhost:8080/swagger-ui/index.html
@@ -0,0 +1,59 @@
+# Example Docker Compose for Unified Stirling-PDF Container
+# MODE=BOTH (default): Frontend + Backend in single container on port 8080
+
+services:
+  stirling-pdf-unified:
+    container_name: Stirling-PDF-Unified-Both
+    build:
+      context: ../..
+      dockerfile: docker/Dockerfile.unified
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./stirling/data:/usr/share/tessdata:rw
+      - ./stirling/config:/configs:rw
+      - ./stirling/logs:/logs:rw
+      - ./stirling/customFiles:/customFiles:rw
+      - ./stirling/pipeline:/pipeline:rw
+    environment:
+      # MODE parameter: BOTH (default), FRONTEND, or BACKEND
+      MODE: BOTH
+
+      # Backend runs internally on this port when MODE=BOTH
+      BACKEND_INTERNAL_PORT: 8081
+
+      # Standard Stirling-PDF configuration
+      DISABLE_ADDITIONAL_FEATURES: "false"
+      DOCKER_ENABLE_SECURITY: "false"
+      PUID: 1000
+      PGID: 1000
+      UMASK: "022"
+
+      # Application settings
+      SYSTEM_DEFAULTLOCALE: en-US
+      UI_APPNAME: Stirling-PDF
+      UI_HOMEDESCRIPTION: Your locally hosted one-stop-shop for all your PDF needs
+      SYSTEM_MAXFILESIZE: "100"
+      METRICS_ENABLED: "true"
+
+      # Optional: Add OCR languages (comma-separated)
+      # TESSERACT_LANGS: "deu,fra,spa"
+
+      # Optional: Java memory settings
+      # JAVA_CUSTOM_OPTS: "-Xmx4g"
+
+    restart: unless-stopped
+
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+        reservations:
+          memory: 2G
@@ -0,0 +1,63 @@
+# Example Docker Compose for Unified Stirling-PDF Container
+# MODE=FRONTEND: Frontend only, connects to separate backend
+
+services:
+  stirling-pdf-backend:
+    container_name: Stirling-PDF-Backend
+    build:
+      context: ../..
+      dockerfile: docker/Dockerfile.unified
+    ports:
+      - "8081:8080"
+    volumes:
+      - ./stirling/data:/usr/share/tessdata:rw
+      - ./stirling/config:/configs:rw
+      - ./stirling/logs:/logs:rw
+      - ./stirling/customFiles:/customFiles:rw
+      - ./stirling/pipeline:/pipeline:rw
+    environment:
+      MODE: BACKEND
+      DISABLE_ADDITIONAL_FEATURES: "false"
+      DOCKER_ENABLE_SECURITY: "false"
+      PUID: 1000
+      PGID: 1000
+      UMASK: "022"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+
+  stirling-pdf-frontend:
+    container_name: Stirling-PDF-Frontend
+    build:
+      context: ../..
+      dockerfile: docker/Dockerfile.unified
+    ports:
+      - "8080:8080"
+    environment:
+      MODE: FRONTEND
+
+      # Point to the backend service
+      VITE_API_BASE_URL: http://stirling-pdf-backend:8080
+
+      # Minimal config needed for frontend
+      PUID: 1000
+      PGID: 1000
+    depends_on:
+      - stirling-pdf-backend
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8080/ || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    deploy:
+      resources:
+        limits:
+          memory: 512M
@@ -0,0 +1,458 @@
+# Stirling-PDF Unified Container
+
+Single Docker container that can run as **frontend + backend**, **frontend only**, or **backend only** using the `MODE` environment variable.
+
+## Quick Start
+
+### MODE=BOTH (Default)
+Single container with both frontend and backend on port 8080:
+
+```bash
+docker run -p 8080:8080 \
+  -e MODE=BOTH \
+  stirlingtools/stirling-pdf:unified
+```
+
+Access at: `http://localhost:8080`
+
+### MODE=FRONTEND
+Frontend only, connecting to separate backend:
+
+```bash
+docker run -p 8080:8080 \
+  -e MODE=FRONTEND \
+  -e VITE_API_BASE_URL=http://backend:8080 \
+  stirlingtools/stirling-pdf:unified
+```
+
+### MODE=BACKEND
+Backend API only:
+
+```bash
+docker run -p 8080:8080 \
+  -e MODE=BACKEND \
+  stirlingtools/stirling-pdf:unified
+```
+
+Access API at: `http://localhost:8080/api`
+Swagger UI at: `http://localhost:8080/swagger-ui/index.html`
+
+---
+
+## Architecture
+
+### MODE=BOTH (Default)
+```
+┌─────────────────────────────────────┐
+│     Port 8080 (External)            │
+│  ┌───────────────────────────────┐  │
+│  │         Nginx                 │  │
+│  │  • Serves frontend (/)        │  │
+│  │  • Proxies /api/* → backend   │  │
+│  └───────────┬───────────────────┘  │
+│              │                       │
+│  ┌───────────▼───────────────────┐  │
+│  │    Backend (Internal 8081)    │  │
+│  │  • Spring Boot                │  │
+│  │  • PDF Processing             │  │
+│  │  • UnoServer                  │  │
+│  └───────────────────────────────┘  │
+└─────────────────────────────────────┘
+```
+
+### MODE=FRONTEND
+```
+┌─────────────────────────────┐      ┌──────────────────┐
+│   Frontend Container        │      │  Backend         │
+│   Port 8080                 │      │  (External)      │
+│  ┌───────────────────────┐  │      │                  │
+│  │       Nginx           │  │──────▶  :8080/api       │
+│  │  • Serves frontend    │  │      │                  │
+│  │  • Proxies to backend │  │      │                  │
+│  └───────────────────────┘  │      └──────────────────┘
+└─────────────────────────────┘
+```
+
+### MODE=BACKEND
+```
+┌─────────────────────────────┐
+│   Backend Container         │
+│   Port 8080                 │
+│  ┌───────────────────────┐  │
+│  │   Spring Boot         │  │
+│  │  • API Endpoints      │  │
+│  │  • PDF Processing     │  │
+│  │  • UnoServer          │  │
+│  └───────────────────────┘  │
+└─────────────────────────────┘
+```
+
+---
+
+## Environment Variables
+
+### MODE Configuration
+
+| Variable | Values | Default | Description |
+|----------|--------|---------|-------------|
+| `MODE` | `BOTH`, `FRONTEND`, `BACKEND` | `BOTH` | Container operation mode |
+
+### MODE=BOTH Specific
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BACKEND_INTERNAL_PORT` | `8081` | Internal port for backend when MODE=BOTH |
+
+### MODE=FRONTEND Specific
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VITE_API_BASE_URL` | `http://backend:8080` | Backend URL for API proxying |
+
+### Standard Configuration
+
+All modes support standard Stirling-PDF environment variables:
+
+- `DISABLE_ADDITIONAL_FEATURES` - Enable/disable OCR and LibreOffice features
+- `DOCKER_ENABLE_SECURITY` - Enable authentication
+- `PUID` / `PGID` - User/Group IDs
+- `SYSTEM_MAXFILESIZE` - Max upload size (MB)
+- `TESSERACT_LANGS` - Comma-separated OCR language codes
+- `JAVA_CUSTOM_OPTS` - Additional JVM options
+
+See full configuration docs at: https://docs.stirlingpdf.com
+
+---
+
+## Docker Compose Examples
+
+### Example 1: All-in-One (MODE=BOTH)
+
+**File:** `docker/compose/docker-compose-unified-both.yml`
+
+```yaml
+services:
+  stirling-pdf:
+    image: stirlingtools/stirling-pdf:unified
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./data:/usr/share/tessdata:rw
+      - ./config:/configs:rw
+    environment:
+      MODE: BOTH
+    restart: unless-stopped
+```
+
+### Example 2: Separate Frontend & Backend
+
+**File:** `docker/compose/docker-compose-unified-frontend.yml`
+
+```yaml
+services:
+  backend:
+    image: stirlingtools/stirling-pdf:unified
+    ports:
+      - "8081:8080"
+    environment:
+      MODE: BACKEND
+    volumes:
+      - ./data:/usr/share/tessdata:rw
+      - ./config:/configs:rw
+
+  frontend:
+    image: stirlingtools/stirling-pdf:unified
+    ports:
+      - "8080:8080"
+    environment:
+      MODE: FRONTEND
+      VITE_API_BASE_URL: http://backend:8080
+    depends_on:
+      - backend
+```
+
+### Example 3: Backend API Only
+
+**File:** `docker/compose/docker-compose-unified-backend.yml`
+
+```yaml
+services:
+  stirling-pdf-api:
+    image: stirlingtools/stirling-pdf:unified
+    ports:
+      - "8080:8080"
+    environment:
+      MODE: BACKEND
+    volumes:
+      - ./data:/usr/share/tessdata:rw
+      - ./config:/configs:rw
+    restart: unless-stopped
+```
+
+---
+
+## Building the Image
+
+```bash
+# From repository root
+docker build -t stirlingtools/stirling-pdf:unified -f docker/Dockerfile.unified .
+```
+
+### Build Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `VERSION_TAG` | Version tag for the image |
+
+Example:
+```bash
+docker build \
+  --build-arg VERSION_TAG=v1.0.0 \
+  -t stirlingtools/stirling-pdf:unified \
+  -f docker/Dockerfile.unified .
+```
+
+---
+
+## Use Cases
+
+### 1. Simple Deployment (MODE=BOTH)
+- **Best for:** Personal use, small teams, simple deployments
+- **Pros:** Single container, easy setup, minimal configuration
+- **Cons:** Frontend and backend scale together
+
+### 2. Scaled Frontend (MODE=FRONTEND + BACKEND)
+- **Best for:** High traffic, need to scale frontend independently
+- **Pros:** Scale frontend containers separately, CDN-friendly
+- **Example:**
+  ```yaml
+  services:
+    backend:
+      image: stirlingtools/stirling-pdf:unified
+      environment:
+        MODE: BACKEND
+      deploy:
+        replicas: 1
+
+    frontend:
+      image: stirlingtools/stirling-pdf:unified
+      environment:
+        MODE: FRONTEND
+        VITE_API_BASE_URL: http://backend:8080
+      deploy:
+        replicas: 5  # Scale frontend independently
+  ```
+
+### 3. API-Only (MODE=BACKEND)
+- **Best for:** Headless deployments, custom frontends, API integrations
+- **Pros:** Minimal resources, no nginx overhead
+- **Example:** Use with external frontend or API consumers
+
+### 4. Multi-Backend Setup
+- **Best for:** Load balancing, high availability
+- **Example:**
+  ```yaml
+  services:
+    backend-1:
+      image: stirlingtools/stirling-pdf:unified
+      environment:
+        MODE: BACKEND
+
+    backend-2:
+      image: stirlingtools/stirling-pdf:unified
+      environment:
+        MODE: BACKEND
+
+    frontend:
+      image: stirlingtools/stirling-pdf:unified
+      environment:
+        MODE: FRONTEND
+        VITE_API_BASE_URL: http://load-balancer:8080
+  ```
+
+---
+
+## Port Configuration
+
+All modes use **port 8080** by default:
+
+- **MODE=BOTH**: Nginx listens on 8080, proxies to backend on internal 8081
+- **MODE=FRONTEND**: Nginx listens on 8080
+- **MODE=BACKEND**: Spring Boot listens on 8080
+
+**Expose port 8080** in all configurations:
+```yaml
+ports:
+  - "8080:8080"
+```
+
+---
+
+## Health Checks
+
+### MODE=BOTH and MODE=BACKEND
+```yaml
+healthcheck:
+  test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```
+
+### MODE=FRONTEND
+```yaml
+healthcheck:
+  test: ["CMD-SHELL", "curl -f http://localhost:8080/ || exit 1"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```
+
+---
+
+## Troubleshooting
+
+### Check logs
+```bash
+docker logs stirling-pdf-container
+```
+
+Look for the startup banner:
+```
+===================================
+Stirling-PDF Unified Container
+MODE: BOTH
+===================================
+```
+
+### Invalid MODE error
+```
+ERROR: Invalid MODE 'XYZ'. Must be BOTH, FRONTEND, or BACKEND
+```
+**Fix:** Set `MODE` to one of the three valid values.
+
+### Frontend can't connect to backend (MODE=FRONTEND)
+**Check:**
+1. `VITE_API_BASE_URL` points to correct backend URL
+2. Backend container is running and accessible
+3. Network connectivity between containers
+
+### Backend not starting (MODE=BOTH or BACKEND)
+**Check:**
+1. Sufficient memory allocated (4GB recommended)
+2. Java heap size (`JAVA_CUSTOM_OPTS`)
+3. Volume permissions for `/tmp/stirling-pdf`
+
+---
+
+## Migration Guide
+
+### From Separate Containers → MODE=BOTH
+
+**Before:**
+```yaml
+services:
+  frontend:
+    image: stirlingtools/stirling-pdf:frontend
+    ports: ["80:80"]
+
+  backend:
+    image: stirlingtools/stirling-pdf:backend
+    ports: ["8080:8080"]
+```
+
+**After:**
+```yaml
+services:
+  stirling-pdf:
+    image: stirlingtools/stirling-pdf:unified
+    ports: ["8080:8080"]
+    environment:
+      MODE: BOTH
+```
+
+### From Legacy → MODE=BACKEND
+```yaml
+services:
+  stirling-pdf:
+    image: stirlingtools/stirling-pdf:latest
+    ports: ["8080:8080"]
+```
+
+**Becomes:**
+```yaml
+services:
+  stirling-pdf:
+    image: stirlingtools/stirling-pdf:unified
+    ports: ["8080:8080"]
+    environment:
+      MODE: BACKEND
+```
+
+---
+
+## Performance Tuning
+
+### MODE=BOTH
+```yaml
+environment:
+  JAVA_CUSTOM_OPTS: "-Xmx4g -XX:MaxRAMPercentage=75"
+  BACKEND_INTERNAL_PORT: 8081
+deploy:
+  resources:
+    limits:
+      memory: 4G
+    reservations:
+      memory: 2G
+```
+
+### MODE=FRONTEND (Lightweight)
+```yaml
+deploy:
+  resources:
+    limits:
+      memory: 512M
+    reservations:
+      memory: 256M
+```
+
+### MODE=BACKEND (Heavy Processing)
+```yaml
+environment:
+  JAVA_CUSTOM_OPTS: "-Xmx8g"
+deploy:
+  resources:
+    limits:
+      memory: 10G
+    reservations:
+      memory: 4G
+```
+
+---
+
+## Security Considerations
+
+1. **MODE=BOTH**: Backend not exposed externally (runs on internal port)
+2. **MODE=BACKEND**: API exposed directly - consider API authentication
+3. **MODE=FRONTEND**: Only serves static files - minimal attack surface
+
+Enable security features:
+```yaml
+environment:
+  DOCKER_ENABLE_SECURITY: "true"
+  SECURITY_ENABLELOGIN: "true"
+```
+
+---
+
+## Support
+
+- Documentation: https://docs.stirlingpdf.com
+- GitHub Issues: https://github.com/Stirling-Tools/Stirling-PDF/issues
+- Docker Hub: https://hub.docker.com/r/stirlingtools/stirling-pdf
+
+---
+
+## License
+
+MIT License - See repository for full details
@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Build script for Stirling-PDF Unified Container
+# Usage: ./build.sh [version-tag]
+
+set -e
+
+VERSION_TAG=${1:-latest}
+IMAGE_NAME="stirlingtools/stirling-pdf:unified-${VERSION_TAG}"
+
+echo "==================================="
+echo "Building Stirling-PDF Unified Container"
+echo "Version: $VERSION_TAG"
+echo "Image: $IMAGE_NAME"
+echo "==================================="
+
+# Navigate to repository root (assuming script is in docker/unified/)
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+REPO_ROOT="$SCRIPT_DIR/../.."
+
+cd "$REPO_ROOT"
+
+# Build the image
+docker build \
+  --build-arg VERSION_TAG="$VERSION_TAG" \
+  -t "$IMAGE_NAME" \
+  -f docker/Dockerfile.unified \
+  .
+
+echo "==================================="
+echo "✓ Build complete!"
+echo "Image: $IMAGE_NAME"
+echo ""
+echo "Test the image:"
+echo "  MODE=BOTH:     docker run -p 8080:8080 -e MODE=BOTH $IMAGE_NAME"
+echo "  MODE=FRONTEND: docker run -p 8080:8080 -e MODE=FRONTEND $IMAGE_NAME"
+echo "  MODE=BACKEND:  docker run -p 8080:8080 -e MODE=BACKEND $IMAGE_NAME"
+echo "==================================="
@@ -0,0 +1,176 @@
+#!/bin/bash
+
+set -e
+
+# Default MODE to BOTH if not set
+MODE=${MODE:-BOTH}
+
+echo "==================================="
+echo "Stirling-PDF Unified Container"
+echo "MODE: $MODE"
+echo "==================================="
+
+# Function to setup OCR (from init.sh)
+setup_ocr() {
+    echo "Setting up OCR languages..."
+
+    # Copy tessdata
+    mkdir -p /usr/share/tessdata
+    cp -rn /usr/share/tessdata-original/* /usr/share/tessdata 2>/dev/null || true
+
+    if [ -d /usr/share/tesseract-ocr/4.00/tessdata ]; then
+        cp -r /usr/share/tesseract-ocr/4.00/tessdata/* /usr/share/tessdata 2>/dev/null || true
+    fi
+
+    if [ -d /usr/share/tesseract-ocr/5/tessdata ]; then
+        cp -r /usr/share/tesseract-ocr/5/tessdata/* /usr/share/tessdata 2>/dev/null || true
+    fi
+
+    # Install additional languages if specified
+    if [[ -n "$TESSERACT_LANGS" ]]; then
+        SPACE_SEPARATED_LANGS=$(echo $TESSERACT_LANGS | tr ',' ' ')
+        pattern='^[a-zA-Z]{2,4}(_[a-zA-Z]{2,4})?$'
+        for LANG in $SPACE_SEPARATED_LANGS; do
+            if [[ $LANG =~ $pattern ]]; then
+                apk add --no-cache "tesseract-ocr-data-$LANG" 2>/dev/null || true
+            fi
+        done
+    fi
+}
+
+# Function to setup user permissions (from init-without-ocr.sh)
+setup_permissions() {
+    echo "Setting up user permissions..."
+
+    export JAVA_TOOL_OPTIONS="${JAVA_BASE_OPTS} ${JAVA_CUSTOM_OPTS}"
+
+    # Update user and group IDs
+    if [ ! -z "$PUID" ] && [ "$PUID" != "$(id -u stirlingpdfuser)" ]; then
+        usermod -o -u "$PUID" stirlingpdfuser || true
+    fi
+
+    if [ ! -z "$PGID" ] && [ "$PGID" != "$(getent group stirlingpdfgroup | cut -d: -f3)" ]; then
+        groupmod -o -g "$PGID" stirlingpdfgroup || true
+    fi
+
+    umask "$UMASK" || true
+
+    # Install fonts if needed
+    if [[ -n "$LANGS" ]]; then
+        /scripts/installFonts.sh $LANGS
+    fi
+
+    # Ensure directories exist with correct permissions
+    mkdir -p /tmp/stirling-pdf || true
+
+    # Set ownership and permissions
+    chown -R stirlingpdfuser:stirlingpdfgroup \
+        $HOME /logs /scripts /usr/share/fonts/opentype/noto \
+        /configs /customFiles /pipeline /tmp/stirling-pdf \
+        /var/lib/nginx /var/log/nginx /usr/share/nginx \
+        /app.jar 2>/dev/null || echo "[WARN] Some chown operations failed, may run as host user"
+
+    chmod -R 755 /logs /scripts /usr/share/fonts/opentype/noto \
+        /configs /customFiles /pipeline /tmp/stirling-pdf 2>/dev/null || true
+}
+
+# Function to configure nginx
+configure_nginx() {
+    local backend_url=$1
+    echo "Configuring nginx with backend URL: $backend_url"
+    sed -i "s|\${BACKEND_URL}|${backend_url}|g" /etc/nginx/nginx.conf
+}
+
+# Function to run as user or root depending on permissions
+run_as_user() {
+    if [ "$(id -u)" = "0" ]; then
+        # Running as root, use su-exec
+        su-exec stirlingpdfuser "$@"
+    else
+        # Already running as non-root
+        exec "$@"
+    fi
+}
+
+# Setup OCR and permissions
+setup_ocr
+setup_permissions
+
+# Handle different modes
+case "$MODE" in
+    BOTH)
+        echo "Starting in BOTH mode: Frontend + Backend on port 8080"
+
+        # Configure nginx to proxy to internal backend
+        configure_nginx "http://localhost:${BACKEND_INTERNAL_PORT:-8081}"
+
+        # Start backend on internal port
+        echo "Starting backend on port ${BACKEND_INTERNAL_PORT:-8081}..."
+        run_as_user sh -c "java -Dfile.encoding=UTF-8 \
+            -Djava.io.tmpdir=/tmp/stirling-pdf \
+            -Dserver.port=${BACKEND_INTERNAL_PORT:-8081} \
+            -jar /app.jar" &
+        BACKEND_PID=$!
+
+        # Start unoserver for document conversion
+        run_as_user /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1 &
+        UNO_PID=$!
+
+        # Wait for backend to start
+        sleep 3
+
+        # Start nginx on port 8080
+        echo "Starting nginx on port 8080..."
+        run_as_user nginx -g "daemon off;" &
+        NGINX_PID=$!
+
+        echo "==================================="
+        echo "✓ Frontend available at: http://localhost:8080"
+        echo "✓ Backend API at: http://localhost:8080/api"
+        echo "✓ Backend running internally on port ${BACKEND_INTERNAL_PORT:-8081}"
+        echo "==================================="
+        ;;
+
+    FRONTEND)
+        echo "Starting in FRONTEND mode: Frontend only on port 8080"
+
+        # Configure nginx with external backend URL
+        BACKEND_URL=${VITE_API_BASE_URL:-http://backend:8080}
+        configure_nginx "$BACKEND_URL"
+
+        # Start nginx on port 8080
+        echo "Starting nginx on port 8080..."
+        run_as_user nginx -g "daemon off;" &
+        NGINX_PID=$!
+
+        echo "==================================="
+        echo "✓ Frontend available at: http://localhost:8080"
+        echo "✓ Proxying API calls to: $BACKEND_URL"
+        echo "==================================="
+        ;;
+
+    BACKEND)
+        echo "Starting in BACKEND mode: Backend only on port 8080"
+
+        # Start backend on port 8080
+        echo "Starting backend on port 8080..."
+        run_as_user sh -c "java -Dfile.encoding=UTF-8 \
+            -Djava.io.tmpdir=/tmp/stirling-pdf \
+            -Dserver.port=8080 \
+            -jar /app.jar & /opt/venv/bin/unoserver --port 2003 --interface 127.0.0.1" &
+        BACKEND_PID=$!
+
+        echo "==================================="
+        echo "✓ Backend API available at: http://localhost:8080/api"
+        echo "✓ Swagger UI at: http://localhost:8080/swagger-ui/index.html"
+        echo "==================================="
+        ;;
+
+    *)
+        echo "ERROR: Invalid MODE '$MODE'. Must be BOTH, FRONTEND, or BACKEND"
+        exit 1
+        ;;
+esac
+
+# Wait for all background processes
+wait
@@ -0,0 +1,118 @@
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Add .mjs MIME type mapping
+    types {
+        text/javascript mjs;
+    }
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
+
+    server {
+        listen 8080;
+        server_name _;
+        root /usr/share/nginx/html;
+        index index.html index.htm;
+
+        # Global settings for file uploads
+        client_max_body_size 100m;
+
+        # Handle client-side routing - support subpaths
+        location / {
+            try_files $uri $uri/ /index.html;
+        }
+
+        # Proxy API calls to backend
+        location /api/ {
+            proxy_pass ${BACKEND_URL}/api/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port $server_port;
+
+            # Additional headers for proper API proxying
+            proxy_set_header Connection '';
+            proxy_http_version 1.1;
+            proxy_buffering off;
+            proxy_cache off;
+
+            # Timeout settings for large file uploads
+            proxy_connect_timeout 60s;
+            proxy_send_timeout 60s;
+            proxy_read_timeout 60s;
+
+            # Request size limits for file uploads
+            client_max_body_size 100m;
+            proxy_request_buffering off;
+        }
+
+        # Proxy Swagger UI to backend (including versioned paths)
+        location ~ ^/swagger-ui(.*)$ {
+            proxy_pass ${BACKEND_URL}/swagger-ui$1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port $server_port;
+
+            proxy_set_header Connection '';
+            proxy_http_version 1.1;
+            proxy_buffering off;
+            proxy_cache off;
+        }
+
+        # Proxy API docs to backend (with query parameters and sub-paths)
+        location ~ ^/v3/api-docs(.*)$ {
+            proxy_pass ${BACKEND_URL}/v3/api-docs$1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port $server_port;
+        }
+
+        # Proxy v1 API docs to backend (with query parameters and sub-paths)
+        location ~ ^/v1/api-docs(.*)$ {
+            proxy_pass ${BACKEND_URL}/v1/api-docs$1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Port $server_port;
+        }
+
+        # Serve .mjs files with correct MIME type (must come before general static assets)
+        location ~* \.mjs$ {
+            try_files $uri =404;
+            add_header Content-Type "text/javascript; charset=utf-8" always;
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # Cache static assets
+        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # Security headers
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-XSS-Protection "1; mode=block" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    }
+}
@@ -0,0 +1,35 @@
+# Backend feature audit for frontend-only viability
+
+This note reviews each frontend tool that currently posts to the Java API and summarises what the backend actually does today. For every tool (or small group of closely related tools) the table calls out the implementation details we observed in the Spring controllers/services and whether an equivalent browser-only port looks tractable with the current pdf-lib based helper layer.
+
+| Tool(s) | What the backend does | Frontend-only feasibility |
+| --- | --- | --- |
+| Add Attachments | Streams every uploaded attachment into `PDComplexFileSpecification` entries, updates the embedded files name tree, and toggles the viewer preferences through PDFBox APIs.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AttachmentController.java†L34-L53】【F:app/core/src/main/java/stirling/software/SPDF/service/AttachmentService.java†L28-L104】 | pdf-lib does not expose low-level name tree or attachment primitives today, so we would need significant custom parsing/writing work to recreate the COS dictionaries in the browser. |
+| Add Page Numbers | Iterates every selected page and draws text with precise positioning, font selection (including non Latin fonts), and string templating via `PDPageContentStream` and PDFBox font metrics.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/PageNumbersController.java†L37-L148】 | Achievable but non-trivial—pdf-lib can draw text, yet we would have to reimplement margin presets, font loading, and multi-language font fallbacks in TS. |
+| Add Password / Change Permissions / Remove Password | Loads the document with PDFBox, toggles security flags, and applies `StandardProtectionPolicy` encryption or strips it entirely when removing passwords.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/PasswordController.java†L32-L113】 | Browser tooling has no equivalent for modifying encrypted PDFs; a frontend-only port would require implementing encryption/decryption, which is out of scope. |
+| Add Stamp | Builds either text or image stamps with alpha blending, font loading from bundled TTFs, optional coordinate overrides, and applies them through `PDPageContentStream` for selected pages.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/StampController.java†L52-L167】 | Implemented with pdf-lib in the browser—`addStampClientSide` mirrors the font loading, opacity, and positioning logic so the tool can now run without the backend for supported formats.【F:frontend/src/utils/pdfOperations/addStamp.ts†L1-L120】 |
+| Add Watermark | Mirrors the stamp pipeline but adds image conversion, transparency, and optional PDF-to-image fallback via shared PDF utilities.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java†L64-L153】 | Implemented with pdf-lib in the browser—`addWatermarkClientSide` handles tiled text/image watermarks; the PDF-to-image fallback still requires the server when requested.【F:frontend/src/utils/pdfOperations/addWatermark.ts†L1-L99】 |
+| Adjust Page Scale | Rebuilds each page inside a new document, importing the original page as a form XObject and scaling it with PDFBox’ `LayerUtility` while computing centring offsets.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/ScalePagesController.java†L38-L103】 | Technically possible client-side, but pdf-lib lacks a one-liner for reusing existing content streams; we would need to reimplement the import/scale maths and could run into performance issues for large files. |
+| Auto Rename | Reads the PDF with a custom `PDFTextStripper`, groups text runs by font size, and heuristically picks the biggest headline as the suggested filename.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/AutoRenameController.java†L33-L118】 | pdf-lib has no built-in text extraction; we would have to port PDFBox’ text parsing to JS or rely on wasm, so a browser rewrite is currently impractical. |
+| Automate (pipelines) | Parses the uploaded JSON config and sequentially replays each operation by making internal HTTP calls to the other backend endpoints, managing ZIP outputs and error accumulation.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java†L47-L132】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineProcessor.java†L91-L200】 | Browser-only automation would require reproducing the entire backend orchestration plus every dependent tool in JS, so it is not viable until the individual operations have browser implementations. |
+| Booklet Imposition / Reorganise Pages / Remove Pages | Uses PDFBox to compute saddle-stitch signatures, duplicate/reorder pages, and rebuild the document via form XObjects and layout maths.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/BookletImpositionController.java†L41-L183】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java†L38-L220】 | Simple page removal now ships with a browser implementation (`removePagesClientSide`), but booklet imposition and complex reordering still require backend logic.【F:frontend/src/utils/pdfOperations/removePages.ts†L1-L27】 |
+| Change Metadata / Sanitize | Mutates document info dictionaries, strips XMP blocks, removes JavaScript/embedded files, and walks annotations/forms to clear actions with PDFBox COS access.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/MetadataController.java†L54-L185】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/SanitizeController.java†L46-L198】 | Requires low-level catalog and COS manipulation that pdf-lib exposes only partially; a full port would likely need a dedicated parser/writer to match PDFBox behaviour. |
+| Compress | Chains optional Ghostscript and QPDF CLI invocations, falls back to iterative image recompression inside PDFBox, and manages many temp files to hit the requested target size.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/CompressController.java†L658-L823】 | Impossible to match in-browser without wasm bindings to Ghostscript/QPDF equivalents; image recompression alone would not deliver parity. |
+| Convert (URL → PDF, PDF → PDF/A, etc.) | Delegates to external binaries such as WeasyPrint and LibreOffice before finishing with PDFBox clean-up and metadata stamping.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertWebsiteToPDF.java†L40-L99】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToPDFA.java†L78-L214】 | These flows rely on heavy native tooling; there is no realistic pure-browser substitute today. |
+| Crop / Adjust Layout | Imports each page as a form XObject, applies clipping rectangles, and rebuilds the media box to the requested dimensions with LayerUtility.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/CropController.java†L33-L95】 | Rectangular cropping is now handled in-browser via `cropPdfClientSide`; the advanced layout transformations still lean on the server.【F:frontend/src/utils/pdfOperations/crop.ts†L1-L33】 |
+| Extract Images / Remove Blanks / Flatten | Traverse resources and renderers from PDFBox to locate images, run multithreaded extraction, identify blank pages via PDFRenderer heuristics, or rasterise entire pages when flattening forms.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImagesController.java†L54-L170】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java†L68-L166】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/FlattenController.java†L38-L85】 | Image extraction and blank-page detection depend on PDFBox renderers; replicating them in JS would need a wasm renderer or bespoke canvas logic, so they are currently impractical. |
+| Merge / Overlay PDFs | Loads multiple files, optionally sorts them, stitches pages, builds outlines, and uses PDFBox’ `Overlay` helper to mix foreground/background documents with temp-file juggling.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/MergeController.java†L183-L220】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/PdfOverlayController.java†L39-L200】 | Simple merges are achievable with pdf-lib, but matching TOC generation, overlay modes, and stream-safe stitching would require a sizeable port. |
+| OCR | Chooses between OCRmyPDF and Tesseract CLI runs, manages temporary sidecar files, and merges the results back into a PDF/ZIP response.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java†L76-L214】 | No pure-browser OCR stack offers comparable quality/performance; a wasm bridge to tesseract.js might help, but it would struggle with large PDFs and multi-language pipelines. |
+| Security: Cert Sign / Validate Signature / Remove Cert | Leverages BouncyCastle and PDFBox to embed PKCS#7 signatures, craft visible appearance streams, and validate chains via PKIX path building and revocation checks.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/CertSignController.java†L115-L199】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/ValidateSignatureController.java†L68-L220】 | Browser crypto APIs cannot access arbitrary certificate stores or craft incremental PDF signatures, so these flows must stay server-side. |
+
+## Can our existing frontend libraries cover the remaining gaps?
+
+The browser stack is currently anchored around `pdf-lib` for structural edits and `pdfjs-dist` for rendering support.【F:frontend/package.json†L8-L67】 Those libraries are excellent for page re-ordering, lightweight drawing, and viewer presentation, but the backend-only tools above depend on capabilities that pdf-lib and pdf.js simply do not expose today:
+
+* **Encryption and permission management** – The password tools use PDFBox’ `StandardProtectionPolicy` workflow to set encryption keys, permission flags, and to strip security when unlocking documents.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/PasswordController.java†L32-L113】 None of the shipped frontend libraries can generate or remove those encrypted revisions, so we cannot match the backend feature-set in the browser.
+* **Low-level catalog and attachment access** – Adding attachments reaches into the embedded-file name tree, constructs `PDComplexFileSpecification` objects, and rewrites viewer preferences.【F:app/core/src/main/java/stirling/software/SPDF/service/AttachmentService.java†L28-L104】 Metadata sanitisation follows a similar COS-level pattern. pdf-lib intentionally hides these PDF internals, leaving no straightforward way to recreate the same structures client-side.
+* **Rasterisation-heavy flows** – Compression, blank-page removal, and full-page flattening all rely on PDFBox renderers plus optional Ghostscript/QPDF passes for image recompression and heuristic detection.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/CompressController.java†L44-L205】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/BlankPageController.java†L68-L166】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/FlattenController.java†L38-L85】 Replicating those pipelines in pure TypeScript would require shipping large wasm builds of the same engines.
+* **External binary orchestration** – Converters and OCR call out to native tools such as LibreOffice, WeasyPrint, OCRmyPDF, and Tesseract, marshalling intermediate files before re-wrapping the results.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToPDFA.java†L78-L214】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/misc/OCRController.java†L76-L214】 Without comparable browser binaries we cannot achieve parity for those tasks.
+* **Digital signatures and certificate validation** – Signing invokes BouncyCastle to parse keystores, craft PKCS#7 envelopes, and paint visible signature appearances, while validation performs PKIX path building and revocation checks.【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/CertSignController.java†L1-L199】【F:app/core/src/main/java/stirling/software/SPDF/controller/api/security/ValidateSignatureController.java†L68-L220】 Browser crypto APIs deliberately omit those PDF-specific primitives.
+
+Because the features we still need from PDFBox span encryption, name-tree rewrites, rasterisation, native CLI orchestration, and advanced cryptography, the current frontend libraries cannot satisfy the outstanding requirements on their own. A wasm port of a native PDF engine would be required before we could retire these backend endpoints.
@@ -0,0 +1,55 @@
+# Frontend tool dependency overview
+
+This document summarises how each Stirling PDF frontend tool currently executes its work, identifying whether the implementation already runs entirely in the browser or relies on backend REST APIs.
+
+## Key observations
+
+* With the exception of a handful of tools, the React hooks delegate processing to `useToolOperation`, which ultimately posts the selected files to backend endpoints via `apiClient.post`.【F:frontend/src/hooks/tools/shared/useToolOperation.ts†L213-L267】【F:frontend/src/hooks/tools/shared/useToolApiCalls.ts†L19-L103】
+* Automation flows rely on the same backend-driven operations through the shared executor, which performs direct Axios POST requests and ZIP handling.【F:frontend/src/utils/automationExecutor.ts†L52-L127】
+* **Adjust Contrast** and **Remove Annotations** remain pure client-side processors today, and **Rotate** now offers an optional browser-based mode powered by `pdf-lib`, while Swagger UI is a static documentation viewer. All other PDF manipulations depend on backend services.
+
+## Tool matrix
+
+| Tool | Operation Hook(s) | Endpoint(s) | Frontend-only viability |
+| --- | --- | --- | --- |
+| AddAttachments | AddAttachments: frontend/src/hooks/tools/addAttachments/useAddAttachmentsOperation.ts【F:frontend/src/hooks/tools/addAttachments/useAddAttachmentsOperation.ts†L2-L33】 | AddAttachments: /api/v1/misc/add-attachments【F:frontend/src/hooks/tools/addAttachments/useAddAttachmentsOperation.ts†L2-L33】 | Requires backend API for PDF processing |
+| AddPageNumbers | AddPageNumbers: frontend/src/components/tools/addPageNumbers/useAddPageNumbersOperation.ts【F:frontend/src/components/tools/addPageNumbers/useAddPageNumbersOperation.ts†L2-L31】 | AddPageNumbers: /api/v1/misc/add-page-numbers【F:frontend/src/components/tools/addPageNumbers/useAddPageNumbersOperation.ts†L2-L31】 | Requires backend API for PDF processing |
+| AddPassword | AddPassword: frontend/src/hooks/tools/addPassword/useAddPasswordOperation.ts【F:frontend/src/hooks/tools/addPassword/useAddPasswordOperation.ts†L2-L39】 | AddPassword: /api/v1/security/add-password【F:frontend/src/hooks/tools/addPassword/useAddPasswordOperation.ts†L2-L39】 | Requires backend API for PDF processing |
+| AddStamp | AddStamp: frontend/src/components/tools/addStamp/useAddStampOperation.ts【F:frontend/src/components/tools/addStamp/useAddStampOperation.ts†L2-L65】 | AddStamp: /api/v1/misc/add-stamp【F:frontend/src/components/tools/addStamp/useAddStampOperation.ts†L2-L65】 | Toggle between backend processing and new browser stamping pipeline using pdf-lib【F:frontend/src/components/tools/addStamp/useAddStampOperation.ts†L2-L65】【F:frontend/src/utils/pdfOperations/addStamp.ts†L1-L120】 |
+| AddWatermark | AddWatermark: frontend/src/hooks/tools/addWatermark/useAddWatermarkOperation.ts【F:frontend/src/hooks/tools/addWatermark/useAddWatermarkOperation.ts†L2-L65】 | AddWatermark: /api/v1/security/add-watermark【F:frontend/src/hooks/tools/addWatermark/useAddWatermarkOperation.ts†L2-L65】 | Toggle between backend processing and new browser watermarking pipeline using pdf-lib【F:frontend/src/hooks/tools/addWatermark/useAddWatermarkOperation.ts†L2-L65】【F:frontend/src/utils/pdfOperations/addWatermark.ts†L1-L99】 |
+| AdjustContrast | AdjustContrast: frontend/src/hooks/tools/adjustContrast/useAdjustContrastOperation.ts【F:frontend/src/hooks/tools/adjustContrast/useAdjustContrastOperation.ts†L2-L89】 | — | Already frontend-only (client-side implementation) |
+| AdjustPageScale | AdjustPageScale: frontend/src/hooks/tools/adjustPageScale/useAdjustPageScaleOperation.ts【F:frontend/src/hooks/tools/adjustPageScale/useAdjustPageScaleOperation.ts†L2-L25】 | AdjustPageScale: /api/v1/general/scale-pages【F:frontend/src/hooks/tools/adjustPageScale/useAdjustPageScaleOperation.ts†L2-L25】 | Requires backend API for PDF processing |
+| AutoRename | AutoRename: frontend/src/hooks/tools/autoRename/useAutoRenameOperation.ts【F:frontend/src/hooks/tools/autoRename/useAutoRenameOperation.ts†L2-L38】 | AutoRename: /api/v1/misc/auto-rename【F:frontend/src/hooks/tools/autoRename/useAutoRenameOperation.ts†L2-L38】 | Requires backend API for PDF processing |
+| Automate | Automate: frontend/src/hooks/tools/automate/useAutomateOperation.ts【F:frontend/src/hooks/tools/automate/useAutomateOperation.ts†L1-L45】 | — | Requires backend API for PDF processing |
+| BookletImposition | BookletImposition: frontend/src/hooks/tools/bookletImposition/useBookletImpositionOperation.ts【F:frontend/src/hooks/tools/bookletImposition/useBookletImpositionOperation.ts†L2-L33】 | BookletImposition: /api/v1/general/booklet-imposition【F:frontend/src/hooks/tools/bookletImposition/useBookletImpositionOperation.ts†L2-L33】 | Requires backend API for PDF processing |
+| CertSign | CertSign: frontend/src/hooks/tools/certSign/useCertSignOperation.ts【F:frontend/src/hooks/tools/certSign/useCertSignOperation.ts†L2-L67】 | CertSign: /api/v1/security/cert-sign【F:frontend/src/hooks/tools/certSign/useCertSignOperation.ts†L2-L67】 | Requires backend API for PDF processing |
+| ChangeMetadata | ChangeMetadata: frontend/src/hooks/tools/changeMetadata/useChangeMetadataOperation.ts【F:frontend/src/hooks/tools/changeMetadata/useChangeMetadataOperation.ts†L2-L66】 | ChangeMetadata: /api/v1/misc/update-metadata【F:frontend/src/hooks/tools/changeMetadata/useChangeMetadataOperation.ts†L2-L66】 | Requires backend API for PDF processing |
+| ChangePermissions | ChangePermissions: frontend/src/hooks/tools/changePermissions/useChangePermissionsOperation.ts【F:frontend/src/hooks/tools/changePermissions/useChangePermissionsOperation.ts†L2-L37】 | ChangePermissions: /api/v1/security/add-password【F:frontend/src/hooks/tools/changePermissions/useChangePermissionsOperation.ts†L2-L37】 | Requires backend API for PDF processing |
+| Compress | Compress: frontend/src/hooks/tools/compress/useCompressOperation.ts【F:frontend/src/hooks/tools/compress/useCompressOperation.ts†L2-L37】 | Compress: /api/v1/misc/compress-pdf【F:frontend/src/hooks/tools/compress/useCompressOperation.ts†L2-L37】 | Requires backend API for PDF processing |
+| Convert | Convert: frontend/src/hooks/tools/convert/useConvertOperation.ts【F:frontend/src/hooks/tools/convert/useConvertOperation.ts†L6-L156】 | — | Requires backend API for PDF processing |
+| Crop | Crop: frontend/src/hooks/tools/crop/useCropOperation.ts【F:frontend/src/hooks/tools/crop/useCropOperation.ts†L2-L45】 | Crop: /api/v1/general/crop【F:frontend/src/hooks/tools/crop/useCropOperation.ts†L2-L45】 | Toggle between backend processing and new browser cropping pipeline using pdf-lib【F:frontend/src/hooks/tools/crop/useCropOperation.ts†L2-L45】【F:frontend/src/utils/pdfOperations/crop.ts†L1-L33】 |
+| ExtractImages | ExtractImages: frontend/src/hooks/tools/extractImages/useExtractImagesOperation.ts【F:frontend/src/hooks/tools/extractImages/useExtractImagesOperation.ts†L3-L36】 | ExtractImages: /api/v1/misc/extract-images【F:frontend/src/hooks/tools/extractImages/useExtractImagesOperation.ts†L3-L36】 | Requires backend API for PDF processing |
+| Flatten | Flatten: frontend/src/hooks/tools/flatten/useFlattenOperation.ts【F:frontend/src/hooks/tools/flatten/useFlattenOperation.ts†L2-L27】 | Flatten: /api/v1/misc/flatten【F:frontend/src/hooks/tools/flatten/useFlattenOperation.ts†L2-L27】 | Requires backend API for PDF processing |
+| Merge | Merge: frontend/src/hooks/tools/merge/useMergeOperation.ts【F:frontend/src/hooks/tools/merge/useMergeOperation.ts†L2-L34】 | Merge: /api/v1/general/merge-pdfs【F:frontend/src/hooks/tools/merge/useMergeOperation.ts†L2-L34】 | Requires backend API for PDF processing |
+| OCR | OCR: frontend/src/hooks/tools/ocr/useOCROperation.ts【F:frontend/src/hooks/tools/ocr/useOCROperation.ts†L4-L124】 | OCR: /api/v1/misc/ocr-pdf【F:frontend/src/hooks/tools/ocr/useOCROperation.ts†L4-L124】 | Requires backend API for PDF processing |
+| OverlayPdfs | OverlayPdfs: frontend/src/hooks/tools/overlayPdfs/useOverlayPdfsOperation.ts【F:frontend/src/hooks/tools/overlayPdfs/useOverlayPdfsOperation.ts†L2-L38】 | OverlayPdfs: /api/v1/general/overlay-pdfs【F:frontend/src/hooks/tools/overlayPdfs/useOverlayPdfsOperation.ts†L2-L38】 | Requires backend API for PDF processing |
+| PageLayout | PageLayout: frontend/src/hooks/tools/pageLayout/usePageLayoutOperation.ts【F:frontend/src/hooks/tools/pageLayout/usePageLayoutOperation.ts†L2-L25】 | PageLayout: /api/v1/general/multi-page-layout【F:frontend/src/hooks/tools/pageLayout/usePageLayoutOperation.ts†L2-L25】 | Requires backend API for PDF processing |
+| Redact | Redact: frontend/src/hooks/tools/redact/useRedactOperation.ts【F:frontend/src/hooks/tools/redact/useRedactOperation.ts†L2-L46】 | Redact: /api/v1/security/auto-redact【F:frontend/src/hooks/tools/redact/useRedactOperation.ts†L2-L46】 | Requires backend API for PDF processing |
+| RemoveAnnotations | RemoveAnnotations: frontend/src/hooks/tools/removeAnnotations/useRemoveAnnotationsOperation.ts【F:frontend/src/hooks/tools/removeAnnotations/useRemoveAnnotationsOperation.ts†L2-L92】 | — | Already frontend-only (client-side implementation) |
+| RemoveBlanks | RemoveBlanks: frontend/src/hooks/tools/removeBlanks/useRemoveBlanksOperation.ts【F:frontend/src/hooks/tools/removeBlanks/useRemoveBlanksOperation.ts†L3-L34】 | RemoveBlanks: /api/v1/misc/remove-blanks【F:frontend/src/hooks/tools/removeBlanks/useRemoveBlanksOperation.ts†L3-L34】 | Requires backend API for PDF processing |
+| RemoveCertificateSign | RemoveCertificateSign: frontend/src/hooks/tools/removeCertificateSign/useRemoveCertificateSignOperation.ts【F:frontend/src/hooks/tools/removeCertificateSign/useRemoveCertificateSignOperation.ts†L2-L25】 | RemoveCertificateSign: /api/v1/security/remove-cert-sign【F:frontend/src/hooks/tools/removeCertificateSign/useRemoveCertificateSignOperation.ts†L2-L25】 | Requires backend API for PDF processing |
+| RemoveImage | RemoveImage: frontend/src/hooks/tools/removeImage/useRemoveImageOperation.ts【F:frontend/src/hooks/tools/removeImage/useRemoveImageOperation.ts†L2-L22】 | RemoveImage: /api/v1/general/remove-image-pdf【F:frontend/src/hooks/tools/removeImage/useRemoveImageOperation.ts†L2-L22】 | Requires backend API for PDF processing |
+| RemovePages | RemovePages: frontend/src/hooks/tools/removePages/useRemovePagesOperation.ts【F:frontend/src/hooks/tools/removePages/useRemovePagesOperation.ts†L2-L47】 | RemovePages: /api/v1/general/remove-pages【F:frontend/src/hooks/tools/removePages/useRemovePagesOperation.ts†L2-L47】 | Toggle between backend processing and new browser page removal pipeline using pdf-lib【F:frontend/src/hooks/tools/removePages/useRemovePagesOperation.ts†L2-L47】【F:frontend/src/utils/pdfOperations/removePages.ts†L1-L27】 |
+| RemovePassword | RemovePassword: frontend/src/hooks/tools/removePassword/useRemovePasswordOperation.ts【F:frontend/src/hooks/tools/removePassword/useRemovePasswordOperation.ts†L2-L26】 | RemovePassword: /api/v1/security/remove-password【F:frontend/src/hooks/tools/removePassword/useRemovePasswordOperation.ts†L2-L26】 | Requires backend API for PDF processing |
+| ReorganizePages | ReorganizePages: frontend/src/hooks/tools/reorganizePages/useReorganizePagesOperation.ts【F:frontend/src/hooks/tools/reorganizePages/useReorganizePagesOperation.ts†L2-L28】 | ReorganizePages: /api/v1/general/rearrange-pages【F:frontend/src/hooks/tools/reorganizePages/useReorganizePagesOperation.ts†L2-L28】 | Requires backend API for PDF processing |
+| Repair | Repair: frontend/src/hooks/tools/repair/useRepairOperation.ts【F:frontend/src/hooks/tools/repair/useRepairOperation.ts†L2-L25】 | Repair: /api/v1/misc/repair【F:frontend/src/hooks/tools/repair/useRepairOperation.ts†L2-L25】 | Requires backend API for PDF processing |
+| ReplaceColor | ReplaceColor: frontend/src/hooks/tools/replaceColor/useReplaceColorOperation.ts【F:frontend/src/hooks/tools/replaceColor/useReplaceColorOperation.ts†L2-L34】 | ReplaceColor: /api/v1/misc/replace-invert-pdf【F:frontend/src/hooks/tools/replaceColor/useReplaceColorOperation.ts†L2-L34】 | Requires backend API for PDF processing |
+| Rotate | Rotate: frontend/src/hooks/tools/rotate/useRotateOperation.ts【F:frontend/src/hooks/tools/rotate/useRotateOperation.ts†L1-L35】 | Rotate: /api/v1/general/rotate-pdf【F:frontend/src/hooks/tools/rotate/useRotateOperation.ts†L18-L25】 | Toggle between backend processing and new frontend pdf-lib implementation【F:frontend/src/utils/pdfOperations/rotate.ts†L1-L38】【F:frontend/src/components/tools/rotate/RotateSettings.tsx†L1-L121】 |
+| Sanitize | Sanitize: frontend/src/hooks/tools/sanitize/useSanitizeOperation.ts【F:frontend/src/hooks/tools/sanitize/useSanitizeOperation.ts†L2-L35】 | Sanitize: /api/v1/security/sanitize-pdf【F:frontend/src/hooks/tools/sanitize/useSanitizeOperation.ts†L2-L35】 | Requires backend API for PDF processing |
+| ScannerImageSplit | ScannerImageSplit: frontend/src/hooks/tools/scannerImageSplit/useScannerImageSplitOperation.ts【F:frontend/src/hooks/tools/scannerImageSplit/useScannerImageSplitOperation.ts†L3-L60】 | ScannerImageSplit: /api/v1/misc/extract-image-scans【F:frontend/src/hooks/tools/scannerImageSplit/useScannerImageSplitOperation.ts†L3-L60】 | Requires backend API for PDF processing |
+| Sign | Sign: frontend/src/hooks/tools/sign/useSignOperation.ts【F:frontend/src/hooks/tools/sign/useSignOperation.ts†L2-L55】 | Sign: /api/v1/security/add-signature【F:frontend/src/hooks/tools/sign/useSignOperation.ts†L2-L55】 | Requires backend API for PDF processing |
+| SingleLargePage | SingleLargePage: frontend/src/hooks/tools/singleLargePage/useSingleLargePageOperation.ts【F:frontend/src/hooks/tools/singleLargePage/useSingleLargePageOperation.ts†L2-L25】 | SingleLargePage: /api/v1/general/pdf-to-single-page【F:frontend/src/hooks/tools/singleLargePage/useSingleLargePageOperation.ts†L2-L25】 | Requires backend API for PDF processing |
+| Split | Split: frontend/src/hooks/tools/split/useSplitOperation.ts【F:frontend/src/hooks/tools/split/useSplitOperation.ts†L3-L96】 | Split: getSplitEndpoint【F:frontend/src/hooks/tools/split/useSplitOperation.ts†L3-L96】 | Requires backend API for PDF processing |
+| SwaggerUI | None | N/A | Already frontend-only (documentation viewer) |
+| UnlockPdfForms | UnlockPdfForms: frontend/src/hooks/tools/unlockPdfForms/useUnlockPdfFormsOperation.ts【F:frontend/src/hooks/tools/unlockPdfForms/useUnlockPdfFormsOperation.ts†L2-L25】 | UnlockPdfForms: /api/v1/misc/unlock-pdf-forms【F:frontend/src/hooks/tools/unlockPdfForms/useUnlockPdfFormsOperation.ts†L2-L25】 | Requires backend API for PDF processing |
+| ValidateSignature | ValidateSignature: frontend/src/hooks/tools/validateSignature/useValidateSignatureOperation.ts【F:frontend/src/hooks/tools/validateSignature/useValidateSignatureOperation.ts†L5-L91】 | ValidateSignature: /api/v1/security/validate-signature【F:frontend/src/hooks/tools/validateSignature/useValidateSignatureOperation.ts†L5-L91】 | Requires backend API for PDF processing |
@@ -1,9 +1,10 @@
 // @ts-check

 import eslint from '@eslint/js';
-import globals from "globals";
+import globals from 'globals';
 import { defineConfig } from 'eslint/config';
 import tseslint from 'typescript-eslint';
+import importPlugin from 'eslint-plugin-import';

 const srcGlobs = [
  'src/**/*.{js,mjs,jsx,ts,tsx}',
@@ -14,35 +15,46 @@ const nodeGlobs = [
 ];

 export default defineConfig(
+  {
+    // Everything that contains 3rd party code that we don't want to lint
+    ignores: [
+      'dist',
+      'node_modules',
+      'public',
+    ],
+  },
  eslint.configs.recommended,
  tseslint.configs.recommended,
-  {
-    ignores: [
-      "dist", // Contains 3rd party code
-      "public", // Contains 3rd party code
-    ],
-  },
  {
    rules: {
-      "@typescript-eslint/no-empty-object-type": [
-        "error",
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            ".*", // Disallow any relative imports (they should be '@app/x/y/z' or similar)
+            "src/*", // Disallow any absolute imports (they should be '@app/x/y/z' or similar)
+          ],
+        },
+      ],
+      '@typescript-eslint/no-empty-object-type': [
+        'error',
        {
          // Allow empty extending interfaces because there's no real reason not to, and it makes it obvious where to put extra attributes in the future
          allowInterfaces: 'with-single-extends',
        },
      ],
-      "@typescript-eslint/no-explicit-any": "off", // Temporarily disabled until codebase conformant
-      "@typescript-eslint/no-require-imports": "off", // Temporarily disabled until codebase conformant
-      "@typescript-eslint/no-unused-vars": [
-        "error",
+      '@typescript-eslint/no-explicit-any': 'off', // Temporarily disabled until codebase conformant
+      '@typescript-eslint/no-require-imports': 'off', // Temporarily disabled until codebase conformant
+      '@typescript-eslint/no-unused-vars': [
+        'error',
        {
-          "args": "all", // All function args must be used (or explicitly ignored)
-          "argsIgnorePattern": "^_", // Allow unused variables beginning with an underscore
-          "caughtErrors": "all", // Caught errors must be used (or explicitly ignored)
-          "caughtErrorsIgnorePattern": "^_", // Allow unused variables beginning with an underscore
-          "destructuredArrayIgnorePattern": "^_", // Allow unused variables beginning with an underscore
-          "varsIgnorePattern": "^_", // Allow unused variables beginning with an underscore
-          "ignoreRestSiblings": true, // Allow unused variables when removing attributes from objects (otherwise this requires explicit renaming like `({ x: _x, ...y }) => y`, which is clunky)
+          'args': 'all', // All function args must be used (or explicitly ignored)
+          'argsIgnorePattern': '^_', // Allow unused variables beginning with an underscore
+          'caughtErrors': 'all', // Caught errors must be used (or explicitly ignored)
+          'caughtErrorsIgnorePattern': '^_', // Allow unused variables beginning with an underscore
+          'destructuredArrayIgnorePattern': '^_', // Allow unused variables beginning with an underscore
+          'varsIgnorePattern': '^_', // Allow unused variables beginning with an underscore
+          'ignoreRestSiblings': true, // Allow unused variables when removing attributes from objects (otherwise this requires explicit renaming like `({ x: _x, ...y }) => y`, which is clunky)
        },
      ],
    },
@@ -65,4 +77,21 @@ export default defineConfig(
      }
    }
  },
+  // Config for import plugin
+  {
+    ...importPlugin.flatConfigs.recommended,
+    ...importPlugin.flatConfigs.typescript,
+    rules: {
+      // ...importPlugin.flatConfigs.recommended.rules, // Temporarily disabled until codebase conformant
+      ...importPlugin.flatConfigs.typescript.rules,
+      'import/no-cycle': 'error',
+    },
+    settings: {
+      'import/resolver': {
+        typescript: {
+          project: './tsconfig.json',
+        },
+      },
+    },
+  },
 );
@@ -18,6 +18,6 @@
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
-    <script type="module" src="/src/index.jsx"></script>
+    <script type="module" src="/src/index.tsx"></script>
  </body>
 </html>
@@ -33,6 +33,7 @@
    "@mantine/hooks": "^8.3.1",
    "@mui/icons-material": "^7.3.2",
    "@mui/material": "^7.3.2",
+    "@reactour/tour": "^3.8.0",
    "@tailwindcss/postcss": "^4.1.13",
    "@tanstack/react-virtual": "^3.13.12",
    "autoprefixer": "^10.4.21",
@@ -56,16 +57,20 @@
  },
  "scripts": {
    "predev": "npm run generate-icons",
-    "dev": "npm run typecheck && vite",
+    "dev": "vite",
    "prebuild": "npm run generate-icons",
-    "lint": "eslint",
-    "build": "npm run typecheck && vite build",
+    "lint": "eslint --max-warnings=0",
+    "build": "vite build",
    "preview": "vite preview",
    "typecheck": "tsc --noEmit",
+    "typecheck:core": "tsc --noEmit --project tsconfig.core.json",
+    "typecheck:proprietary": "tsc --noEmit --project tsconfig.proprietary.json",
+    "typecheck:all": "npm run typecheck:core && npm run typecheck:proprietary",
    "check": "npm run typecheck && npm run lint && npm run test:run",
    "generate-licenses": "node scripts/generate-licenses.js",
    "generate-icons": "node scripts/generate-icons.js",
    "generate-icons:verbose": "node scripts/generate-icons.js --verbose",
+    "generate-sample-pdf": "node scripts/sample-pdf/generate.mjs",
    "test": "vitest",
    "test:run": "vitest run",
    "test:watch": "vitest --watch",
@@ -118,6 +123,8 @@
    "@vitejs/plugin-react-swc": "^4.1.0",
    "@vitest/coverage-v8": "^3.2.4",
    "eslint": "^9.36.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
    "eslint-plugin-react-hooks": "^5.2.0",
    "jsdom": "^27.0.0",
    "license-checker": "^25.0.1",
@@ -126,9 +133,11 @@
    "postcss-cli": "^11.0.1",
    "postcss-preset-mantine": "^1.18.0",
    "postcss-simple-vars": "^7.0.1",
+    "puppeteer": "^24.25.0",
    "typescript": "^5.9.2",
    "typescript-eslint": "^8.44.1",
    "vite": "^7.1.7",
+    "vite-tsconfig-paths": "^5.1.4",
    "vitest": "^3.2.4"
  },
  "depcheck": {
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
+  <path d="M17.05 20.28c-.98.95-2.05.8-3.08.35-1.09-.46-2.09-.48-3.24 0-1.44.62-2.2.44-3.06-.35C2.79 15.25 3.51 7.59 9.05 7.31c1.35.07 2.29.74 3.08.8 1.18-.24 2.31-.93 3.57-.84 1.51.12 2.65.72 3.4 1.8-3.12 1.87-2.38 5.98.48 7.13-.57 1.5-1.31 2.99-2.54 4.09l.01-.01zM12.03 7.25c-.15-2.23 1.66-4.07 3.74-4.25.29 2.58-2.34 4.5-3.74 4.25z"/>
+</svg>
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 23 23" fill="none">
+  <path d="M0 0h10.5v10.5H0V0z" fill="#F25022"/>
+  <path d="M12.5 0H23v10.5H12.5V0z" fill="#7FBA00"/>
+  <path d="M0 12.5h10.5V23H0V12.5z" fill="#00A4EF"/>
+  <path d="M12.5 12.5H23V23H12.5V12.5z" fill="#FFB900"/>
+</svg>
@@ -0,0 +1,3 @@
+<svg width="37" height="36" viewBox="0 0 37 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M18.5 3.3125C16.5712 3.3125 14.6613 3.6924 12.8793 4.43052C11.0974 5.16864 9.47823 6.25051 8.11437 7.61437C5.35993 10.3688 3.8125 14.1046 3.8125 18C3.8125 24.4919 8.02781 29.9997 13.8588 31.9531C14.5931 32.0706 14.8281 31.6153 14.8281 31.2187V28.7366C10.7597 29.6178 9.89312 26.7684 9.89312 26.7684C9.2175 25.0647 8.26281 24.6094 8.26281 24.6094C6.92625 23.6987 8.36562 23.7281 8.36562 23.7281C9.83437 23.8309 10.6128 25.2409 10.6128 25.2409C11.8906 27.4734 14.0497 26.8125 14.8869 26.46C15.0191 25.5053 15.4009 24.8591 15.8122 24.4919C12.5516 24.1247 9.12937 22.8616 9.12937 17.2656C9.12937 15.6353 9.6875 14.3281 10.6422 13.2853C10.4953 12.9181 9.98125 11.3906 10.7891 9.40781C10.7891 9.40781 12.0228 9.01125 14.8281 10.9059C15.9884 10.5828 17.2516 10.4212 18.5 10.4212C19.7484 10.4212 21.0116 10.5828 22.1719 10.9059C24.9772 9.01125 26.2109 9.40781 26.2109 9.40781C27.0188 11.3906 26.5047 12.9181 26.3578 13.2853C27.3125 14.3281 27.8706 15.6353 27.8706 17.2656C27.8706 22.8762 24.4338 24.11 21.1584 24.4772C21.6872 24.9325 22.1719 25.8284 22.1719 27.1944V31.2187C22.1719 31.6153 22.4069 32.0853 23.1559 31.9531C28.9869 29.985 33.1875 24.4919 33.1875 18C33.1875 16.0712 32.8076 14.1613 32.0695 12.3793C31.3314 10.5974 30.2495 8.97823 28.8856 7.61437C27.5218 6.25051 25.9026 5.16864 24.1207 4.43052C22.3387 3.6924 20.4288 3.3125 18.5 3.3125Z" fill="black"/>
+</svg>
@@ -0,0 +1,14 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_2781_85129)">
+<path d="M8.36055 0.789432C5.96258 1.62131 3.89457 3.20024 2.46029 5.29431C1.026 7.38838 0.301037 9.8872 0.391883 12.4237C0.482728 14.9603 1.38459 17.4008 2.96501 19.3869C4.54543 21.373 6.72109 22.8 9.17243 23.4582C11.1598 23.971 13.2419 23.9935 15.2399 23.5238C17.0499 23.1172 18.7233 22.2476 20.0962 21.0001C21.5251 19.662 22.5622 17.9597 23.0962 16.0763C23.6765 14.0282 23.7798 11.8743 23.3981 9.78006H12.2381V14.4094H18.7012C18.572 15.1478 18.2952 15.8525 17.8873 16.4814C17.4795 17.1102 16.9489 17.6504 16.3274 18.0694C15.5382 18.5915 14.6485 18.9428 13.7156 19.1007C12.7798 19.2747 11.82 19.2747 10.8843 19.1007C9.93591 18.9046 9.03874 18.5132 8.24993 17.9513C6.98271 17.0543 6.0312 15.7799 5.53118 14.3101C5.02271 12.8127 5.02271 11.1893 5.53118 9.69193C5.8871 8.64234 6.47549 7.68669 7.25243 6.89631C8.14154 5.97521 9.26718 5.3168 10.5058 4.99332C11.7445 4.66985 13.0484 4.6938 14.2743 5.06256C15.232 5.35654 16.1078 5.87019 16.8318 6.56256C17.5606 5.83756 18.2881 5.11068 19.0143 4.38193C19.3893 3.99006 19.7981 3.61693 20.1674 3.21568C19.0622 2.1872 17.765 1.38691 16.3499 0.860682C13.7731 -0.0749615 10.9536 -0.100106 8.36055 0.789432Z" fill="white"/>
+<path d="M8.3607 0.789367C10.9536 -0.100776 13.7731 -0.0762934 16.3501 0.858742C17.7654 1.38855 19.062 2.19269 20.1657 3.22499C19.7907 3.62624 19.3951 4.00124 19.0126 4.39124C18.2851 5.11749 17.5582 5.84124 16.832 6.56249C16.1079 5.87012 15.2321 5.35648 14.2745 5.06249C13.0489 4.69244 11.7451 4.66711 10.5061 4.98926C9.26712 5.31141 8.14079 5.96861 7.2507 6.88874C6.47377 7.67912 5.88538 8.63477 5.52945 9.68437L1.64258 6.67499C3.03384 3.91604 5.44273 1.80566 8.3607 0.789367Z" fill="#E33629"/>
+<path d="M0.611401 9.65654C0.820316 8.62116 1.16716 7.61847 1.64265 6.67529L5.52953 9.69217C5.02105 11.1896 5.02105 12.8129 5.52953 14.3103C4.23453 15.3103 2.9389 16.3153 1.64265 17.3253C0.452308 14.9559 0.0892746 12.2562 0.611401 9.65654Z" fill="#F8BD00"/>
+<path d="M12.2381 9.77783H23.3981C23.7799 11.8721 23.6766 14.026 23.0963 16.0741C22.5623 17.9575 21.5252 19.6597 20.0963 20.9978C18.8419 20.0191 17.5819 19.0478 16.3275 18.0691C16.9494 17.6496 17.4802 17.1089 17.8881 16.4793C18.296 15.8498 18.5726 15.1444 18.7013 14.4053H12.2381C12.2363 12.8641 12.2381 11.321 12.2381 9.77783Z" fill="#587DBD"/>
+<path d="M1.64062 17.3251C2.93687 16.3251 4.2325 15.3201 5.5275 14.3101C6.02851 15.7804 6.98138 17.0549 8.25 17.9513C9.04126 18.5106 9.94037 18.8988 10.89 19.0913C11.8257 19.2653 12.7855 19.2653 13.7212 19.0913C14.6542 18.9334 15.5439 18.5821 16.3331 18.0601C17.5875 19.0388 18.8475 20.0101 20.1019 20.9888C18.7292 22.237 17.0558 23.1073 15.2456 23.5144C13.2476 23.9841 11.1655 23.9616 9.17812 23.4488C7.60632 23.0291 6.13814 22.2893 4.86562 21.2757C3.51874 20.2063 2.41867 18.8588 1.64062 17.3251Z" fill="#319F43"/>
+</g>
+<defs>
+<clipPath id="clip0_2781_85129">
+<rect width="24" height="24" fill="white"/>
+</clipPath>
+</defs>
+</svg>
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 23 23" fill="none">
+  <path d="M0 0h10.5v10.5H0V0z" fill="#F25022"/>
+  <path d="M12.5 0H23v10.5H12.5V0z" fill="#7FBA00"/>
+  <path d="M0 12.5h10.5V23H0V12.5z" fill="#00A4EF"/>
+  <path d="M12.5 12.5H23V23H12.5V12.5z" fill="#FFB900"/>
+</svg>
@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * Stirling PDF Sample Document Generator
+ *
+ * This script uses Puppeteer to generate a sample PDF from a HTML template.
+ * The output is used in the onboarding tour and as a demo document
+ * for users to experiment with Stirling PDF's features.
+ */
+
+import puppeteer from 'puppeteer';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync, mkdirSync, statSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const TEMPLATE_PATH = join(__dirname, 'template.html');
+const OUTPUT_DIR = join(__dirname, '../../public/samples');
+const OUTPUT_PATH = join(OUTPUT_DIR, 'Sample.pdf');
+
+async function generatePDF() {
+  console.log('🚀 Starting Stirling PDF sample document generation...\n');
+
+  // Ensure output directory exists
+  if (!existsSync(OUTPUT_DIR)) {
+    mkdirSync(OUTPUT_DIR, { recursive: true });
+    console.log(`✅ Created output directory: ${OUTPUT_DIR}`);
+  }
+
+  // Check if template exists
+  if (!existsSync(TEMPLATE_PATH)) {
+    console.error(`❌ Template file not found: ${TEMPLATE_PATH}`);
+    process.exit(1);
+  }
+
+  console.log(`📄 Reading template: ${TEMPLATE_PATH}`);
+
+  let browser;
+  try {
+    // Launch Puppeteer
+    console.log('🌐 Launching browser...');
+    browser = await puppeteer.launch({
+      headless: 'new',
+      args: ['--no-sandbox', '--disable-setuid-sandbox']
+    });
+
+    const page = await browser.newPage();
+
+    // Set viewport to match A4 proportions
+    await page.setViewport({
+      width: 794,  // A4 width in pixels at 96 DPI
+      height: 1123, // A4 height in pixels at 96 DPI
+      deviceScaleFactor: 2 // Higher quality rendering
+    });
+
+    // Navigate to the template file
+    const fileUrl = `file://${TEMPLATE_PATH}`;
+    console.log('📖 Loading HTML template...');
+    await page.goto(fileUrl, {
+      waitUntil: 'networkidle0' // Wait for all resources to load
+    });
+
+    // Generate PDF with A4 dimensions
+    console.log('📝 Generating PDF...');
+    await page.pdf({
+      path: OUTPUT_PATH,
+      format: 'A4',
+      printBackground: true,
+      margin: {
+        top: 0,
+        right: 0,
+        bottom: 0,
+        left: 0
+      },
+      preferCSSPageSize: true
+    });
+
+    console.log('\n✅ PDF generated successfully!');
+    console.log(`📦 Output: ${OUTPUT_PATH}`);
+
+    // Get file size
+    const stats = statSync(OUTPUT_PATH);
+    const fileSizeInKB = (stats.size / 1024).toFixed(2);
+    console.log(`📊 File size: ${fileSizeInKB} KB`);
+
+  } catch (error) {
+    console.error('\n❌ Error generating PDF:', error.message);
+    process.exit(1);
+  } finally {
+    if (browser) {
+      await browser.close();
+      console.log('🔒 Browser closed.');
+    }
+  }
+
+  console.log('\n🎉 Done! Sample PDF is ready for use in Stirling PDF.\n');
+}
+
+// Run the generator
+generatePDF().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
@@ -0,0 +1,432 @@
+/* Stirling PDF Sample Document Styles */
+
+:root {
+  /* Brand Colors */
+  --brand-red: #8e3231;
+  --brand-blue: #3b82f6;
+
+  /* Category Colors */
+  --color-general: #3b82f6;
+  --color-security: #f59e0b;
+  --color-formatting: #8b5cf6;
+  --color-automation: #ec4899;
+
+  /* Neutral Colors */
+  --color-black: #111827;
+  --color-gray-dark: #4b5563;
+  --color-gray-medium: #6b7280;
+  --color-gray-light: #e5e7eb;
+  --color-gray-lighter: #f3f4f6;
+  --color-white: #ffffff;
+
+  /* Font Stack */
+  --font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+                  'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: var(--font-family);
+  color: var(--color-black);
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Page Structure - A4 Dimensions */
+.page {
+  width: 210mm;
+  height: 297mm;
+  background: white;
+  page-break-after: always;
+  position: relative;
+  overflow: hidden;
+}
+
+.page:last-child {
+  page-break-after: auto;
+}
+
+/* Page 1: Hero / Cover */
+.page-1 {
+  background: var(--brand-red);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  overflow: hidden;
+}
+
+/* Decorative shapes container */
+.decorative-shapes {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  z-index: 0;
+}
+
+.shape {
+  position: absolute;
+}
+
+/* Logo SVG shape - top-right */
+.shape-1 {
+  top: -120px;
+  right: -100px;
+  width: 450px;
+  height: auto;
+  opacity: 0.12;
+}
+
+/* Logo SVG shape - top-left */
+.shape-2 {
+  top: -80px;
+  left: -80px;
+  width: 350px;
+  height: auto;
+  opacity: 0.08;
+}
+
+/* Logo SVG shape - bottom-left */
+.shape-3 {
+  bottom: -180px;
+  left: -150px;
+  width: 550px;
+  height: auto;
+  opacity: 0.15;
+}
+
+/* Logo SVG shape - bottom-right */
+.shape-4 {
+  bottom: -100px;
+  right: -120px;
+  width: 400px;
+  height: auto;
+  opacity: 0.1;
+}
+
+/* Small accent shape center-right */
+.shape-5 {
+  top: 50%;
+  right: -30px;
+  width: 200px;
+  height: auto;
+  opacity: 0.08;
+  transform: translateY(-50%);
+}
+
+.hero-content {
+  text-align: center;
+  padding: 60px;
+  position: relative;
+  z-index: 1;
+}
+
+.logo-container {
+  margin-bottom: 48px;
+  position: relative;
+}
+
+.hero-logo {
+  width: 280px;
+  height: auto;
+}
+
+.hero-tagline {
+  font-size: 32px;
+  font-weight: 600;
+  color: var(--color-white);
+  margin-bottom: 32px;
+  line-height: 1.3;
+}
+
+.hero-stats {
+  margin-bottom: 40px;
+}
+
+.stat-badge {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 24px 48px;
+  background: rgba(255, 255, 255, 0.95);
+  border-radius: 16px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
+}
+
+.stat-number {
+  font-size: 48px;
+  font-weight: 700;
+  color: var(--brand-red);
+  line-height: 1;
+}
+
+.stat-label {
+  font-size: 18px;
+  color: var(--color-gray-dark);
+  margin-top: 8px;
+  font-weight: 500;
+}
+
+.hero-features {
+  display: flex;
+  justify-content: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+
+.feature-pill {
+  padding: 12px 24px;
+  background: rgba(255, 255, 255, 0.2);
+  color: white;
+  border-radius: 24px;
+  font-size: 16px;
+  font-weight: 500;
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  backdrop-filter: blur(10px);
+}
+
+/* Page 2: What is Stirling PDF */
+.page-2 {
+  padding: 60px;
+}
+
+.content-wrapper {
+  max-width: 700px;
+  margin: 0 auto;
+}
+
+.page-title {
+  font-size: 36px;
+  font-weight: 700;
+  color: var(--brand-red);
+  margin-bottom: 24px;
+  border-bottom: 4px solid var(--brand-red);
+  padding-bottom: 16px;
+}
+
+.intro-text {
+  font-size: 16px;
+  color: var(--color-gray-dark);
+  margin-bottom: 48px;
+  line-height: 1.8;
+}
+
+.value-props {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 32px;
+}
+
+.value-prop {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.value-icon {
+  width: 48px;
+  height: 48px;
+  color: var(--brand-red);
+  margin-bottom: 8px;
+}
+
+.value-icon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.value-prop h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: var(--color-black);
+}
+
+.value-prop p {
+  font-size: 14px;
+  color: var(--color-gray-dark);
+  line-height: 1.6;
+}
+
+/* Page 3: Key Features */
+.page-3 {
+  padding: 60px;
+}
+
+.features-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 24px;
+  margin-bottom: 32px;
+}
+
+.feature-card {
+  background: white;
+  border: 2px solid var(--color-gray-light);
+  border-radius: 12px;
+  padding: 24px;
+  transition: all 0.2s ease;
+}
+
+.feature-card[data-category="general"] {
+  border-color: var(--color-general);
+}
+
+.feature-card[data-category="security"] {
+  border-color: var(--color-security);
+}
+
+.feature-card[data-category="formatting"] {
+  border-color: var(--color-formatting);
+}
+
+.feature-card[data-category="automation"] {
+  border-color: var(--color-automation);
+}
+
+.feature-header {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.feature-icon-large {
+  width: 40px;
+  height: 40px;
+  flex-shrink: 0;
+}
+
+.feature-card[data-category="general"] .feature-icon-large {
+  color: var(--color-general);
+}
+
+.feature-card[data-category="security"] .feature-icon-large {
+  color: var(--color-security);
+}
+
+.feature-card[data-category="formatting"] .feature-icon-large {
+  color: var(--color-formatting);
+}
+
+.feature-card[data-category="automation"] .feature-icon-large {
+  color: var(--color-automation);
+}
+
+.feature-icon-large svg {
+  width: 100%;
+  height: 100%;
+}
+
+.feature-card h3 {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--color-black);
+}
+
+.feature-list {
+  list-style: none;
+  padding: 0;
+}
+
+.feature-list li {
+  font-size: 14px;
+  color: var(--color-gray-dark);
+  padding: 6px 0;
+  padding-left: 20px;
+  position: relative;
+}
+
+.feature-list li::before {
+  content: "•";
+  position: absolute;
+  left: 0;
+  color: var(--brand-red);
+  font-weight: bold;
+}
+
+.additional-features {
+  background: white;
+  border: 2px solid var(--brand-red);
+  padding: 24px;
+  border-radius: 12px;
+  margin-top: 24px;
+}
+
+.additional-features-header {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.additional-features-icon {
+  width: 40px;
+  height: 40px;
+  color: var(--brand-red);
+  flex-shrink: 0;
+}
+
+.additional-features-icon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.additional-features h3 {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--color-black);
+  margin: 0;
+}
+
+.additional-features-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 32px;
+}
+
+.additional-features-grid ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.additional-features-grid li {
+  font-size: 15px;
+  color: var(--color-gray-dark);
+  padding: 4px 0;
+  padding-left: 24px;
+  position: relative;
+  line-height: 1.5;
+}
+
+.additional-features-grid li::before {
+  content: "•";
+  position: absolute;
+  left: 0;
+  color: var(--brand-red);
+  font-weight: bold;
+  font-size: 18px;
+}
+
+/* Print Styles */
+@media print {
+  body {
+    margin: 0;
+    padding: 0;
+  }
+
+  .page {
+    margin: 0;
+    border: none;
+    box-shadow: none;
+  }
+}
@@ -0,0 +1,234 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Stirling PDF - Sample Document</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <!-- Page 1: Hero / Cover Page -->
+  <div class="page page-1">
+    <div class="decorative-shapes">
+      <img src="../../public/branding/StirlingPDFLogoNoTextLight.svg" class="shape shape-1" alt="">
+      <img src="../../public/branding/StirlingPDFLogoNoTextDark.svg" class="shape shape-2" alt="">
+      <img src="../../public/branding/StirlingPDFLogoNoTextLight.svg" class="shape shape-3" alt="">
+      <img src="../../public/branding/StirlingPDFLogoNoTextDark.svg" class="shape shape-4" alt="">
+      <img src="../../public/branding/StirlingPDFLogoNoTextLight.svg" class="shape shape-5" alt="">
+    </div>
+    <div class="hero-content">
+      <div class="logo-container">
+        <img src="../../public/branding/StirlingPDFLogoWhiteText.svg" alt="Stirling PDF" class="hero-logo">
+      </div>
+      <h1 class="hero-tagline">The Free Adobe Acrobat Alternative</h1>
+      <div class="hero-stats">
+        <div class="stat-badge">
+          <span class="stat-number">10M+</span>
+          <span class="stat-label">Downloads</span>
+        </div>
+      </div>
+      <div class="hero-features">
+        <div class="feature-pill">Open Source</div>
+        <div class="feature-pill">Privacy First</div>
+        <div class="feature-pill">Self-Hosted</div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Page 2: What is Stirling PDF -->
+  <div class="page page-2">
+    <div class="content-wrapper">
+      <h2 class="page-title">What is Stirling PDF?</h2>
+      <p class="intro-text">
+        Stirling PDF is a robust, web-based PDF manipulation tool.
+        It enables you to carry out various operations on PDF files, including splitting,
+        merging, converting, rearranging, adding images, rotating, compressing, and more.
+      </p>
+
+      <div class="value-props">
+        <div class="value-prop">
+          <div class="value-icon">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z" />
+            </svg>
+          </div>
+          <h3>50+ PDF Operations</h3>
+          <p>Comprehensive toolkit covering all your PDF needs. From basic operations to advanced processing.</p>
+        </div>
+
+        <div class="value-prop">
+          <div class="value-icon">
+            <svg viewBox="0 0 24 24" fill="currentColor">
+              <path d="M7.4 17.25q-1.05.875-2.187.8t-1.988-.775t-1.162-1.837t.412-2.338L4.35 10q-.625-.55-.987-1.325T3 7q0-1.65 1.175-2.825T7 3t2.825 1.175T11 7T9.825 9.825T7 11q-.225 0-.45-.025t-.425-.075L4.2 14.15q-.275.45-.175.888t.425.712t.775.313t.875-.313l10.5-9.025q1.05-.875 2.2-.788t2 .788t1.15 1.838t-.425 2.337L19.65 14q.625.55.988 1.325T21 17q0 1.65-1.175 2.825T17 21t-2.825-1.175T13 17t1.175-2.825T17 13q.225 0 .438.025t.412.075l1.95-3.25q.275-.45.175-.888t-.425-.712t-.775-.312t-.875.312zM7 9q.825 0 1.413-.587T9 7t-.587-1.412T7 5t-1.412.588T5 7t.588 1.413T7 9m10 10q.825 0 1.413-.587T19 17t-.587-1.412T17 15t-1.412.588T15 17t.588 1.413T17 19m0-2" />
+            </svg>
+          </div>
+          <h3>Workflow Automation</h3>
+          <p>Chain multiple operations together and save them as reusable workflows. Perfect for recurring tasks.</p>
+        </div>
+
+        <div class="value-prop">
+          <div class="value-icon">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <circle cx="12" cy="12" r="10" />
+              <line x1="2" y1="12" x2="22" y2="12" />
+              <path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z" />
+            </svg>
+          </div>
+          <h3>Multi-Language Support</h3>
+          <p>Available in over 30 languages with community-contributed translations. Accessible to users worldwide.</p>
+        </div>
+
+        <div class="value-prop">
+          <div class="value-icon">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <rect x="5" y="11" width="14" height="10" rx="2" />
+              <circle cx="12" cy="16" r="1" />
+              <path d="M8 11V7a4 4 0 0 1 8 0v4" />
+            </svg>
+          </div>
+          <h3>Privacy First</h3>
+          <p>Self-hosted solution means your data stays on your infrastructure. You have full control over your documents.</p>
+        </div>
+
+        <div class="value-prop">
+          <div class="value-icon">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <circle cx="12" cy="12" r="10" />
+              <path d="m9 12 2 2 4-4" />
+            </svg>
+          </div>
+          <h3>Open Source</h3>
+          <p>Transparent, community-driven development. Inspect the code, contribute features, and adapt as needed.</p>
+        </div>
+
+        <div class="value-prop">
+          <div class="value-icon">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <polyline points="16 18 22 12 16 6" />
+              <polyline points="8 6 2 12 8 18" />
+            </svg>
+          </div>
+          <h3>API Access</h3>
+          <p>RESTful API for integration with external tools and scripts. Automate PDF operations programmatically.</p>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Page 3: Key Features -->
+  <div class="page page-3">
+    <div class="content-wrapper">
+      <h2 class="page-title">Key Features</h2>
+
+      <div class="features-grid">
+        <div class="feature-card" data-category="general">
+          <div class="feature-header">
+            <div class="feature-icon-large">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+                <polyline points="14 2 14 8 20 8" />
+                <line x1="16" y1="13" x2="8" y2="13" />
+                <line x1="16" y1="17" x2="8" y2="17" />
+                <polyline points="10 9 9 9 8 9" />
+              </svg>
+            </div>
+            <h3>Page Operations</h3>
+          </div>
+          <ul class="feature-list">
+            <li>Merge & split PDFs</li>
+            <li>Rearrange pages</li>
+            <li>Rotate & crop</li>
+            <li>Extract pages</li>
+            <li>Multi-page layout</li>
+          </ul>
+        </div>
+
+        <div class="feature-card" data-category="security">
+          <div class="feature-header">
+            <div class="feature-icon-large">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <rect x="3" y="11" width="18" height="11" rx="2" ry="2" />
+                <path d="M7 11V7a5 5 0 0 1 10 0v4" />
+              </svg>
+            </div>
+            <h3>Security & Signing</h3>
+          </div>
+          <ul class="feature-list">
+            <li>Password protection</li>
+            <li>Digital signatures</li>
+            <li>Watermarks</li>
+            <li>Permission controls</li>
+            <li>Redaction tools</li>
+          </ul>
+        </div>
+
+        <div class="feature-card" data-category="formatting">
+          <div class="feature-header">
+            <div class="feature-icon-large">
+              <svg viewBox="0 0 24 24" fill="currentColor">
+                <path d="m5.825 17l1.9 1.9q.3.3.288.7t-.313.7q-.3.275-.7.288t-.7-.288l-3.6-3.6q-.15-.15-.213-.325T2.426 16t.063-.375t.212-.325l3.6-3.6q.275-.275.688-.275t.712.275q.3.3.3.713t-.3.712L5.825 15H20q.425 0 .713.288T21 16t-.288.713T20 17zm12.35-8H4q-.425 0-.712-.288T3 8t.288-.712T4 7h14.175l-1.9-1.9q-.3-.3-.287-.7t.312-.7q.3-.275.7-.288t.7.288l3.6 3.6q.15.15.213.325t.062.375t-.062.375t-.213.325l-3.6 3.6q-.275.275-.687.275T16.3 12.3q-.3-.3-.3-.712t.3-.713z" />
+              </svg>
+            </div>
+            <h3>File Conversions</h3>
+          </div>
+          <ul class="feature-list">
+            <li>PDF to/from images</li>
+            <li>Office documents</li>
+            <li>HTML to PDF</li>
+            <li>Markdown to PDF</li>
+            <li>PDF to Word/Excel</li>
+          </ul>
+        </div>
+
+        <div class="feature-card" data-category="automation">
+          <div class="feature-header">
+            <div class="feature-icon-large">
+              <svg viewBox="0 0 24 24" fill="currentColor">
+                <path d="M7.4 17.25q-1.05.875-2.187.8t-1.988-.775t-1.162-1.837t.412-2.338L4.35 10q-.625-.55-.987-1.325T3 7q0-1.65 1.175-2.825T7 3t2.825 1.175T11 7T9.825 9.825T7 11q-.225 0-.45-.025t-.425-.075L4.2 14.15q-.275.45-.175.888t.425.712t.775.313t.875-.313l10.5-9.025q1.05-.875 2.2-.788t2 .788t1.15 1.838t-.425 2.337L19.65 14q.625.55.988 1.325T21 17q0 1.65-1.175 2.825T17 21t-2.825-1.175T13 17t1.175-2.825T17 13q.225 0 .438.025t.412.075l1.95-3.25q.275-.45.175-.888t-.425-.712t-.775-.312t-.875.312zM7 9q.825 0 1.413-.587T9 7t-.587-1.412T7 5t-1.412.588T5 7t.588 1.413T7 9m10 10q.825 0 1.413-.587T19 17t-.587-1.412T17 15t-1.412.588T15 17t.588 1.413T17 19m0-2" />
+              </svg>
+            </div>
+            <h3>Automation</h3>
+          </div>
+          <ul class="feature-list">
+            <li>Multi-step workflows</li>
+            <li>Chain PDF operations</li>
+            <li>Save recurring tasks</li>
+            <li>Batch file processing</li>
+            <li>API integration</li>
+          </ul>
+        </div>
+      </div>
+
+      <div class="additional-features">
+        <div class="additional-features-header">
+          <div class="additional-features-icon">
+            <svg viewBox="0 0 24 24" fill="currentColor">
+              <path d="M6 20q-.825 0-1.4125-.5875T4 18t.5875-1.4125T6 16t1.4125.5875T8 18t-.5875 1.4125T6 20m6 0q-.825 0-1.4125-.5875T10 18t.5875-1.4125T12 16t1.4125.5875T14 18t-.5875 1.4125T12 20m6 0q-.825 0-1.4125-.5875T16 18t.5875-1.4125T18 16t1.4125.5875T20 18t-.5875 1.4125T18 20M6 14q-.825 0-1.4125-.5875T4 12t.5875-1.4125T6 10t1.4125.5875T8 12t-.5875 1.4125T6 14m6 0q-.825 0-1.4125-.5875T10 12t.5875-1.4125T12 10t1.4125.5875T14 12t-.5875 1.4125T12 14m6 0q-.825 0-1.4125-.5875T16 12t.5875-1.4125T18 10t1.4125.5875T20 12t-.5875 1.4125T18 14M6 8q-.825 0-1.4125-.5875T4 6t.5875-1.4125T6 4t1.4125.5875T8 6t-.5875 1.4125T6 8m6 0q-.825 0-1.4125-.5875T10 6t.5875-1.4125T12 4t1.4125.5875T14 6t-.5875 1.4125T12 8m6 0q-.825 0-1.4125-.5875T16 6t.5875-1.4125T18 4t1.4125.5875T20 6t-.5875 1.4125T18 8" />
+            </svg>
+          </div>
+          <h3>Plus Many More</h3>
+        </div>
+        <div class="additional-features-grid">
+          <ul>
+            <li>OCR text recognition</li>
+            <li>Compress PDFs</li>
+            <li>Add images & stamps</li>
+            <li>Detect blank pages</li>
+            <li>Extract images</li>
+            <li>Edit metadata</li>
+          </ul>
+          <ul>
+            <li>Flatten forms</li>
+            <li>PDF/A conversion</li>
+            <li>Add page numbers</li>
+            <li>Remove pages</li>
+            <li>Repair PDFs</li>
+            <li>And 40+ more tools</li>
+          </ul>
+        </div>
+      </div>
+    </div>
+  </div>
+
+</body>
+</html>
@@ -1,38 +0,0 @@
-.App {
-  text-align: center;
-}
-
-.App-logo {
-  height: 40vmin;
-  pointer-events: none;
-}
-
-@media (prefers-reduced-motion: no-preference) {
-  .App-logo {
-    animation: App-logo-spin infinite 20s linear;
-  }
-}
-
-.App-header {
-  background-color: #282c34;
-  min-height: 100vh;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  font-size: calc(10px + 2vmin);
-  color: white;
-}
-
-.App-link {
-  color: #61dafb;
-}
-
-@keyframes App-logo-spin {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
-}
@@ -1,70 +0,0 @@
-import { Suspense } from "react";
-import { RainbowThemeProvider } from "./components/shared/RainbowThemeProvider";
-import { FileContextProvider } from "./contexts/FileContext";
-import { NavigationProvider } from "./contexts/NavigationContext";
-import { FilesModalProvider } from "./contexts/FilesModalContext";
-import { ToolWorkflowProvider } from "./contexts/ToolWorkflowContext";
-import { HotkeyProvider } from "./contexts/HotkeyContext";
-import { SidebarProvider } from "./contexts/SidebarContext";
-import { PreferencesProvider } from "./contexts/PreferencesContext";
-import ErrorBoundary from "./components/shared/ErrorBoundary";
-import HomePage from "./pages/HomePage";
-
-// Import global styles
-import "./styles/tailwind.css";
-import "./styles/cookieconsent.css";
-import "./index.css";
-import { RightRailProvider } from "./contexts/RightRailContext";
-import { ViewerProvider } from "./contexts/ViewerContext";
-import { SignatureProvider } from "./contexts/SignatureContext";
-
-// Import file ID debugging helpers (development only)
-import "./utils/fileIdSafety";
-
-// Loading component for i18next suspense
-const LoadingFallback = () => (
-  <div
-    style={{
-      display: "flex",
-      justifyContent: "center",
-      alignItems: "center",
-      height: "100vh",
-      fontSize: "18px",
-      color: "#666",
-    }}
-  >
-    Loading...
-  </div>
-);
-
-export default function App() {
-  return (
-    <Suspense fallback={<LoadingFallback />}>
-      <RainbowThemeProvider>
-        <ErrorBoundary>
-          <PreferencesProvider>
-            <FileContextProvider enableUrlSync={true} enablePersistence={true}>
-              <NavigationProvider>
-                <FilesModalProvider>
-                  <ToolWorkflowProvider>
-                    <HotkeyProvider>
-                      <SidebarProvider>
-                        <ViewerProvider>
-                          <SignatureProvider>
-                            <RightRailProvider>
-                              <HomePage />
-                            </RightRailProvider>
-                          </SignatureProvider>
-                        </ViewerProvider>
-                      </SidebarProvider>
-                    </HotkeyProvider>
-                  </ToolWorkflowProvider>
-                </FilesModalProvider>
-              </NavigationProvider>
-            </FileContextProvider>
-          </PreferencesProvider>
-        </ErrorBoundary>
-      </RainbowThemeProvider>
-    </Suspense>
-  );
-}
@@ -1,502 +0,0 @@
-import React, { useCallback, useState, useEffect, useMemo } from 'react';
-import { ActionIcon, Divider, Popover } from '@mantine/core';
-import LocalIcon from './LocalIcon';
-import './rightRail/RightRail.css';
-import { useToolWorkflow } from '../../contexts/ToolWorkflowContext';
-import { useRightRail } from '../../contexts/RightRailContext';
-import { useFileState, useFileSelection, useFileManagement, useFileContext } from '../../contexts/FileContext';
-import { useNavigationState } from '../../contexts/NavigationContext';
-import { useTranslation } from 'react-i18next';
-
-import LanguageSelector from '../shared/LanguageSelector';
-import { useRainbowThemeContext } from '../shared/RainbowThemeProvider';
-import { Tooltip } from '../shared/Tooltip';
-import BulkSelectionPanel from '../pageEditor/BulkSelectionPanel';
-import { SearchInterface } from '../viewer/SearchInterface';
-import { ViewerContext } from '../../contexts/ViewerContext';
-import { useSignature } from '../../contexts/SignatureContext';
-import ViewerAnnotationControls from './rightRail/ViewerAnnotationControls';
-
-import { parseSelection } from '../../utils/bulkselection/parseSelection';
-
-
-import { useSidebarContext } from '../../contexts/SidebarContext';
-
-export default function RightRail() {
-  const { sidebarRefs } = useSidebarContext();
-  const { t } = useTranslation();
-  const [isPanning, setIsPanning] = useState(false);
-
-  // Viewer context for PDF controls - safely handle when not available
-  const viewerContext = React.useContext(ViewerContext);
-  const { toggleTheme } = useRainbowThemeContext();
-  const { buttons, actions, allButtonsDisabled } = useRightRail();
-
-  const topButtons = useMemo(() => buttons.filter(b => (b.section || 'top') === 'top' && (b.visible ?? true)), [buttons]);
-
-  // Access PageEditor functions for page-editor-specific actions
-  const { pageEditorFunctions, toolPanelMode, leftPanelView } = useToolWorkflow();
-  const disableForFullscreen = toolPanelMode === 'fullscreen' && leftPanelView === 'toolPicker';
-
-  // CSV input state for page selection
-  const [csvInput, setCsvInput] = useState<string>("");
-
-  // Navigation view
-  const { workbench: currentView } = useNavigationState();
-  const isCustomWorkbench = typeof currentView === 'string' && currentView.startsWith('custom:');
-
-  // File state and selection
-  const { state, selectors } = useFileState();
-  const { actions: fileActions } = useFileContext();
-  const { selectedFiles, selectedFileIds, setSelectedFiles } = useFileSelection();
-  const { removeFiles } = useFileManagement();
-
-  // Signature context for checking if signatures have been applied
-  const { signaturesApplied } = useSignature();
-
-  const activeFiles = selectors.getFiles();
-  const filesSignature = selectors.getFilesSignature();
-
-  // Compute selection state and total items
-  const getSelectionState = useCallback(() => {
-    if (currentView === 'fileEditor' || currentView === 'viewer') {
-      const totalItems = activeFiles.length;
-      const selectedCount = selectedFileIds.length;
-      return { totalItems, selectedCount };
-    }
-
-    if (currentView === 'pageEditor') {
-      // Use PageEditor's own state
-      const totalItems = pageEditorFunctions?.totalPages || 0;
-      const selectedCount = pageEditorFunctions?.selectedPageIds?.length || 0;
-      return { totalItems, selectedCount };
-    }
-
-    return { totalItems: 0, selectedCount: 0 };
-  }, [currentView, activeFiles, selectedFileIds, pageEditorFunctions]);
-
-  const { totalItems, selectedCount } = getSelectionState();
-
-  // Get export state for viewer mode
-  const exportState = viewerContext?.getExportState?.();
-
-  const handleSelectAll = useCallback(() => {
-    if (currentView === 'fileEditor' || currentView === 'viewer') {
-      // Select all file IDs
-      const allIds = state.files.ids;
-      setSelectedFiles(allIds);
-      // Clear any previous error flags when selecting all
-      try { fileActions.clearAllFileErrors(); } catch (_e) { void _e; }
-      return;
-    }
-
-    if (currentView === 'pageEditor') {
-      // Use PageEditor's select all function
-      pageEditorFunctions?.handleSelectAll?.();
-    }
-  }, [currentView, state.files.ids, setSelectedFiles, pageEditorFunctions]);
-
-  const handleDeselectAll = useCallback(() => {
-    if (currentView === 'fileEditor' || currentView === 'viewer') {
-      setSelectedFiles([]);
-      // Clear any previous error flags when deselecting all
-      try { fileActions.clearAllFileErrors(); } catch (_e) { void _e; }
-      return;
-    }
-    if (currentView === 'pageEditor') {
-      // Use PageEditor's deselect all function
-      pageEditorFunctions?.handleDeselectAll?.();
-    }
-  }, [currentView, setSelectedFiles, pageEditorFunctions]);
-
-  const handleExportAll = useCallback(async () => {
-    if (currentView === 'viewer') {
-      // Check if signatures have been applied
-      if (!signaturesApplied) {
-        alert('You have unapplied signatures. Please use "Apply Signatures" first before exporting.');
-        return;
-      }
-
-      // Use EmbedPDF export functionality for viewer mode
-      viewerContext?.exportActions?.download();
-    } else if (currentView === 'fileEditor') {
-      // Download selected files (or all if none selected)
-      const filesToDownload = selectedFiles.length > 0 ? selectedFiles : activeFiles;
-
-      filesToDownload.forEach(file => {
-        const link = document.createElement('a');
-        link.href = URL.createObjectURL(file);
-        link.download = file.name;
-        document.body.appendChild(link);
-        link.click();
-        document.body.removeChild(link);
-        URL.revokeObjectURL(link.href);
-      });
-    } else if (currentView === 'pageEditor') {
-      // Export all pages (not just selected)
-      pageEditorFunctions?.onExportAll?.();
-    }
-  }, [currentView, activeFiles, selectedFiles, pageEditorFunctions, viewerContext, signaturesApplied, selectors, fileActions]);
-
-  const handleCloseSelected = useCallback(() => {
-    if (currentView !== 'fileEditor') return;
-    if (selectedFileIds.length === 0) return;
-
-    // Close only selected files (do not delete from storage)
-    removeFiles(selectedFileIds, false);
-
-    // Clear selection after closing
-    setSelectedFiles([]);
-  }, [currentView, selectedFileIds, removeFiles, setSelectedFiles]);
-
-  const updatePagesFromCSV = useCallback((override?: string) => {
-    const maxPages = pageEditorFunctions?.totalPages || 0;
-    const normalized = parseSelection(override ?? csvInput, maxPages);
-    pageEditorFunctions?.handleSetSelectedPages?.(normalized);
-  }, [csvInput, pageEditorFunctions]);
-
-  // Do not overwrite user's expression input when selection changes.
-
-  // Clear CSV input when files change (use stable signature to avoid ref churn)
-  useEffect(() => {
-    setCsvInput("");
-  }, [filesSignature]);
-
-  // Mount/visibility for page-editor-only buttons to allow exit animation, then remove to avoid flex gap
-  const [pageControlsMounted, setPageControlsMounted] = useState<boolean>(currentView === 'pageEditor');
-  const [pageControlsVisible, setPageControlsVisible] = useState<boolean>(currentView === 'pageEditor');
-
-  useEffect(() => {
-    if (currentView === 'pageEditor') {
-      // Mount and show
-      setPageControlsMounted(true);
-      // Next tick to ensure transition applies
-      requestAnimationFrame(() => setPageControlsVisible(true));
-    } else {
-      // Start exit animation
-      setPageControlsVisible(false);
-      // After transition, unmount to remove flex gap
-      const timer = setTimeout(() => setPageControlsMounted(false), 240);
-      return () => clearTimeout(timer);
-    }
-  }, [currentView]);
-
-  return (
-    <div ref={sidebarRefs.rightRailRef} className={`right-rail`} data-sidebar="right-rail">
-      <div className="right-rail-inner">
-        {topButtons.length > 0 && !isCustomWorkbench && (
-          <>
-            <div className="right-rail-section">
-              {topButtons.map(btn => (
-                <Tooltip key={btn.id} content={btn.tooltip} position="left" offset={12} arrow portalTarget={document.body}>
-                  <ActionIcon
-                    variant="subtle"
-                    radius="md"
-                    className="right-rail-icon"
-                    onClick={() => actions[btn.id]?.()}
-                    disabled={btn.disabled || allButtonsDisabled || disableForFullscreen}
-                  >
-                    {btn.icon}
-                  </ActionIcon>
-                </Tooltip>
-              ))}
-            </div>
-            <Divider className="right-rail-divider" />
-          </>
-        )}
-
-        {/* Group: PDF Viewer Controls - visible only in viewer mode */}
-        {!isCustomWorkbench && (
-        <div
-          className={`right-rail-slot ${currentView === 'viewer' ? 'visible right-rail-enter' : 'right-rail-exit'}`}
-          aria-hidden={currentView !== 'viewer'}
-        >
-          <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
-            {/* Search */}
-            <Tooltip content={t('rightRail.search', 'Search PDF')} position="left" offset={12} arrow portalTarget={document.body}>
-              <Popover position="left" withArrow shadow="md" offset={8}>
-                <Popover.Target>
-                  <div style={{ display: 'inline-flex' }}>
-                    <ActionIcon
-                      variant="subtle"
-                      radius="md"
-                      className="right-rail-icon"
-                      disabled={currentView !== 'viewer' || allButtonsDisabled || disableForFullscreen}
-                      aria-label={typeof t === 'function' ? t('rightRail.search', 'Search PDF') : 'Search PDF'}
-                    >
-                      <LocalIcon icon="search" width="1.5rem" height="1.5rem" />
-                    </ActionIcon>
-                  </div>
-                </Popover.Target>
-                <Popover.Dropdown>
-                  <div style={{ minWidth: '20rem' }}>
-                    <SearchInterface
-                      visible={true}
-                      onClose={() => {}}
-                    />
-                  </div>
-                </Popover.Dropdown>
-              </Popover>
-            </Tooltip>
-
-
-            {/* Pan Mode */}
-            <Tooltip content={t('rightRail.panMode', 'Pan Mode')} position="left" offset={12} arrow portalTarget={document.body}>
-              <ActionIcon
-                variant={isPanning ? "filled" : "subtle"}
-                color={isPanning ? "blue" : undefined}
-                radius="md"
-                className="right-rail-icon"
-                onClick={() => {
-                  viewerContext?.panActions.togglePan();
-                  setIsPanning(!isPanning);
-                }}
-                disabled={currentView !== 'viewer' || allButtonsDisabled || disableForFullscreen}
-              >
-                <LocalIcon icon="pan-tool-rounded" width="1.5rem" height="1.5rem" />
-              </ActionIcon>
-            </Tooltip>
-
-            {/* Rotate Left */}
-            <Tooltip content={t('rightRail.rotateLeft', 'Rotate Left')} position="left" offset={12} arrow portalTarget={document.body}>
-              <ActionIcon
-                variant="subtle"
-                radius="md"
-                className="right-rail-icon"
-                onClick={() => {
-                  viewerContext?.rotationActions.rotateBackward();
-                }}
-                disabled={currentView !== 'viewer' || allButtonsDisabled || disableForFullscreen}
-              >
-                <LocalIcon icon="rotate-left" width="1.5rem" height="1.5rem" />
-              </ActionIcon>
-            </Tooltip>
-
-            {/* Rotate Right */}
-            <Tooltip content={t('rightRail.rotateRight', 'Rotate Right')} position="left" offset={12} arrow portalTarget={document.body}>
-              <ActionIcon
-                variant="subtle"
-                radius="md"
-                className="right-rail-icon"
-                onClick={() => {
-                  viewerContext?.rotationActions.rotateForward();
-                }}
-                disabled={currentView !== 'viewer' || allButtonsDisabled || disableForFullscreen}
-              >
-                <LocalIcon icon="rotate-right" width="1.5rem" height="1.5rem" />
-              </ActionIcon>
-            </Tooltip>
-
-            {/* Sidebar Toggle */}
-            <Tooltip content={t('rightRail.toggleSidebar', 'Toggle Sidebar')} position="left" offset={12} arrow portalTarget={document.body}>
-              <ActionIcon
-                variant="subtle"
-                radius="md"
-                className="right-rail-icon"
-                onClick={() => {
-                  viewerContext?.toggleThumbnailSidebar();
-                }}
-                disabled={currentView !== 'viewer' || allButtonsDisabled || disableForFullscreen}
-              >
-                <LocalIcon icon="view-list" width="1.5rem" height="1.5rem" />
-              </ActionIcon>
-            </Tooltip>
-
-            {/* Annotation Controls */}
-            <ViewerAnnotationControls
-              currentView={currentView}
-              disabled={currentView !== 'viewer' || allButtonsDisabled || disableForFullscreen}
-            />
-          </div>
-          <Divider className="right-rail-divider" />
-        </div>
-        )}
-
-        {/* Group: Selection controls + Close, animate as one unit when entering/leaving viewer */}
-        {!isCustomWorkbench && (
-        <div
-          className={`right-rail-slot ${currentView !== 'viewer' ? 'visible right-rail-enter' : 'right-rail-exit'}`}
-          aria-hidden={currentView === 'viewer'}
-        >
-          <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
-            {/* Select All Button */}
-            <Tooltip content={t('rightRail.selectAll', 'Select All')} position="left" offset={12} arrow portalTarget={document.body}>
-              <div>
-                <ActionIcon
-                  variant="subtle"
-                  radius="md"
-                  className="right-rail-icon"
-                  onClick={handleSelectAll}
-                  disabled={currentView === 'viewer' || totalItems === 0 || selectedCount === totalItems || allButtonsDisabled || disableForFullscreen}
-                >
-                  <LocalIcon icon="select-all" width="1.5rem" height="1.5rem" />
-                </ActionIcon>
-              </div>
-            </Tooltip>
-
-            {/* Deselect All Button */}
-            <Tooltip content={t('rightRail.deselectAll', 'Deselect All')} position="left" offset={12} arrow portalTarget={document.body}>
-              <div>
-                <ActionIcon
-                  variant="subtle"
-                  radius="md"
-                  className="right-rail-icon"
-                  onClick={handleDeselectAll}
-                  disabled={currentView === 'viewer' || selectedCount === 0 || allButtonsDisabled || disableForFullscreen}
-                >
-                  <LocalIcon icon="crop-square-outline" width="1.5rem" height="1.5rem" />
-                </ActionIcon>
-              </div>
-            </Tooltip>
-
-            {/* Select by Numbers - page editor only, with animated presence */}
-            {pageControlsMounted && (
-                                  <Tooltip content={t('rightRail.selectByNumber', 'Select by Page Numbers')} position="left" offset={12} arrow portalTarget={document.body}>
-
-              <div className={`right-rail-fade ${pageControlsVisible ? 'enter' : 'exit'}`} aria-hidden={!pageControlsVisible}>
-                <Popover position="left" withArrow shadow="md" offset={8}>
-                  <Popover.Target>
-                      <div style={{ display: 'inline-flex' }}>
-                        <ActionIcon
-                          variant="subtle"
-                          radius="md"
-                          className="right-rail-icon"
-                          disabled={!pageControlsVisible || totalItems === 0 || allButtonsDisabled || disableForFullscreen}
-                          aria-label={typeof t === 'function' ? t('rightRail.selectByNumber', 'Select by Page Numbers') : 'Select by Page Numbers'}
-                        >
-                          <LocalIcon icon="pin-end" width="1.5rem" height="1.5rem" />
-                        </ActionIcon>
-                      </div>
-                  </Popover.Target>
-                  <Popover.Dropdown>
-
-                    <div style={{ minWidth: '24rem', maxWidth: '32rem' }}>
-                      <BulkSelectionPanel
-                        csvInput={csvInput}
-                        setCsvInput={setCsvInput}
-                        selectedPageIds={Array.isArray(pageEditorFunctions?.selectedPageIds) ? pageEditorFunctions.selectedPageIds : []}
-                        displayDocument={pageEditorFunctions?.displayDocument}
-                        onUpdatePagesFromCSV={updatePagesFromCSV}
-                      />
-                    </div>
-                  </Popover.Dropdown>
-                </Popover>
-              </div>
-              </Tooltip>
-
-            )}
-
-            {/* Delete Selected Pages - page editor only, with animated presence */}
-            {pageControlsMounted && (
-                              <Tooltip content={t('rightRail.deleteSelected', 'Delete Selected Pages')} position="left" offset={12} arrow portalTarget={document.body}>
-
-              <div className={`right-rail-fade ${pageControlsVisible ? 'enter' : 'exit'}`} aria-hidden={!pageControlsVisible}>
-                  <div style={{ display: 'inline-flex' }}>
-                    <ActionIcon
-                      variant="subtle"
-                      radius="md"
-                      className="right-rail-icon"
-                      onClick={() => { pageEditorFunctions?.handleDelete?.(); }}
-                      disabled={!pageControlsVisible || (pageEditorFunctions?.selectedPageIds?.length || 0) === 0 || allButtonsDisabled || disableForFullscreen}
-                      aria-label={typeof t === 'function' ? t('rightRail.deleteSelected', 'Delete Selected Pages') : 'Delete Selected Pages'}
-                    >
-                      <LocalIcon icon="delete-outline-rounded" width="1.5rem" height="1.5rem" />
-                    </ActionIcon>
-                  </div>
-              </div>
-              </Tooltip>
-
-            )}
-
-            {/* Export Selected Pages - page editor only */}
-            {pageControlsMounted && (
-              <Tooltip content={t('rightRail.exportSelected', 'Export Selected Pages')} position="left" offset={12} arrow portalTarget={document.body}>
-                <div className={`right-rail-fade ${pageControlsVisible ? 'enter' : 'exit'}`} aria-hidden={!pageControlsVisible}>
-                  <div style={{ display: 'inline-flex' }}>
-                    <ActionIcon
-                      variant="subtle"
-                      radius="md"
-                      className="right-rail-icon"
-                      onClick={() => { pageEditorFunctions?.onExportSelected?.(); }}
-                      disabled={!pageControlsVisible || (pageEditorFunctions?.selectedPageIds?.length || 0) === 0 || pageEditorFunctions?.exportLoading || allButtonsDisabled || disableForFullscreen}
-                      aria-label={typeof t === 'function' ? t('rightRail.exportSelected', 'Export Selected Pages') : 'Export Selected Pages'}
-                    >
-                      <LocalIcon icon="download" width="1.5rem" height="1.5rem" />
-                    </ActionIcon>
-                  </div>
-                </div>
-              </Tooltip>
-            )}
-
-            {/* Close (File Editor: Close Selected | Page Editor: Close PDF) */}
-            <Tooltip content={currentView === 'pageEditor' ? t('rightRail.closePdf', 'Close PDF') : t('rightRail.closeSelected', 'Close Selected Files')} position="left" offset={12} arrow portalTarget={document.body}>
-              <div>
-                <ActionIcon
-                  variant="subtle"
-                  radius="md"
-                  className="right-rail-icon"
-                  onClick={currentView === 'pageEditor' ? () => pageEditorFunctions?.closePdf?.() : handleCloseSelected}
-                  disabled={
-                    currentView === 'viewer' ||
-                    (currentView === 'fileEditor' && selectedCount === 0) ||
-                    (currentView === 'pageEditor' && (activeFiles.length === 0 || !pageEditorFunctions?.closePdf)) ||
-                    allButtonsDisabled || disableForFullscreen
-                  }
-                >
-                  <LocalIcon icon="close-rounded" width="1.5rem" height="1.5rem" />
-                </ActionIcon>
-              </div>
-            </Tooltip>
-          </div>
-
-          <Divider className="right-rail-divider" />
-        </div>
-        )}
-
-        {/* Theme toggle and Language dropdown */}
-        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
-          <Tooltip content={t('rightRail.toggleTheme', 'Toggle Theme')} position="left" offset={12} arrow portalTarget={document.body}
-          >
-            <ActionIcon
-              variant="subtle"
-              radius="md"
-              className="right-rail-icon"
-              onClick={toggleTheme}
-            >
-              <LocalIcon icon="contrast" width="1.5rem" height="1.5rem" />
-            </ActionIcon>
-          </Tooltip>
-
-          <Tooltip content={t('rightRail.language', 'Language')} position="left" offset={12} arrow portalTarget={document.body}>
-            <div style={{ display: 'inline-flex' }}>
-              <LanguageSelector position="left-start" offset={6} compact />
-            </div>
-          </Tooltip>
-
-          <Tooltip content={
-            currentView === 'pageEditor'
-              ? t('rightRail.exportAll', 'Export PDF')
-              : (selectedCount > 0 ? t('rightRail.downloadSelected', 'Download Selected Files') : t('rightRail.downloadAll', 'Download All'))
-          } position="left" offset={12} arrow portalTarget={document.body}>
-            <div>
-              <ActionIcon
-                variant="subtle"
-                radius="md"
-                className="right-rail-icon"
-                onClick={handleExportAll}
-                disabled={
-                  disableForFullscreen || (currentView === 'viewer' ? !exportState?.canExport : totalItems === 0 || allButtonsDisabled)
-                }
-              >
-                <LocalIcon icon="download" width="1.5rem" height="1.5rem" />
-              </ActionIcon>
-            </div>
-          </Tooltip>
-        </div>
-
-        <div className="right-rail-spacer" />
-      </div>
-    </div>
-  );
-}
-
@@ -1,64 +0,0 @@
-import React from 'react';
-import { NavKey } from './types';
-import HotkeysSection from './configSections/HotkeysSection';
-import GeneralSection from './configSections/GeneralSection';
-
-export interface ConfigNavItem {
-  key: NavKey;
-  label: string;
-  icon: string;
-  component: React.ReactNode;
-}
-
-export interface ConfigNavSection {
-  title: string;
-  items: ConfigNavItem[];
-}
-
-export interface ConfigColors {
-  navBg: string;
-  sectionTitle: string;
-  navItem: string;
-  navItemActive: string;
-  navItemActiveBg: string;
-  contentBg: string;
-  headerBorder: string;
-}
-
-export const createConfigNavSections = (
-  Overview: React.ComponentType<{ onLogoutClick: () => void }>,
-  onLogoutClick: () => void
-): ConfigNavSection[] => {
-  const sections: ConfigNavSection[] = [
-    {
-      title: 'Account',
-      items: [
-        {
-          key: 'overview',
-          label: 'Overview',
-          icon: 'person-rounded',
-          component: <Overview onLogoutClick={onLogoutClick} />
-        },
-      ],
-    },
-    {
-      title: 'Preferences',
-      items: [
-        {
-          key: 'general',
-          label: 'General',
-          icon: 'settings-rounded',
-          component: <GeneralSection />
-        },
-        {
-          key: 'hotkeys',
-          label: 'Keyboard Shortcuts',
-          icon: 'keyboard-rounded',
-          component: <HotkeysSection />
-        },
-      ],
-    },
-  ];
-
-  return sections;
-};
@@ -1,73 +0,0 @@
-import React, { createContext, useContext, useState, useEffect, useCallback } from 'react';
-import { preferencesService, UserPreferences, DEFAULT_PREFERENCES } from '../services/preferencesService';
-
-interface PreferencesContextValue {
-  preferences: UserPreferences;
-  updatePreference: <K extends keyof UserPreferences>(
-    key: K,
-    value: UserPreferences[K]
-  ) => Promise<void>;
-  resetPreferences: () => Promise<void>;
-  isLoading: boolean;
-}
-
-const PreferencesContext = createContext<PreferencesContextValue | undefined>(undefined);
-
-export const PreferencesProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
-  const [preferences, setPreferences] = useState<UserPreferences>(DEFAULT_PREFERENCES);
-  const [isLoading, setIsLoading] = useState(true);
-
-  useEffect(() => {
-    const loadPreferences = async () => {
-      try {
-        await preferencesService.initialize();
-        const loadedPreferences = await preferencesService.getAllPreferences();
-        setPreferences(loadedPreferences);
-      } catch (error) {
-        console.error('Failed to load preferences:', error);
-        // Keep default preferences on error
-      } finally {
-        setIsLoading(false);
-      }
-    };
-
-    loadPreferences();
-  }, []);
-
-  const updatePreference = useCallback(
-    async <K extends keyof UserPreferences>(key: K, value: UserPreferences[K]) => {
-        await preferencesService.setPreference(key, value);
-        setPreferences((prev) => ({
-          ...prev,
-          [key]: value,
-        }));
-    },
-    []
-  );
-
-  const resetPreferences = useCallback(async () => {
-      await preferencesService.clearAllPreferences();
-      setPreferences(DEFAULT_PREFERENCES);
-  }, []);
-
-  return (
-    <PreferencesContext.Provider
-      value={{
-        preferences,
-        updatePreference,
-        resetPreferences,
-        isLoading,
-      }}
-    >
-      {children}
-    </PreferencesContext.Provider>
-  );
-};
-
-export const usePreferences = (): PreferencesContextValue => {
-  const context = useContext(PreferencesContext);
-  if (!context) {
-    throw new Error('usePreferences must be used within a PreferencesProvider');
-  }
-  return context;
-};
@@ -0,0 +1,24 @@
+import { Suspense } from "react";
+import { AppProviders } from "@app/components/AppProviders";
+import { LoadingFallback } from "@app/components/shared/LoadingFallback";
+import HomePage from "@app/pages/HomePage";
+import OnboardingTour from "@app/components/onboarding/OnboardingTour";
+
+// Import global styles
+import "@app/styles/tailwind.css";
+import "@app/styles/cookieconsent.css";
+import "@app/styles/index.css";
+
+// Import file ID debugging helpers (development only)
+import "@app/utils/fileIdSafety";
+
+export default function App() {
+  return (
+    <Suspense fallback={<LoadingFallback />}>
+      <AppProviders>
+        <HomePage />
+        <OnboardingTour />
+      </AppProviders>
+    </Suspense>
+  );
+}
@@ -0,0 +1,67 @@
+import { ReactNode } from "react";
+import { RainbowThemeProvider } from "@app/components/shared/RainbowThemeProvider";
+import { FileContextProvider } from "@app/contexts/FileContext";
+import { NavigationProvider } from "@app/contexts/NavigationContext";
+import { ToolRegistryProvider } from "@app/contexts/ToolRegistryProvider";
+import { FilesModalProvider } from "@app/contexts/FilesModalContext";
+import { ToolWorkflowProvider } from "@app/contexts/ToolWorkflowContext";
+import { HotkeyProvider } from "@app/contexts/HotkeyContext";
+import { SidebarProvider } from "@app/contexts/SidebarContext";
+import { PreferencesProvider } from "@app/contexts/PreferencesContext";
+import { AppConfigProvider } from "@app/contexts/AppConfigContext";
+import { RightRailProvider } from "@app/contexts/RightRailContext";
+import { ViewerProvider } from "@app/contexts/ViewerContext";
+import { SignatureProvider } from "@app/contexts/SignatureContext";
+import { OnboardingProvider } from "@app/contexts/OnboardingContext";
+import { TourOrchestrationProvider } from "@app/contexts/TourOrchestrationContext";
+import ErrorBoundary from "@app/components/shared/ErrorBoundary";
+import { useScarfTracking } from "@app/hooks/useScarfTracking";
+
+// Component to initialize scarf tracking (must be inside AppConfigProvider)
+function ScarfTrackingInitializer() {
+  useScarfTracking();
+  return null;
+}
+
+/**
+ * Core application providers
+ * Contains all providers needed for the core
+ */
+export function AppProviders({ children }: { children: ReactNode }) {
+  return (
+    <PreferencesProvider>
+      <RainbowThemeProvider>
+        <ErrorBoundary>
+          <OnboardingProvider>
+            <AppConfigProvider>
+              <ScarfTrackingInitializer />
+              <FileContextProvider enableUrlSync={true} enablePersistence={true}>
+                <ToolRegistryProvider>
+                  <NavigationProvider>
+                    <FilesModalProvider>
+                      <ToolWorkflowProvider>
+                        <HotkeyProvider>
+                          <SidebarProvider>
+                            <ViewerProvider>
+                              <SignatureProvider>
+                                <RightRailProvider>
+                                  <TourOrchestrationProvider>
+                                    {children}
+                                  </TourOrchestrationProvider>
+                                </RightRailProvider>
+                              </SignatureProvider>
+                            </ViewerProvider>
+                          </SidebarProvider>
+                        </HotkeyProvider>
+                      </ToolWorkflowProvider>
+                    </FilesModalProvider>
+                  </NavigationProvider>
+                </ToolRegistryProvider>
+              </FileContextProvider>
+            </AppConfigProvider>
+          </OnboardingProvider>
+        </ErrorBoundary>
+      </RainbowThemeProvider>
+    </PreferencesProvider>
+  );
+}
@@ -1,17 +1,17 @@
 import React, { useState, useCallback, useEffect } from 'react';
 import { Modal } from '@mantine/core';
 import { Dropzone } from '@mantine/dropzone';
-import { StirlingFileStub } from '../types/fileContext';
-import { useFileManager } from '../hooks/useFileManager';
-import { useFilesModalContext } from '../contexts/FilesModalContext';
-import { Tool } from '../types/tool';
-import MobileLayout from './fileManager/MobileLayout';
-import DesktopLayout from './fileManager/DesktopLayout';
-import DragOverlay from './fileManager/DragOverlay';
-import { FileManagerProvider } from '../contexts/FileManagerContext';
-import { Z_INDEX_FILE_MANAGER_MODAL } from '../styles/zIndex';
-import { isGoogleDriveConfigured } from '../services/googleDrivePickerService';
-import { loadScript } from '../utils/scriptLoader';
+import { StirlingFileStub } from '@app/types/fileContext';
+import { useFileManager } from '@app/hooks/useFileManager';
+import { useFilesModalContext } from '@app/contexts/FilesModalContext';
+import { Tool } from '@app/types/tool';
+import MobileLayout from '@app/components/fileManager/MobileLayout';
+import DesktopLayout from '@app/components/fileManager/DesktopLayout';
+import DragOverlay from '@app/components/fileManager/DragOverlay';
+import { FileManagerProvider } from '@app/contexts/FileManagerContext';
+import { Z_INDEX_FILE_MANAGER_MODAL } from '@app/styles/zIndex';
+import { isGoogleDriveConfigured } from '@app/services/googleDrivePickerService';
+import { loadScript } from '@app/utils/scriptLoader';

 interface FileManagerProps {
  selectedTool?: Tool | null;
@@ -3,9 +3,9 @@ import { Card, Group, Text, Button, Progress } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import StorageIcon from "@mui/icons-material/Storage";
 import DeleteIcon from "@mui/icons-material/Delete";
-import { StorageStats } from "../services/fileStorage";
-import { formatFileSize } from "../utils/fileUtils";
-import { getStorageUsagePercent } from "../utils/storageUtils";
+import { StorageStats } from "@app/services/fileStorage";
+import { formatFileSize } from "@app/utils/fileUtils";
+import { getStorageUsagePercent } from "@app/utils/storageUtils";

 interface StorageStatsCardProps {
  storageStats: StorageStats | null;
@@ -1,9 +1,9 @@
 import React, { useState } from 'react';
 import { Stack, Alert, Text } from '@mantine/core';
 import { useTranslation } from 'react-i18next';
-import { DrawingControls } from './DrawingControls';
-import { ColorPicker } from './ColorPicker';
-import { usePDFAnnotation } from '../providers/PDFAnnotationProvider';
+import { DrawingControls } from '@app/components/annotation/shared/DrawingControls';
+import { ColorPicker } from '@app/components/annotation/shared/ColorPicker';
+import { usePDFAnnotation } from '@app/components/annotation/providers/PDFAnnotationProvider';

 export interface AnnotationToolConfig {
  enableDrawing?: boolean;
@@ -1,7 +1,7 @@
 import React, { useRef, useState } from 'react';
 import { Paper, Button, Modal, Stack, Text, Popover, ColorPicker as MantineColorPicker } from '@mantine/core';
-import { ColorSwatchButton } from './ColorPicker';
-import PenSizeSelector from '../../tools/sign/PenSizeSelector';
+import { ColorSwatchButton } from '@app/components/annotation/shared/ColorPicker';
+import PenSizeSelector from '@app/components/tools/sign/PenSizeSelector';
 import SignaturePad from 'signature_pad';

 interface DrawingCanvasProps {
@@ -1,7 +1,7 @@
 import React, { useState, useEffect } from 'react';
 import { Stack, TextInput, Select, Combobox, useCombobox, Group, Box } from '@mantine/core';
 import { useTranslation } from 'react-i18next';
-import { ColorPicker } from './ColorPicker';
+import { ColorPicker } from '@app/components/annotation/shared/ColorPicker';

 interface TextInputWithFontProps {
  text: string;
@@ -1,7 +1,7 @@
 import React, { useState } from 'react';
 import { Stack } from '@mantine/core';
-import { BaseAnnotationTool } from '../shared/BaseAnnotationTool';
-import { DrawingCanvas } from '../shared/DrawingCanvas';
+import { BaseAnnotationTool } from '@app/components/annotation/shared/BaseAnnotationTool';
+import { DrawingCanvas } from '@app/components/annotation/shared/DrawingCanvas';

 interface DrawingToolProps {
  onDrawingChange?: (data: string | null) => void;
@@ -1,7 +1,7 @@
 import React, { useState } from 'react';
 import { Stack } from '@mantine/core';
-import { BaseAnnotationTool } from '../shared/BaseAnnotationTool';
-import { ImageUploader } from '../shared/ImageUploader';
+import { BaseAnnotationTool } from '@app/components/annotation/shared/BaseAnnotationTool';
+import { ImageUploader } from '@app/components/annotation/shared/ImageUploader';

 interface ImageToolProps {
  onImageChange?: (data: string | null) => void;
@@ -1,7 +1,7 @@
 import React, { useState } from 'react';
 import { Stack } from '@mantine/core';
-import { BaseAnnotationTool } from '../shared/BaseAnnotationTool';
-import { TextInputWithFont } from '../shared/TextInputWithFont';
+import { BaseAnnotationTool } from '@app/components/annotation/shared/BaseAnnotationTool';
+import { TextInputWithFont } from '@app/components/annotation/shared/TextInputWithFont';

 interface TextToolProps {
  onTextChange?: (text: string) => void;
@@ -2,10 +2,10 @@ import React, { useRef, useState } from 'react';
 import { Button, Group, useMantineColorScheme } from '@mantine/core';
 import { useTranslation } from 'react-i18next';
 import AddIcon from '@mui/icons-material/Add';
-import { useFilesModalContext } from '../../contexts/FilesModalContext';
-import LocalIcon from '../shared/LocalIcon';
-import { BASE_PATH } from '../../constants/app';
-import styles from './FileEditor.module.css';
+import { useFilesModalContext } from '@app/contexts/FilesModalContext';
+import LocalIcon from '@app/components/shared/LocalIcon';
+import { BASE_PATH } from '@app/constants/app';
+import styles from '@app/components/fileEditor/FileEditor.module.css';

 interface AddFileCardProps {
  onFileSelect: (files: File[]) => void;
@@ -9,7 +9,7 @@
  transition: box-shadow 0.18s ease, outline-color 0.18s ease, transform 0.18s ease;
  max-width: 100%;
  max-height: 100%;
-  overflow: hidden;
+  overflow: visible;
  margin-left: 0.5rem;
  margin-right: 0.5rem;
 }
@@ -1,19 +1,19 @@
-import React, { useState, useCallback, useRef, useMemo, useEffect } from 'react';
+import { useState, useCallback, useRef, useMemo, useEffect } from 'react';
 import {
-  Text, Center, Box, LoadingOverlay, Stack, Group
+  Text, Center, Box, LoadingOverlay, Stack
 } from '@mantine/core';
 import { Dropzone } from '@mantine/dropzone';
-import { useFileSelection, useFileState, useFileManagement, useFileActions } from '../../contexts/FileContext';
-import { useNavigationActions } from '../../contexts/NavigationContext';
-import { zipFileService } from '../../services/zipFileService';
-import { detectFileExtension } from '../../utils/fileUtils';
-import FileEditorThumbnail from './FileEditorThumbnail';
-import AddFileCard from './AddFileCard';
-import FilePickerModal from '../shared/FilePickerModal';
-import SkeletonLoader from '../shared/SkeletonLoader';
-import { FileId, StirlingFile } from '../../types/fileContext';
-import { alert } from '../toast';
-import { downloadBlob } from '../../utils/downloadUtils';
+import { useFileSelection, useFileState, useFileManagement, useFileActions, useFileContext } from '@app/contexts/FileContext';
+import { useNavigationActions } from '@app/contexts/NavigationContext';
+import { zipFileService } from '@app/services/zipFileService';
+import { detectFileExtension } from '@app/utils/fileUtils';
+import FileEditorThumbnail from '@app/components/fileEditor/FileEditorThumbnail';
+import AddFileCard from '@app/components/fileEditor/AddFileCard';
+import FilePickerModal from '@app/components/shared/FilePickerModal';
+import { FileId, StirlingFile } from '@app/types/fileContext';
+import { alert } from '@app/components/toast';
+import { downloadBlob } from '@app/utils/downloadUtils';
+import { useFileEditorRightRailButtons } from '@app/components/fileEditor/fileEditorRightRailButtons';


 interface FileEditorProps {
@@ -37,11 +37,15 @@ const FileEditor = ({
  // Use optimized FileContext hooks
  const { state, selectors } = useFileState();
  const { addFiles, removeFiles, reorderFiles } = useFileManagement();
-  const { actions } = useFileActions();
+  const { actions: fileActions } = useFileActions();
+  const { actions: fileContextActions } = useFileContext();
+  const { clearAllFileErrors } = fileContextActions;

  // Extract needed values from state (memoized to prevent infinite loops)
  const activeStirlingFileStubs = useMemo(() => selectors.getStirlingFileStubs(), [selectors.getFilesSignature()]);
  const selectedFileIds = state.ui.selectedFileIds;
+  const totalItems = state.files.ids.length;
+  const selectedCount = selectedFileIds.length;

  // Get navigation actions
  const { actions: navActions } = useNavigationActions();
@@ -68,19 +72,6 @@ const FileEditor = ({
    }
  }, [toolMode]);
  const [showFilePickerModal, setShowFilePickerModal] = useState(false);
-  const [zipExtractionProgress, setZipExtractionProgress] = useState<{
-    isExtracting: boolean;
-    currentFile: string;
-    progress: number;
-    extractedCount: number;
-    totalFiles: number;
-  }>({
-    isExtracting: false,
-    currentFile: '',
-    progress: 0,
-    extractedCount: 0,
-    totalFiles: 0
-  });
  // Get selected file IDs from context (defensive programming)
  const contextSelectedIds = Array.isArray(selectedFileIds) ? selectedFileIds : [];

@@ -91,107 +82,63 @@ const FileEditor = ({
  // Use activeStirlingFileStubs directly - no conversion needed
  const localSelectedIds = contextSelectedIds;

+  const handleSelectAllFiles = useCallback(() => {
+    setSelectedFiles(state.files.ids);
+    try {
+      clearAllFileErrors();
+    } catch (error) {
+      if (process.env.NODE_ENV === 'development') {
+        console.warn('Failed to clear file errors on select all:', error);
+      }
+    }
+  }, [state.files.ids, setSelectedFiles, clearAllFileErrors]);
+
+  const handleDeselectAllFiles = useCallback(() => {
+    setSelectedFiles([]);
+    try {
+      clearAllFileErrors();
+    } catch (error) {
+      if (process.env.NODE_ENV === 'development') {
+        console.warn('Failed to clear file errors on deselect:', error);
+      }
+    }
+  }, [setSelectedFiles, clearAllFileErrors]);
+
+  const handleCloseSelectedFiles = useCallback(() => {
+    if (selectedFileIds.length === 0) return;
+    void removeFiles(selectedFileIds, false);
+    setSelectedFiles([]);
+  }, [selectedFileIds, removeFiles, setSelectedFiles]);
+
+  useFileEditorRightRailButtons({
+    totalItems,
+    selectedCount,
+    onSelectAll: handleSelectAllFiles,
+    onDeselectAll: handleDeselectAllFiles,
+    onCloseSelected: handleCloseSelectedFiles,
+  });
+
  // Process uploaded files using context
+  // ZIP extraction is now handled automatically in FileContext based on user preferences
  const handleFileUpload = useCallback(async (uploadedFiles: File[]) => {
    _setError(null);

    try {
-      const allExtractedFiles: File[] = [];
-      const errors: string[] = [];
-
-      for (const file of uploadedFiles) {
-        if (file.type === 'application/pdf') {
-          // Handle PDF files normally
-          allExtractedFiles.push(file);
-        } else if (file.type === 'application/zip' || file.type === 'application/x-zip-compressed' || file.name.toLowerCase().endsWith('.zip')) {
-          // Handle ZIP files - only expand if they contain PDFs
-          try {
-            // Validate ZIP file first
-            const validation = await zipFileService.validateZipFile(file);
-
-            if (validation.isValid && validation.containsPDFs) {
-              // ZIP contains PDFs - extract them
-              setZipExtractionProgress({
-                isExtracting: true,
-                currentFile: file.name,
-                progress: 0,
-                extractedCount: 0,
-                totalFiles: validation.fileCount
-              });
-
-              const extractionResult = await zipFileService.extractPdfFiles(file, (progress) => {
-                setZipExtractionProgress({
-                  isExtracting: true,
-                  currentFile: progress.currentFile,
-                  progress: progress.progress,
-                  extractedCount: progress.extractedCount,
-                  totalFiles: progress.totalFiles
-                });
-              });
-
-              // Reset extraction progress
-              setZipExtractionProgress({
-                isExtracting: false,
-                currentFile: '',
-                progress: 0,
-                extractedCount: 0,
-                totalFiles: 0
-              });
-
-              if (extractionResult.success) {
-                allExtractedFiles.push(...extractionResult.extractedFiles);
-
-                if (extractionResult.errors.length > 0) {
-                  errors.push(...extractionResult.errors);
-                }
-              } else {
-                errors.push(`Failed to extract ZIP file "${file.name}": ${extractionResult.errors.join(', ')}`);
-              }
-            } else {
-              // ZIP doesn't contain PDFs or is invalid - treat as regular file
-              allExtractedFiles.push(file);
-            }
-          } catch (zipError) {
-            errors.push(`Failed to process ZIP file "${file.name}": ${zipError instanceof Error ? zipError.message : 'Unknown error'}`);
-            setZipExtractionProgress({
-              isExtracting: false,
-              currentFile: '',
-              progress: 0,
-              extractedCount: 0,
-              totalFiles: 0
-            });
-          }
-        } else {
-          allExtractedFiles.push(file);
-        }
-      }
-
-      // Show any errors
-      if (errors.length > 0) {
-        showError(errors.join('\n'));
-      }
-
-      // Process all extracted files
-      if (allExtractedFiles.length > 0) {
-        // Add files to context and select them automatically
-        await addFiles(allExtractedFiles, { selectFiles: true });
-        showStatus(`Added ${allExtractedFiles.length} files`, 'success');
+      if (uploadedFiles.length > 0) {
+        // FileContext will automatically handle ZIP extraction based on user preferences
+        // - Respects autoUnzip setting
+        // - Respects autoUnzipFileLimit
+        // - HTML ZIPs stay intact
+        // - Non-ZIP files pass through unchanged
+        await addFiles(uploadedFiles, { selectFiles: true });
+        showStatus(`Added ${uploadedFiles.length} file(s)`, 'success');
      }
    } catch (err) {
      const errorMessage = err instanceof Error ? err.message : 'Failed to process files';
      showError(errorMessage);
      console.error('File processing error:', err);
-
-      // Reset extraction progress on error
-      setZipExtractionProgress({
-        isExtracting: false,
-        currentFile: '',
-        progress: 0,
-        extractedCount: 0,
-        totalFiles: 0
-      });
    }
-  }, [addFiles]);
+  }, [addFiles, showStatus, showError]);

  const toggleFile = useCallback((fileId: FileId) => {
    const currentSelectedIds = contextSelectedIdsRef.current;
@@ -320,7 +267,7 @@ const FileEditor = ({

        if (result.success && result.extractedStubs.length > 0) {
          // Add extracted file stubs to FileContext
-          await actions.addStirlingFileStubs(result.extractedStubs);
+          await fileActions.addStirlingFileStubs(result.extractedStubs);

          // Remove the original ZIP file
          removeFiles([fileId], false);
@@ -350,7 +297,7 @@ const FileEditor = ({
        });
      }
    }
-  }, [activeStirlingFileStubs, selectors, actions, removeFiles]);
+  }, [activeStirlingFileStubs, selectors, fileActions, removeFiles]);

  const handleViewFile = useCallback((fileId: FileId) => {
    const record = activeStirlingFileStubs.find(r => r.id === fileId);
@@ -394,7 +341,7 @@ const FileEditor = ({
        <Box p="md">


-        {activeStirlingFileStubs.length === 0 && !zipExtractionProgress.isExtracting ? (
+        {activeStirlingFileStubs.length === 0 ? (
          <Center h="60vh">
            <Stack align="center" gap="md">
              <Text size="lg" c="dimmed">📁</Text>
@@ -402,43 +349,6 @@ const FileEditor = ({
              <Text size="sm" c="dimmed">Upload PDF files, ZIP archives, or load from storage to get started</Text>
            </Stack>
          </Center>
-        ) : activeStirlingFileStubs.length === 0 && zipExtractionProgress.isExtracting ? (
-          <Box>
-            <SkeletonLoader type="controls" />
-
-            {/* ZIP Extraction Progress */}
-            {zipExtractionProgress.isExtracting && (
-              <Box mb="md" p="sm" style={{ backgroundColor: 'var(--mantine-color-orange-0)', borderRadius: 8 }}>
-                <Group justify="space-between" mb="xs">
-                  <Text size="sm" fw={500}>Extracting ZIP archive...</Text>
-                  <Text size="sm" c="dimmed">{Math.round(zipExtractionProgress.progress)}%</Text>
-                </Group>
-                <Text size="xs" c="dimmed" mb="xs">
-                  {zipExtractionProgress.currentFile || 'Processing files...'}
-                </Text>
-                <Text size="xs" c="dimmed" mb="xs">
-                  {zipExtractionProgress.extractedCount} of {zipExtractionProgress.totalFiles} files extracted
-                </Text>
-                <div style={{
-                  width: '100%',
-                  height: '4px',
-                  backgroundColor: 'var(--mantine-color-gray-2)',
-                  borderRadius: '2px',
-                  overflow: 'hidden'
-                }}>
-                  <div style={{
-                    width: `${Math.round(zipExtractionProgress.progress)}%`,
-                    height: '100%',
-                    backgroundColor: 'var(--mantine-color-orange-6)',
-                    transition: 'width 0.3s ease'
-                  }} />
-                </div>
-              </Box>
-            )}
-
-
-            <SkeletonLoader type="fileGrid" count={6} />
-          </Box>
        ) : (
          <div
            style={{
@@ -1,24 +1,26 @@
-import React, { useState, useCallback, useRef, useMemo, useEffect } from 'react';
-import { Text, ActionIcon, CheckboxIndicator, Tooltip } from '@mantine/core';
-import { alert } from '../toast';
+import React, { useState, useCallback, useRef, useMemo } from 'react';
+import { Text, ActionIcon, CheckboxIndicator, Tooltip, Modal, Button, Group, Stack } from '@mantine/core';
+import { useMediaQuery } from '@mantine/hooks';
+import { alert } from '@app/components/toast';
 import { useTranslation } from 'react-i18next';
-import MoreVertIcon from '@mui/icons-material/MoreVert';
 import DownloadOutlinedIcon from '@mui/icons-material/DownloadOutlined';
 import CloseIcon from '@mui/icons-material/Close';
+import VisibilityIcon from '@mui/icons-material/Visibility';
 import UnarchiveIcon from '@mui/icons-material/Unarchive';
 import PushPinIcon from '@mui/icons-material/PushPin';
 import PushPinOutlinedIcon from '@mui/icons-material/PushPinOutlined';
 import DragIndicatorIcon from '@mui/icons-material/DragIndicator';
 import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
-import { StirlingFileStub } from '../../types/fileContext';
-import { zipFileService } from '../../services/zipFileService';
+import { StirlingFileStub } from '@app/types/fileContext';
+import { zipFileService } from '@app/services/zipFileService';

-import styles from './FileEditor.module.css';
-import { useFileContext } from '../../contexts/FileContext';
-import { useFileState } from '../../contexts/file/fileHooks';
-import { FileId } from '../../types/file';
-import { formatFileSize } from '../../utils/fileUtils';
-import ToolChain from '../shared/ToolChain';
+import styles from '@app/components/fileEditor/FileEditor.module.css';
+import { useFileContext } from '@app/contexts/FileContext';
+import { useFileState } from '@app/contexts/file/fileHooks';
+import { FileId } from '@app/types/file';
+import { formatFileSize } from '@app/utils/fileUtils';
+import ToolChain from '@app/components/shared/ToolChain';
+import HoverActionMenu, { HoverAction } from '@app/components/shared/HoverActionMenu';



@@ -60,8 +62,9 @@ const FileEditorThumbnail = ({
  // ---- Drag state ----
  const [isDragging, setIsDragging] = useState(false);
  const dragElementRef = useRef<HTMLDivElement | null>(null);
-  const [actionsWidth, setActionsWidth] = useState<number | undefined>(undefined);
-  const [showActions, setShowActions] = useState(false);
+  const [showHoverMenu, setShowHoverMenu] = useState(false);
+  const isMobile = useMediaQuery('(max-width: 1024px)');
+  const [showCloseModal, setShowCloseModal] = useState(false);

  // Resolve the actual File object for pin/unpin operations
  const actualFile = useMemo(() => {
@@ -155,46 +158,66 @@ const FileEditorThumbnail = ({
    };
  }, [file.id, file.name, selectedFiles, onReorderFiles]);

-  // Update dropdown width on resize
-  useEffect(() => {
-    const update = () => {
-      if (dragElementRef.current) setActionsWidth(dragElementRef.current.offsetWidth);
-    };
-    update();
-    window.addEventListener('resize', update);
-    return () => window.removeEventListener('resize', update);
+  // Handle close with confirmation
+  const handleCloseWithConfirmation = useCallback(() => {
+    setShowCloseModal(true);
  }, []);

-  // Close the actions dropdown when hovering outside this file card (and its dropdown)
-  useEffect(() => {
-    if (!showActions) return;
+  const handleConfirmClose = useCallback(() => {
+    onCloseFile(file.id);
+    alert({ alertType: 'neutral', title: `Closed ${file.name}`, expandable: false, durationMs: 3500 });
+    setShowCloseModal(false);
+  }, [file.id, file.name, onCloseFile]);

-    const isInsideCard = (target: EventTarget | null) => {
-      const container = dragElementRef.current;
-      if (!container) return false;
-      return target instanceof Node && container.contains(target);
-    };
+  const handleCancelClose = useCallback(() => {
+    setShowCloseModal(false);
+  }, []);

-    const handleMouseMove = (e: MouseEvent) => {
-      if (!isInsideCard(e.target)) {
-        setShowActions(false);
-      }
-    };
-
-    const handleTouchStart = (e: TouchEvent) => {
-      // On touch devices, close if the touch target is outside the card
-      if (!isInsideCard(e.target)) {
-        setShowActions(false);
-      }
-    };
-
-    document.addEventListener('mousemove', handleMouseMove);
-    document.addEventListener('touchstart', handleTouchStart, { passive: true });
-    return () => {
-      document.removeEventListener('mousemove', handleMouseMove);
-      document.removeEventListener('touchstart', handleTouchStart);
-    };
-  }, [showActions]);
+  // Build hover menu actions
+  const hoverActions = useMemo<HoverAction[]>(() => [
+    {
+      id: 'view',
+      icon: <VisibilityIcon style={{ fontSize: 20 }} />,
+      label: t('openInViewer', 'Open in Viewer'),
+      onClick: (e) => {
+        e.stopPropagation();
+        onViewFile(file.id);
+      },
+    },
+    {
+      id: 'download',
+      icon: <DownloadOutlinedIcon style={{ fontSize: 20 }} />,
+      label: t('download', 'Download'),
+      onClick: (e) => {
+        e.stopPropagation();
+        onDownloadFile(file.id);
+        alert({ alertType: 'success', title: `Downloading ${file.name}`, expandable: false, durationMs: 2500 });
+      },
+    },
+    {
+      id: 'unzip',
+      icon: <UnarchiveIcon style={{ fontSize: 20 }} />,
+      label: t('fileManager.unzip', 'Unzip'),
+      onClick: (e) => {
+        e.stopPropagation();
+        if (onUnzipFile) {
+          onUnzipFile(file.id);
+          alert({ alertType: 'success', title: `Unzipping ${file.name}`, expandable: false, durationMs: 2500 });
+        }
+      },
+      hidden: !isZipFile || !onUnzipFile,
+    },
+    {
+      id: 'close',
+      icon: <CloseIcon style={{ fontSize: 20 }} />,
+      label: t('close', 'Close'),
+      onClick: (e) => {
+        e.stopPropagation();
+        handleCloseWithConfirmation();
+      },
+      color: 'red',
+    }
+  ], [t, file.id, file.name, isZipFile, onViewFile, onDownloadFile, onUnzipFile, handleCloseWithConfirmation]);

  // ---- Card interactions ----
  const handleCardClick = () => {
@@ -224,6 +247,7 @@ const FileEditorThumbnail = ({
      ref={fileElementRef}
      data-file-id={file.id}
      data-testid="file-thumbnail"
+      data-tour="file-card-checkbox"
      data-selected={isSelected}
      data-supported={isSupported}
      className={`${styles.card} w-[18rem] h-[22rem] select-none flex flex-col shadow-sm transition-all relative`}
@@ -232,6 +256,8 @@ const FileEditorThumbnail = ({
      role="listitem"
      aria-selected={isSelected}
      onClick={handleCardClick}
+      onMouseEnter={() => setShowHoverMenu(true)}
+      onMouseLeave={() => setShowHoverMenu(false)}
      onDoubleClick={handleCardDoubleClick}
    >
      {/* Header bar */}
@@ -268,11 +294,12 @@ const FileEditorThumbnail = ({
        {/* Action buttons group */}
        <div className={styles.headerActions}>
          {/* Pin/Unpin icon */}
-          <Tooltip label={isPinned ? t('unpin', 'Unpin') : t('pin', 'Pin')}>
+          <Tooltip label={isPinned ? t('unpin', 'Unpin File (replace after tool run)') : t('pin', 'Pin File (keep active after tool run)')}>
            <ActionIcon
-              aria-label={isPinned ? t('unpin', 'Unpin') : t('pin', 'Pin')}
+              aria-label={isPinned ? t('unpin', 'Unpin File (replace after tool run)') : t('pin', 'Pin File (keep active after tool run)')}
              variant="subtle"
              className={isPinned ? styles.pinned : styles.headerIconButton}
+              data-tour="file-card-pin"
              onClick={(e) => {
                e.stopPropagation();
                if (actualFile) {
@@ -289,98 +316,9 @@ const FileEditorThumbnail = ({
              {isPinned ? <PushPinIcon fontSize="small" /> : <PushPinOutlinedIcon fontSize="small" />}
            </ActionIcon>
          </Tooltip>
-
-          {/* Download icon */}
-          <Tooltip label={t('download', 'Download')}>
-            <ActionIcon
-              aria-label={t('download', 'Download')}
-              variant="subtle"
-              className={styles.headerIconButton}
-              onClick={(e) => {
-                e.stopPropagation();
-                onDownloadFile(file.id);
-                alert({ alertType: 'success', title: `Downloading ${file.name}`, expandable: false, durationMs: 2500 });
-              }}
-            >
-              <DownloadOutlinedIcon fontSize="small" />
-            </ActionIcon>
-          </Tooltip>
-
-          {/* Kebab menu */}
-          <ActionIcon
-            aria-label={t('moreOptions', 'More options')}
-            variant="subtle"
-            className={styles.headerIconButton}
-            onClick={(e) => {
-              e.stopPropagation();
-              setShowActions((v) => !v);
-            }}
-          >
-            <MoreVertIcon fontSize="small" />
-          </ActionIcon>
        </div>
      </div>

-      {/* Actions overlay */}
-      {showActions && (
-        <div
-          className={styles.actionsOverlay}
-          style={{ width: actionsWidth }}
-          onClick={(e) => e.stopPropagation()}
-        >
-          <button
-            className={styles.actionRow}
-            onClick={() => {
-              if (actualFile) {
-                if (isPinned) {
-                  unpinFile(actualFile);
-                  alert({ alertType: 'neutral', title: `Unpinned ${file.name}`, expandable: false, durationMs: 3000 });
-                } else {
-                  pinFile(actualFile);
-                  alert({ alertType: 'success', title: `Pinned ${file.name}`, expandable: false, durationMs: 3000 });
-                }
-              }
-              setShowActions(false);
-            }}
-          >
-            {isPinned ? <PushPinIcon className={styles.pinned} fontSize="small" /> : <PushPinOutlinedIcon fontSize="small" />}
-            <span>{isPinned ? t('unpin', 'Unpin') : t('pin', 'Pin')}</span>
-          </button>
-
-          <button
-            className={styles.actionRow}
-            onClick={() => { onDownloadFile(file.id); alert({ alertType: 'success', title: `Downloading ${file.name}`, expandable: false, durationMs: 2500 }); setShowActions(false); }}
-          >
-            <DownloadOutlinedIcon fontSize="small" />
-            <span>{t('download', 'Download')}</span>
-          </button>
-
-          {isZipFile && onUnzipFile && (
-            <button
-              className={styles.actionRow}
-              onClick={() => { onUnzipFile(file.id); alert({ alertType: 'success', title: `Unzipping ${file.name}`, expandable: false, durationMs: 2500 }); setShowActions(false); }}
-            >
-              <UnarchiveIcon fontSize="small" />
-              <span>{t('fileManager.unzip', 'Unzip')}</span>
-            </button>
-          )}
-
-          <div className={styles.actionsDivider} />
-
-          <button
-            className={`${styles.actionRow} ${styles.actionDanger}`}
-            onClick={() => {
-              onCloseFile(file.id);
-              alert({ alertType: 'neutral', title: `Closed ${file.name}`, expandable: false, durationMs: 3500 });
-              setShowActions(false);
-            }}
-          >
-            <CloseIcon fontSize="small" />
-            <span>{t('close', 'Close')}</span>
-          </button>
-        </div>
-      )}
-
      {/* Title + meta line */}
      <div
      style={{
@@ -471,6 +409,37 @@ const FileEditorThumbnail = ({
          </div>
        )}
      </div>
+
+      {/* Hover Menu */}
+      <HoverActionMenu
+        show={showHoverMenu || isMobile}
+        actions={hoverActions}
+        position="outside"
+      />
+
+      {/* Close Confirmation Modal */}
+      <Modal
+        opened={showCloseModal}
+        onClose={handleCancelClose}
+        title={t('confirmClose', 'Confirm Close')}
+        centered
+        size="auto"
+      >
+        <Stack gap="md">
+          <Text size="md">{t('confirmCloseMessage', 'Are you sure you want to close this file?')}</Text>
+          <Text size="sm" c="dimmed" fw={500}>
+            {file.name}
+          </Text>
+          <Group justify="flex-end" gap="sm">
+            <Button variant="light" onClick={handleCancelClose}>
+              {t('confirmCloseCancel', 'Cancel')}
+            </Button>
+            <Button variant="filled" color="red" onClick={handleConfirmClose}>
+              {t('confirmCloseConfirm', 'Close File')}
+            </Button>
+          </Group>
+        </Stack>
+      </Modal>
    </div>
  );
 };
@@ -0,0 +1,60 @@
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useRightRailButtons, RightRailButtonWithAction } from '@app/hooks/useRightRailButtons';
+import LocalIcon from '@app/components/shared/LocalIcon';
+
+interface FileEditorRightRailButtonsParams {
+  totalItems: number;
+  selectedCount: number;
+  onSelectAll: () => void;
+  onDeselectAll: () => void;
+  onCloseSelected: () => void;
+}
+
+export function useFileEditorRightRailButtons({
+  totalItems,
+  selectedCount,
+  onSelectAll,
+  onDeselectAll,
+  onCloseSelected,
+}: FileEditorRightRailButtonsParams) {
+  const { t } = useTranslation();
+
+  const buttons = useMemo<RightRailButtonWithAction[]>(() => [
+    {
+      id: 'file-select-all',
+      icon: <LocalIcon icon="select-all" width="1.5rem" height="1.5rem" />,
+      tooltip: t('rightRail.selectAll', 'Select All'),
+      ariaLabel: typeof t === 'function' ? t('rightRail.selectAll', 'Select All') : 'Select All',
+      section: 'top' as const,
+      order: 10,
+      disabled: totalItems === 0 || selectedCount === totalItems,
+      visible: totalItems > 0,
+      onClick: onSelectAll,
+    },
+    {
+      id: 'file-deselect-all',
+      icon: <LocalIcon icon="crop-square-outline" width="1.5rem" height="1.5rem" />,
+      tooltip: t('rightRail.deselectAll', 'Deselect All'),
+      ariaLabel: typeof t === 'function' ? t('rightRail.deselectAll', 'Deselect All') : 'Deselect All',
+      section: 'top' as const,
+      order: 20,
+      disabled: selectedCount === 0,
+      visible: totalItems > 0,
+      onClick: onDeselectAll,
+    },
+    {
+      id: 'file-close-selected',
+      icon: <LocalIcon icon="close-rounded" width="1.5rem" height="1.5rem" />,
+      tooltip: t('rightRail.closeSelected', 'Close Selected Files'),
+      ariaLabel: typeof t === 'function' ? t('rightRail.closeSelected', 'Close Selected Files') : 'Close Selected Files',
+      section: 'top' as const,
+      order: 30,
+      disabled: selectedCount === 0,
+      visible: totalItems > 0,
+      onClick: onCloseSelected,
+    },
+  ], [t, totalItems, selectedCount, onSelectAll, onDeselectAll, onCloseSelected]);
+
+  useRightRailButtons(buttons);
+}
--- a/Show More
+++ b/Show More