# stirling-tools/stirling-pdf architecture

> Architecture diagram of the GitHub repository stirling-tools/stirling-pdf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stirling-tools/stirling-pdf
- Repository: https://github.com/stirling-tools/stirling-pdf

## Overview

Stirling PDF is an open-source PDF editing platform for browser, desktop, and self-hosted use. Its principal workflow is submitting documents to a PDF tool or pipeline and receiving processed files; the sampled pipeline controller shows input preparation, pipeline execution, and single-file or ZIP responses. The README also documents editing, signing, redaction, conversion, OCR, REST APIs, and no-code workflows. Several of those capabilities are represented at directory level because their implementation was not sampled; those relationships are documented rather than inferred from imports.

Main entry points: [`app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java`](https://github.com/stirling-tools/stirling-pdf/blob/main/app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java) (Pipeline API), [`app/core/src/main/java/stirling/software/SPDF/controller/api`](https://github.com/stirling-tools/stirling-pdf/tree/main/app/core/src/main/java/stirling/software/SPDF/controller/api) (PDF tools), [`app/proprietary/src/main/java/stirling/software/proprietary/storage/service/StorageEncryptionMigrationService.java`](https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/storage/service/StorageEncryptionMigrationService.java) (Storage encryption), [`app/common/src/main/java/stirling/software/common/service`](https://github.com/stirling-tools/stirling-pdf/tree/main/app/common/src/main/java/stirling/software/common/service) (PDF services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pdf["PDF processing"]
  node_pipeline_api["Pipeline API"]
  node_pipeline_processor["Pipeline processor"]
  node_pdf_tools["PDF tools"]
  node_pdf_json["PDF JSON conversion"]
  node_pdf_services["PDF services"]
end

subgraph group_workflow["Automation"]
  node_automation_ui["Workflow UI"]
  node_workflow_sessions["Workflow sessions"]
end

subgraph group_enterprise["Enterprise services"]
  node_accounts[("Accounts and teams<br/>[User.java]")]
  node_file_storage["File storage"]
  node_storage_backend["Storage backend"]
  node_encryption_migration["Storage encryption"]
  node_audit["Audit service<br/>[AuditService.java]"]
  node_saas_billing["Usage billing"]
end

subgraph group_platform["Platform services"]
  node_temp_files["Temporary files"]
  node_api["REST API"]
  node_app_config["Application configuration"]
  node_process_executor["Process execution"]
end

node_user(("PDF user"))

node_user -->|"submits documents"| node_pipeline_api
node_pipeline_api -->|"runs pipeline"| node_pipeline_processor
node_pipeline_api -->|"returns files"| node_user
node_user -->|"uses PDF tools"| node_pdf_tools
node_user -->|"integrates by API"| node_api
node_user -->|"configures workflows"| node_automation_ui
node_user -->|"signs documents"| node_workflow_sessions
node_user -.->|"manages files"| node_file_storage
node_file_storage -->|"stores objects"| node_storage_backend
node_encryption_migration -->|"migrates blobs"| node_storage_backend
node_encryption_migration -->|"records events"| node_audit
node_pipeline_api -->|"creates temp files"| node_temp_files
node_pdf_tools -.->|"uses PDF services"| node_pdf_services
node_pdf_tools -.->|"converts PDF data"| node_pdf_json
node_pdf_services -.->|"runs external tools"| node_process_executor
node_user -->|"incurs usage charges"| node_saas_billing

click node_pipeline_api "https://github.com/stirling-tools/stirling-pdf/blob/main/app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java"
click node_pipeline_processor "https://github.com/stirling-tools/stirling-pdf/tree/main/app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline"
click node_pdf_tools "https://github.com/stirling-tools/stirling-pdf/tree/main/app/core/src/main/java/stirling/software/SPDF/controller/api"
click node_pdf_json "https://github.com/stirling-tools/stirling-pdf/blob/main/app/core/src/main/java/stirling/software/SPDF/service/PdfJsonConversionService.java"
click node_pdf_services "https://github.com/stirling-tools/stirling-pdf/tree/main/app/common/src/main/java/stirling/software/common/service"
click node_temp_files "https://github.com/stirling-tools/stirling-pdf/blob/main/app/common/src/main/java/stirling/software/common/util/TempFileManager.java"
click node_automation_ui "https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/proprietary/components/policies/useEditorPipelines.ts"
click node_workflow_sessions "https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/WorkflowSessionService.java"
click node_accounts "https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/security/model/User.java"
click node_file_storage "https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/storage/service/FileStorageService.java"
click node_storage_backend "https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/storage/provider/StorageProvider.java"
click node_encryption_migration "https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/storage/service/StorageEncryptionMigrationService.java"
click node_audit "https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/service/AuditService.java"
click node_api "https://github.com/stirling-tools/stirling-pdf/tree/main/app/core/src/main/java/stirling/software/SPDF/controller/api"
click node_app_config "https://github.com/stirling-tools/stirling-pdf/blob/main/app/common/src/main/java/stirling/software/common/model/ApplicationProperties.java"
click node_process_executor "https://github.com/stirling-tools/stirling-pdf/blob/main/app/common/src/main/java/stirling/software/common/util/ProcessExecutor.java"
click node_saas_billing "https://github.com/stirling-tools/stirling-pdf/blob/main/app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pipeline_api,node_pipeline_processor,node_pdf_tools,node_pdf_json,node_pdf_services,node_user toneBlue
class node_automation_ui,node_workflow_sessions toneAmber
class node_accounts,node_file_storage,node_storage_backend,node_encryption_migration,node_audit,node_saas_billing toneMint
class node_temp_files,node_api,node_app_config,node_process_executor toneRose
```

## Components

### PDF processing

- [Pipeline API](https://github.com/stirling-tools/stirling-pdf/blob/main/app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java): `app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java`
- [Pipeline processor](https://github.com/stirling-tools/stirling-pdf/tree/main/app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline): `app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline`
- [PDF tools](https://github.com/stirling-tools/stirling-pdf/tree/main/app/core/src/main/java/stirling/software/SPDF/controller/api): `app/core/src/main/java/stirling/software/SPDF/controller/api`
- [PDF JSON conversion](https://github.com/stirling-tools/stirling-pdf/blob/main/app/core/src/main/java/stirling/software/SPDF/service/PdfJsonConversionService.java): `app/core/src/main/java/stirling/software/SPDF/service/PdfJsonConversionService.java`
- [PDF services](https://github.com/stirling-tools/stirling-pdf/tree/main/app/common/src/main/java/stirling/software/common/service): `app/common/src/main/java/stirling/software/common/service`

### Automation

- [Workflow UI](https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/proprietary/components/policies/useEditorPipelines.ts): `frontend/editor/src/proprietary/components/policies/useEditorPipelines.ts`
- [Workflow sessions](https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/WorkflowSessionService.java): `app/proprietary/src/main/java/stirling/software/proprietary/workflow/service/WorkflowSessionService.java`

### Enterprise services

- [Accounts and teams](https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/security/model/User.java): `app/proprietary/src/main/java/stirling/software/proprietary/security/model/User.java`
- [File storage](https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/storage/service/FileStorageService.java): `app/proprietary/src/main/java/stirling/software/proprietary/storage/service/FileStorageService.java`
- [Storage backend](https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/storage/provider/StorageProvider.java): `app/proprietary/src/main/java/stirling/software/proprietary/storage/provider/StorageProvider.java`
- [Storage encryption](https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/storage/service/StorageEncryptionMigrationService.java): `app/proprietary/src/main/java/stirling/software/proprietary/storage/service/StorageEncryptionMigrationService.java`
- [Audit service](https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/java/stirling/software/proprietary/service/AuditService.java): `app/proprietary/src/main/java/stirling/software/proprietary/service/AuditService.java`
- [Usage billing](https://github.com/stirling-tools/stirling-pdf/blob/main/app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java): `app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java`

### Platform services

- [Temporary files](https://github.com/stirling-tools/stirling-pdf/blob/main/app/common/src/main/java/stirling/software/common/util/TempFileManager.java): `app/common/src/main/java/stirling/software/common/util/TempFileManager.java`
- [REST API](https://github.com/stirling-tools/stirling-pdf/tree/main/app/core/src/main/java/stirling/software/SPDF/controller/api): `app/core/src/main/java/stirling/software/SPDF/controller/api`
- [Application configuration](https://github.com/stirling-tools/stirling-pdf/blob/main/app/common/src/main/java/stirling/software/common/model/ApplicationProperties.java): `app/common/src/main/java/stirling/software/common/model/ApplicationProperties.java`
- [Process execution](https://github.com/stirling-tools/stirling-pdf/blob/main/app/common/src/main/java/stirling/software/common/util/ProcessExecutor.java): `app/common/src/main/java/stirling/software/common/util/ProcessExecutor.java`

### Other components

- **PDF user**

## Connections

- PDF user → Pipeline API: submits documents (evidence: `README.md`)
- Pipeline API → Pipeline processor: runs pipeline (evidence: `app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java`)
- Pipeline API → PDF user: returns files (evidence: `app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java`)
- PDF user → PDF tools: uses PDF tools (evidence: `README.md`)
- PDF user → REST API: integrates by API (evidence: `README.md`)
- PDF user → Workflow UI: configures workflows (evidence: `README.md`)
- PDF user → Workflow sessions: signs documents (evidence: `README.md`)
- PDF user → File storage: manages files
- File storage → Storage backend: stores objects (evidence: `app/proprietary/src/main/java/stirling/software/proprietary/storage/service/FileStorageService.java`)
- Storage encryption → Storage backend: migrates blobs (evidence: `app/proprietary/src/main/java/stirling/software/proprietary/storage/service/StorageEncryptionMigrationService.java`)
- Storage encryption → Audit service: records events (evidence: `app/proprietary/src/main/java/stirling/software/proprietary/storage/service/StorageEncryptionMigrationService.java`)
- Pipeline API → Temporary files: creates temp files (evidence: `app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java`)
- PDF tools → PDF services: uses PDF services (evidence: `app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineController.java`)
- PDF tools → PDF JSON conversion: converts PDF data
- PDF services → Process execution: runs external tools
- PDF user → Usage billing: incurs usage charges (evidence: `app/saas/src/main/java/stirling/software/saas/payg/instance/InstanceUsageIngestService.java`)
