diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b9093b6..9567aee 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,8 +2,22 @@ name: CI
on:
push:
branches: [develop]
+ paths-ignore:
+ - '**.md'
+ - 'docs/**'
+ - 'tutorials/**'
+ - 'examples/**/README.md'
+ - 'LICENSE'
+ - '.gitignore'
pull_request:
branches: [develop, main]
+ paths-ignore:
+ - '**.md'
+ - 'docs/**'
+ - 'tutorials/**'
+ - 'examples/**/README.md'
+ - 'LICENSE'
+ - '.gitignore'
workflow_dispatch:
inputs:
triggered-by:
@@ -13,10 +27,5 @@ on:
jobs:
build:
uses: fireflyframework/.github/.github/workflows/java-ci.yml@main
- permissions:
- packages: read
- contents: read
- actions: write
with:
java-version: '25'
- secrets: inherit
diff --git a/README.md b/README.md
index 374fdb3..99121e6 100644
--- a/README.md
+++ b/README.md
@@ -1,393 +1,110 @@
-# Firefly ECM Library
+# Firefly Framework - Enterprise Content Management (ECM)
[](https://github.com/fireflyframework/fireflyframework-ecm/actions/workflows/ci.yml)
+[](LICENSE)
+[](https://openjdk.org)
+[](https://spring.io/projects/spring-boot)
-> **Enterprise Content Management Port Interfaces for the Modern Era**
+> ECM core library providing document management, e-signature, intelligent document processing, and folder security through a port/adapter architecture.
-A comprehensive, production-ready Enterprise Content Management (ECM) **port interface library** built on hexagonal architecture principles. This library provides the **core port interfaces** (business contracts) for document management, digital signatures, and intelligent document processing. Adapter implementations are provided in separate libraries, allowing you to choose and integrate only the providers you need.
-
-[](https://opensource.org/licenses/Apache-2.0)
-[](https://openjdk.java.net/)
-[](https://spring.io/projects/spring-boot)
-
-## ๐ฏ Purpose & Vision
-
-The Firefly ECM Library solves the challenge of **vendor lock-in** and **integration complexity** in enterprise content management by providing a **stable, vendor-agnostic interface layer**. This library contains:
-
-- **Port Interfaces**: Business contracts defining ECM operations (document management, eSignatures, IDP)
-- **Domain Models**: Core entities and value objects for ECM operations
-- **Adapter Infrastructure**: Framework for registering and selecting adapter implementations
-- **Auto-Configuration**: Spring Boot auto-configuration for seamless integration
-
-Organizations can:
-
-- **Switch between storage providers** without changing business logic
-- **Integrate multiple eSignature providers** through a unified API
-- **Process documents intelligently** with various IDP providers
-- **Scale horizontally** with cloud-native, reactive architecture
-- **Maintain compliance** with built-in audit trails and security features
-- **Future-proof applications** with a stable, vendor-agnostic interface
-
-**Adapter implementations** are provided in separate libraries (see [Available Adapters](#-available-adapters) below).
-
-## ๐๏ธ Architecture Overview
-
-This library implements **Hexagonal Architecture** (Ports and Adapters pattern), providing clean separation between business logic and external systems.
-
-**Key Benefits**: Pluggable adapters, testable design, scalable architecture, reactive programming, vendor independence
-
-### Library Structure
-
-This is a **single-module library** containing:
-
-```
-fireflyframework-ecm/ # Port Interfaces Library
-โโโ src/main/java/
-โ โโโ org.fireflyframework.ecm/
-โ โโโ port/ # Port Interfaces (business contracts)
-โ โ โโโ document/ # Document management ports
-โ โ โโโ folder/ # Folder management ports
-โ โ โโโ security/ # Security and permissions ports
-โ โ โโโ audit/ # Audit and compliance ports
-โ โ โโโ esignature/ # Digital signature ports
-โ โ โโโ idp/ # Intelligent Document Processing ports
-โ โโโ domain/ # Domain Models and DTOs
-โ โโโ adapter/ # Adapter infrastructure (registry, selector)
-โ โโโ config/ # Spring Boot auto-configuration
-โ โโโ service/ # Core services (EcmPortProvider)
-โโโ pom.xml
-```
-
-### Adapter Libraries (Separate Repositories)
-
-Adapter implementations are provided in separate libraries that you add as dependencies:
-
-```
-Document Storage Adapters:
-โโโ fireflyframework-ecm-adapter-s3 # Amazon S3 adapter
-โโโ fireflyframework-ecm-adapter-azure-blob # Azure Blob Storage adapter
-โโโ fireflyframework-ecm-adapter-minio # MinIO adapter
-โโโ fireflyframework-ecm-adapter-alfresco # Alfresco Content Services adapter
-
-eSignature Adapters:
-โโโ fireflyframework-ecm-adapter-docusign # DocuSign adapter
-โโโ fireflyframework-ecm-adapter-adobe-sign # Adobe Sign adapter
-โโโ fireflyframework-ecm-adapter-logalty # Logalty adapter (eIDAS-compliant)
-
-IDP Adapters:
-โโโ fireflyframework-ecm-adapter-aws-textract # AWS Textract adapter
-โโโ fireflyframework-ecm-adapter-azure-form-recognizer # Azure Form Recognizer adapter
-โโโ fireflyframework-ecm-adapter-google-document-ai # Google Document AI adapter
-```
-
-## ๐ What's Included in This Library
-
-### โ
Port Interfaces (Business Contracts)
-
-This library provides **complete port interface definitions** for:
-
-#### **Document Management Ports**
-- โ
**DocumentPort**: Document CRUD operations (create, read, update, delete)
-- โ
**DocumentContentPort**: Binary content storage and streaming
-- โ
**DocumentVersionPort**: Version management and history
-- โ
**DocumentSearchPort**: Search and query capabilities
-
-#### **Folder Management Ports**
-- โ
**FolderPort**: Folder CRUD and organization
-- โ
**FolderHierarchyPort**: Hierarchical folder operations
-
-#### **Security & Permissions Ports**
-- โ
**PermissionPort**: Access control and permissions
-- โ
**DocumentSecurityPort**: Document-level security operations
-
-#### **Audit & Compliance Ports**
-- โ
**AuditPort**: Audit logging and compliance tracking
-
-#### **eSignature Ports**
-- โ
**SignatureEnvelopePort**: Envelope lifecycle management
-- โ
**SignatureRequestPort**: Signature request operations
-- โ
**SignatureValidationPort**: Signature verification
-- โ
**SignatureProofPort**: Signature proof and evidence
-
-#### **Intelligent Document Processing (IDP) Ports**
-- โ
**DocumentExtractionPort**: OCR and text extraction
-- โ
**DocumentClassificationPort**: Document type classification
-- โ
**DataExtractionPort**: Structured data extraction
-- โ
**DocumentValidationPort**: Document validation and quality checks
-
-### โ
Core Infrastructure
-
-- โ
**Domain Models**: Complete entity definitions with validation
-- โ
**Adapter Infrastructure**: Registry, selector, and validation framework
-- โ
**Auto-Configuration**: Spring Boot auto-configuration
-- โ
**Reactive Support**: Full Project Reactor integration
-- โ
**Graceful Degradation**: No-op adapters for missing implementations
-- โ
**Comprehensive Javadoc**: Fully documented APIs
-
-### ๐งช Test Coverage
-
-| **Component** | **Tests** | **Success Rate** | **Status** |
-|---------------|-----------|------------------|------------|
-| **Core Library** | 11 | โ
**100%** | Production Ready |
-| **Port Interfaces** | - | โ
**Complete** | All defined |
-| **Domain Models** | - | โ
**Complete** | Fully validated |
-
-## ๐ฆ Available Adapters
+---
-Adapter implementations are provided in **separate libraries**. Add the adapters you need as Maven dependencies:
+## Table of Contents
-### Document Storage Adapters
+- [Overview](#overview)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
-| Adapter | Artifact ID | Status | Repository |
-|---------|-------------|--------|------------|
-| **Amazon S3** | `fireflyframework-ecm-adapter-s3` | โ
Available | [firefly-oss/fireflyframework-ecm-adapter-s3](https://github.org/fireflyframework-oss/fireflyframework-ecm-adapter-s3) |
-| **Azure Blob** | `fireflyframework-ecm-adapter-azure-blob` | โ
Available | [firefly-oss/fireflyframework-ecm-adapter-azure-blob](https://github.org/fireflyframework-oss/fireflyframework-ecm-adapter-azure-blob) |
-| **MinIO** | `fireflyframework-ecm-adapter-minio` | ๐ Planned | - |
-| **Alfresco** | `fireflyframework-ecm-adapter-alfresco` | ๐ Planned | - |
+## Overview
-### eSignature Adapters
+Firefly Framework ECM provides Enterprise Content Management capabilities through a hexagonal (port/adapter) architecture. It defines ports for document management, e-signature workflows, intelligent document processing (IDP), folder management, audit trails, and document security, which are implemented by provider-specific adapter modules.
-| Adapter | Artifact ID | Status | Repository |
-|---------|-------------|--------|------------|
-| **DocuSign** | `fireflyframework-ecm-adapter-docusign` | โ
Available | [firefly-oss/fireflyframework-ecm-adapter-docusign](https://github.org/fireflyframework-oss/fireflyframework-ecm-adapter-docusign) |
-| **Adobe Sign** | `fireflyframework-ecm-adapter-adobe-sign` | โ
Available | [firefly-oss/fireflyframework-ecm-adapter-adobe-sign](https://github.org/fireflyframework-oss/fireflyframework-ecm-adapter-adobe-sign) |
-| **Logalty** | `fireflyframework-ecm-adapter-logalty` | ๐ Planned | - |
+The core module includes the adapter registry and selection mechanism, enabling runtime adapter discovery and multi-provider support. It provides domain models for documents, signature envelopes, folders, permissions, and audit events, along with comprehensive enumerations for document statuses, signature states, and processing workflows.
-### IDP Adapters
+Storage adapters (AWS S3, Azure Blob) and e-signature adapters (Adobe Sign, DocuSign, Logalty) are published as separate standalone modules that plug into the ECM core.
-| Adapter | Artifact ID | Status | Repository |
-|---------|-------------|--------|------------|
-| **AWS Textract** | `fireflyframework-ecm-adapter-aws-textract` | ๐ Planned | - |
-| **Azure Form Recognizer** | `fireflyframework-ecm-adapter-azure-form-recognizer` | ๐ Planned | - |
-| **Google Document AI** | `fireflyframework-ecm-adapter-google-document-ai` | ๐ Planned | - |
+## Features
-> **Legend:** โ
= Available | ๐ = Planned
+- Hexagonal architecture with port/adapter pattern
+- Document management ports: content, metadata, versioning, search
+- E-signature ports: envelope management, signature requests, validation, proof
+- Intelligent document processing ports: classification, extraction, validation
+- Folder management with hierarchical structure and permissions
+- Audit trail with event type and severity tracking
+- Adapter registry with profile-based selection
+- NoOp adapters for testing and development
+- Local document search and permission adapters
+- Resilience configuration for adapter operations
+- Auto-configuration via `EcmAutoConfiguration`
+- Configurable via `EcmProperties`
-## ๐ Quick Start
+## Requirements
-### 1. Add Dependencies
+- Java 21+
+- Spring Boot 3.x
+- Maven 3.9+
-Add the **core library** (port interfaces) and your chosen **adapter libraries** to your Spring Boot project:
+## Installation
```xml
-
org.fireflyframework
fireflyframework-ecm
- 1.0.0-SNAPSHOT
-
-
-
-
-
-
- org.fireflyframework
- fireflyframework-ecm-adapter-s3
- 1.0.0-SNAPSHOT
-
-
-
-
- org.fireflyframework
- fireflyframework-ecm-adapter-docusign
- 1.0.0-SNAPSHOT
-
-
-
-
- org.fireflyframework
- fireflyframework-ecm-adapter-azure-blob
- 1.0.0-SNAPSHOT
+ 26.01.01
```
-### 2. Configure Your Adapters
-
-Configure the adapters you've added via `application.yml`:
-
-#### Example: S3 + DocuSign Configuration
-
-```yaml
-firefly:
- ecm:
- # Select document storage adapter
- adapter-type: s3
-
- # Select eSignature provider
- esignature:
- provider: docusign
-
-# S3 adapter configuration
-firefly:
- ecm:
- adapter:
- s3:
- bucket-name: ${S3_BUCKET_NAME}
- region: ${AWS_REGION}
- access-key: ${AWS_ACCESS_KEY_ID}
- secret-key: ${AWS_SECRET_ACCESS_KEY}
-
-# DocuSign adapter configuration
-firefly:
- ecm:
- adapter:
- docusign:
- integration-key: ${DOCUSIGN_INTEGRATION_KEY}
- user-id: ${DOCUSIGN_USER_ID}
- account-id: ${DOCUSIGN_ACCOUNT_ID}
- private-key: ${DOCUSIGN_PRIVATE_KEY}
-```
-
-### 3. Use Port Interfaces in Your Application
-
-Inject and use the port interfaces - the framework automatically provides the configured adapter implementation:
+## Quick Start
```java
+import org.fireflyframework.ecm.port.document.DocumentContentPort;
+import org.fireflyframework.ecm.port.esignature.SignatureEnvelopePort;
+
@Service
-@RequiredArgsConstructor
public class DocumentService {
- private final EcmPortProvider portProvider;
-
- public Mono uploadDocument(String name, byte[] content) {
- // Get the configured DocumentPort implementation
- DocumentPort documentPort = portProvider.getDocumentPort()
- .orElseThrow(() -> new IllegalStateException("No document adapter configured"));
+ private final DocumentContentPort documentPort;
+ private final SignatureEnvelopePort signaturePort;
- Document document = Document.builder()
- .name(name)
- .mimeType("application/pdf")
- .size((long) content.length)
- .build();
-
- return documentPort.createDocument(document, content);
- }
-
- public Mono sendForSignature(UUID documentId, List signers) {
- // Get the configured SignatureEnvelopePort implementation
- SignatureEnvelopePort signaturePort = portProvider.getSignatureEnvelopePort()
- .orElseThrow(() -> new IllegalStateException("No eSignature adapter configured"));
-
- // Create and send envelope
- SignatureEnvelope envelope = SignatureEnvelope.builder()
- .documentId(documentId)
- .signers(signers)
- .build();
-
- return signaturePort.createEnvelope(envelope)
- .flatMap(signaturePort::sendEnvelope);
+ public Mono uploadAndSign(byte[] content, SignatureRequest sigRequest) {
+ return documentPort.store(content)
+ .flatMap(doc -> signaturePort.createEnvelope(doc, sigRequest));
}
}
```
-## ๐ Port Interface Capabilities
-
-This library defines port interfaces for the following ECM capabilities. Actual functionality depends on the adapter implementations you choose:
+## Configuration
-### Document Management Ports
-- **DocumentPort**: Create, read, update, delete documents
-- **DocumentContentPort**: Binary content storage with streaming support
-- **DocumentVersionPort**: Complete document version history
-- **DocumentSearchPort**: Full-text and metadata search capabilities
-
-### Folder Management Ports
-- **FolderPort**: Folder CRUD operations
-- **FolderHierarchyPort**: Nested folder organization and path management
-
-### Security & Permissions Ports
-- **PermissionPort**: Fine-grained access control (read, write, delete, share)
-- **DocumentSecurityPort**: Document encryption and security operations
-
-### Digital Signature Ports
-- **SignatureEnvelopePort**: Envelope lifecycle management
-- **SignatureRequestPort**: Signature request operations
-- **SignatureValidationPort**: Signature verification and validation
-- **SignatureProofPort**: Signature proof and audit trails
-
-### Intelligent Document Processing (IDP) Ports
-- **DocumentExtractionPort**: OCR and text extraction
-- **DocumentClassificationPort**: Automatic document type detection
-- **DataExtractionPort**: Forms, tables, key-value pairs extraction
-- **DocumentValidationPort**: Business rules and quality checks
-
-### Audit & Compliance Ports
-- **AuditPort**: Complete audit trail for all operations
-- **Compliance tracking**: Regulatory compliance and reporting
-
-> **Note**: Port interfaces define the contracts. Actual features depend on the adapter implementations you add to your project.
-
-## ๐ง Adapter Integration Guides
-
-Detailed guides for integrating adapter libraries are available in the [docs/guides](docs/guides) directory:
-
-**Document Storage Adapters:**
-- **[Amazon S3 Integration](docs/guides/s3-integration.md)** - How to add and configure the S3 adapter
-- **[Azure Blob Storage](docs/guides/azure-integration.md)** - How to add and configure the Azure Blob adapter
-- **[MinIO Integration](docs/guides/minio-integration.md)** - How to add and configure the MinIO adapter (planned)
-- **[Alfresco Integration](docs/guides/alfresco-integration.md)** - How to add and configure the Alfresco adapter (planned)
-
-**eSignature Adapters:**
-- **[DocuSign Integration](docs/guides/docusign-integration.md)** - How to add and configure the DocuSign adapter
-
-**IDP Adapters (Planned):**
-- **[AWS Textract Integration](docs/idp/aws-textract-integration.md)** - AWS Textract adapter integration
-- **[Azure Form Recognizer Integration](docs/idp/azure-form-recognizer-integration.md)** - Azure Form Recognizer adapter integration
-- **[Google Document AI Integration](docs/idp/google-document-ai-integration.md)** - Google Document AI adapter integration
-
-## ๐ Documentation
-
-### Core Library Documentation
-- **[Architecture Guide](docs/architecture.md)** - Hexagonal architecture and design principles
-- **[Configuration Reference](docs/configuration.md)** - Configuration options and properties
-- **[API Reference](docs/api/)** - Port interface documentation
-
-### Adapter Integration Guides
-- **[S3 Adapter Guide](docs/guides/s3-integration.md)** - Amazon S3 adapter integration
-- **[Azure Blob Adapter Guide](docs/guides/azure-integration.md)** - Azure Blob Storage adapter integration
-- **[DocuSign Adapter Guide](docs/guides/docusign-integration.md)** - DocuSign adapter integration
-- **[Alfresco Adapter Guide](docs/guides/alfresco-integration.md)** - Alfresco adapter integration (planned)
-- **[MinIO Adapter Guide](docs/guides/minio-integration.md)** - MinIO adapter integration (planned)
-
-### IDP Adapter Guides
-- **[IDP Overview](docs/idp/)** - Intelligent Document Processing overview
-- **[AWS Textract](docs/idp/aws-textract-integration.md)** - AWS Textract adapter (planned)
-- **[Azure Form Recognizer](docs/idp/azure-form-recognizer-integration.md)** - Azure Form Recognizer adapter (planned)
-- **[Google Document AI](docs/idp/google-document-ai-integration.md)** - Google Document AI adapter (planned)
+```yaml
+firefly:
+ ecm:
+ storage:
+ provider: aws-s3 # aws-s3, azure-blob
+ esignature:
+ provider: docusign # adobe-sign, docusign, logalty
+```
-### Development
-- **[Examples](docs/examples/)** - Working code examples
-- **[Testing Guide](docs/testing.md)** - Testing strategies and examples
+## Documentation
-## ๐ค Contributing
+Additional documentation is available in the [docs/](docs/) directory:
-We welcome contributions to the Firefly ECM Library!
+- [Architecture](docs/architecture.md)
+- [Configuration](docs/configuration.md)
+- [Configuration Reference](docs/configuration-reference.md)
+- [Testing](docs/testing.md)
-### Contributing to Core Library (Port Interfaces)
-- New port interface definitions
-- Domain model enhancements
-- Infrastructure improvements
-- Documentation updates
+## Contributing
-### Contributing Adapter Implementations
-Adapter implementations are in separate repositories. See the [Available Adapters](#-available-adapters) section for repository links.
+Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests.
-Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
-- Code style and conventions
-- Testing requirements
-- Pull request process
-- Issue reporting
+## License
-## ๐ License
+Copyright 2024-2026 Firefly Software Solutions Inc.
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
-
-## ๐ Support
-
-- **Documentation**: [Firefly ECM Wiki](https://github.org/fireflyframework-oss/fireflyframework-ecm/wiki)
-- **Issues**: [GitHub Issues](https://github.org/fireflyframework-oss/fireflyframework-ecm/issues)
-- **Discussions**: [GitHub Discussions](https://github.org/fireflyframework-oss/fireflyframework-ecm/discussions)
-- **Enterprise Support**: Contact [support@getfirefly.io](mailto:support@firefly-oss.org)
-
----
-
-**Built with โค๏ธ by the Firefly OpenCore Platform Team**