Merge branch 'V2' into booklet

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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