# kitodo/kitodo-production architecture

> Architecture diagram of the GitHub repository kitodo/kitodo-production, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kitodo/kitodo-production
- Repository: https://github.com/kitodo/kitodo-production

## Overview

Based on your project’s file tree and the README, Kitodo.Production is a modular, Java‐based workflow management system built to support mass digitization projects. It is part of a larger digital library suite and uses Java Server Faces on a Tomcat container with MySQL accessed via Hibernate. The project is organized into many interconnected modules (for example, Kitodo-API, Kitodo-Command, Kitodo-DataEditor, Kitodo-DataManagement, Kitodo-FileManagement, Kitodo-ImageManagement, etc.) that together implement key functionality for processing, editing, validating, and exporting digital objects and their metadata.

##### Main Components
a. Frontend / Presentation Module: The web layer is based on Java Server Faces (JSF) as found inside the main “Kitodo/src/main/webapp” directory. This includes the user pages, managed beans, JS, CSS, and image resources.
b. Business and Workflow Engine: The core production engine and workflow processing are found throughout the “Kitodo” module and related production packages (e.g., service classes in “org.kitodo.production.services”, workflow and process management packages, etc.). This component orchestrates the digitization workflow.
c. API and Command Modules: The Kitodo-API module defines interfaces for metadata handling, command execution, and external integration. The Kitodo-Command module implements commands that trigger parts of the process.
d. Data Management / Persistence Layer: The “Kitodo-DataManagement” module handles database persistence via Hibernate and connects to a MySQL backend. This layer includes data access objects (DAOs), database entity definitions, and migration scripts.
e. Data Editor and Metadata Modules: Modules such as Kitodo-DataEditor and Kitodo-DataFormat deal with both the enrichment/editing of descriptive and structural metadata and schema conversions.
f. File and Image Management: Modules like Kitodo-FileManagement and Kitodo-ImageManagement deal with physical file handling, file mapping, and media derivative generation.
g. Additional Specialized Modules: Other modules include
– Kitodo-Docket (for export/generation of docket information),
– Kitodo-LongTermPreservationValidation (for validating long term preservation parameters),
– Kitodo-PersistentIdentifier (for generating DOIs/URNs),
– Kitodo-Query-URL-Import (to import data from external catalogs),
– Kitodo-Validation (for structural and metadata validations),
– Kitodo-XML-SchemaConverter (for converting between XML schemas).

##### Relationships and Interactions
- That the business layer calls the API and command interfaces (from Kitodo-API and Kitodo-Command) and uses these interfaces to trigger operations such as metadata editing, workflow state transitions, or process creation.
- That the Data Editor, File Management, and Image Management modules integrate specialized functionality into the workflow engine; for example, the data editor module might pass metadata to the file management module to update files, and the image management module may handle image conversion calls within a process.
- If applicable, put message-oriented middleware (e.g., Activemq) as a communications bus (as hinted in documentation) connecting components like the command service, workflow updates, and external interfaces.

##### Architectural Patterns and Design Principles
- Use a layered (or multi-tiered) architecture to separate the presentation, business logic, and persistence layers.
- Stress the modular design in which clearly defined interfaces (as seen in many “Interface” and “ServiceLoader” classes) allow each module (API, editor, validator, etc.) to be developed, maintained, or even replaced independently.
- Adherence to MVC in the JSF front-end and a Service-Oriented approach in the business layer.
- Use of standard frameworks (JSF, Hibernate) and integration patterns (such as command execution and schema conversion) that support extensibility.

##### Relevant Technologies, Frameworks, and Libraries
- Java and Java EE (specifically Java Server Faces),
- Apache Tomcat as the servlet container,
- MySQL as the database,
- Hibernate for ORM,
- Possibly Activemq or equivalent for messaging (indicated by “activemq” packages and documentation),
- RESTful or service calls (the API layer),
- XML and XSLT processing libraries (especially in the XML-SchemaConverter and metadata export functionalities).

##### Specific Elements
- Use clear labels for each component. For instance, “Web Presentation (JSF)”, “Workflow Engine & Production Services”, “Metadata Editing & Data Format Conversion”, “Command & API Interfaces”, “Data Management (Hibernate / MySQL)”, “File & Image Management”, and “Validation / Export Modules”.
- Optionally, illustrate external interactions (for example, external catalog interfaces or messaging systems) with differently styled connectors or annotations.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Presentation Layer"
        A["Web Presentation (JSF)"]:::frontend
    end

    subgraph "Business / Workflow Layer"
        B["Workflow Engine & Production Services"]:::backend
        C["API Module"]:::backend
        D["Command Module"]:::backend
        P["Messaging Bus (ActiveMQ)"]:::integration
    end

    subgraph "Data & Integration Modules"
        F["Data Editor"]:::module
        G["Data Format Conversion"]:::module
        H["File Management"]:::module
        I["Image Management"]:::module
    end

    subgraph "Additional Specialized Modules"
        J["Docket"]:::module
        K["LongTermPreservationValidation"]:::module
        L["Persistent Identifier"]:::module
        M["Query-URL Import"]:::module
        N["Validation"]:::module
        O["XML Schema Converter"]:::module
    end

    subgraph "Persistence Layer"
        E["Data Management (Hibernate/MySQL)"]:::persistence
        DB["MySQL Database"]:::database
    end

    %% Connections between layers
    A -->|"calls"| B
    B -->|"invokes"| C
    B -->|"triggers"| D
    B -->|"persists via"| E
    E -->|"stores data in"| DB
    B -->|"integrates"| F
    B -->|"integrates"| G
    B -->|"integrates"| H
    B -->|"integrates"| I

    %% Connections to Additional Specialized Modules
    B -->|"connects to"| J
    B -->|"connects to"| K
    B -->|"connects to"| L
    B -->|"connects to"| M
    B -->|"connects to"| N
    B -->|"connects to"| O

    %% Messaging interactions
    D -->|"sends messages to"| P
    B -->|"publishes updates to"| P

    %% Click Events
    click A "https://github.com/kitodo/kitodo-production/tree/main/Kitodo/src/main/webapp"
    click B "https://github.com/kitodo/kitodo-production/tree/main/Kitodo/src/main/java/org/kitodo/production"
    click C "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-API"
    click D "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-Command"
    click E "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-DataManagement"
    click F "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-DataEditor"
    click G "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-DataFormat"
    click H "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-FileManagement"
    click I "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-ImageManagement"
    click J "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-Docket"
    click K "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-LongTermPreservationValidation"
    click L "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-PersistentIdentifier"
    click M "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-Query-URL-Import"
    click N "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-Validation"
    click O "https://github.com/kitodo/kitodo-production/tree/main/Kitodo-XML-SchemaConverter"

    %% Styles
    classDef frontend fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef backend fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef persistence fill:#f94144,stroke:#333,stroke-width:2px;
    classDef module fill:#577590,stroke:#333,stroke-width:2px;
    classDef integration fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef database fill:#277da1,stroke:#333,stroke-width:2px;
```
