# youssefalmia/report-workflow architecture

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

- Interactive diagram: https://gitdiagram.com/youssefalmia/report-workflow
- Repository: https://github.com/youssefalmia/report-workflow

## Overview

##### Project Type and Purpose
- This project is a backend workflow management system built in Java with Spring Boot.
- It automates report handling with structured steps (create, review, validate) and uses Camunda BPMN for workflow orchestration.
- It integrates security measures (JWT authentication, RBAC), event-driven state updates, and a flexible workflow strategy using a factory pattern.

##### Analyzing the File Structure
- The top-level directories and files indicate a Maven-based Spring Boot project.
- The “src/main/java” tree shows a clear separation:
- Configuration classes (e.g., SecurityConfig, AsyncConfig, OpenApiConfig)
- Controllers (e.g., AuthController, ReportController) that expose REST API endpoints.
- Domain classes (entities, enums, and repositories) for the persistence layer.
- DTOs and Mappers for translating data.
- A service layer that contains business logic (including Camunda integration, workflow strategies, and event listeners).
- Utility classes (e.g., JwtUtil, CamundaDatabaseCleaner).
- The “src/main/resources” directory contains the BPMN definition and application properties.
- Testing is well-organized across unit, integration, and performance tests.

##### Key Components
A. REST API Layer:
- That these endpoints use JWT tokens and enforce RBAC via Spring Security.
B. Security & Configuration:
- A component for SecurityConfig and JwtAuthFilter showcasing token-based authentication, role validation, and custom error handling.
- Dual enforcement: security filtering via Spring Security and method-level checks (@PreAuthorize).
C. Service Layer:
- ReportWorkflowService that delegates workflow operations to a chosen strategy.
- Workflow Strategy and Factory Pattern:
- IReportWorkflowStrategy interface and concrete implementations like CamundaReportWorkflow.
- ReportWorkflowFactory which selects the proper strategy based on configuration.
D. Workflow Management Integration:
- Camunda BPMN as an external engine.
- BPMN file (located in “src/main/resources/bpm/camunda/report-workflow.bpmn”) and its mapping into the application.
E. Event-Driven State Updates:
- A sub-component for ReportStateListener that captures task and execution events.
- ReportStateEventListener to update the database accordingly (including logging transitions and saving ReportTransitionLog entries).
F. Persistence Layer:
- Domain models (Report, User, ReportTransitionLog) and their corresponding repositories.
- Use of H2 in-memory database as configured in application.properties.
G. Supporting Utilities and Testing:
- Optionally, include utility classes like JwtUtil for token management.

##### Relationships And Data Flow
- How ReportService uses ReportWorkflowService, which internally obtains a workflow strategy from ReportWorkflowFactory.
- That security checks occur at two levels: a pre-request filtering stage and within the service methods.
- That state transitions (created, reviewed, validated/refused) are recorded in the database and logged.

##### Architectural Patterns and Technologies
- Use of the Strategy Pattern and Factory Pattern in the workflow mechanism.
- Integration with the Camunda BPM engine.
- Layered architecture: controllers (presentation), services (business logic), domain/repositories (persistence), and configuration/security.
- Libraries and technologies: Spring Boot, Spring Security, Maven, Camunda BPM, JWT, and H2 database.

##### Putting It All Together
- Branch out to the event-driven components (ReportStateListener and ReportStateEventListener) that update the database represented in the persistence layer.
- Security layer as an overlay that intercepts incoming API requests.

## Diagram (Mermaid)

```mermaid
graph TD
    Client("API Consumer"):::client

    subgraph "Security & Configuration"
        SC("SecurityConfig"):::security
        JF("JwtAuthFilter"):::security
    end

    subgraph "REST API Layer"
        AC("AuthController"):::controller
        RC("ReportController"):::controller
    end

    subgraph "Service Layer"
        RS("ReportService"):::service
        RWS("ReportWorkflowService"):::service
        RWF("ReportWorkflowFactory"):::service
    end

    subgraph "Workflow & Camunda Integration"
        IRS("IReportWorkflowStrategy"):::workflow
        CRW("CamundaReportWorkflow"):::workflow
        CTM("CamundaTaskManager"):::workflow
        BPMN("Camunda BPMN (report-workflow.bpmn)"):::workflow
    end

    subgraph "Event-Driven Updates"
        RSL("ReportStateListener"):::event
        RSEL("ReportStateEventListener"):::event
        RSC("ReportStateChangedEvent"):::event
    end

    subgraph "Persistence Layer"
        R("Report"):::persistence
        RR("ReportRepository"):::persistence
        RTL("ReportTransitionLog"):::persistence
        RTLR("ReportTransitionLogRepository"):::persistence
        U("User"):::persistence
        UR("UserRepository"):::persistence
    end

    subgraph "Supporting Utilities"
        JU("JwtUtil"):::utility
        CDC("CamundaDatabaseCleaner"):::utility
    end

    %% Relationships
    Client -->|"JWT"| JF
    JF --> AC
    JF --> RC
    SC --- JF

    AC -->|"calls"| RS
    RC -->|"calls"| RS

    RS -->|"delegates"| RWS
    RWS -->|"selectsStrategy"| RWF
    RWF -->|"returns"| IRS
    IRS -->|"implements"| CRW
    CRW --> CTM
    CTM --> BPMN

    BPMN -->|"firesEvents"| RSL
    RSL -->|"notifies"| RSEL
    RSEL -->|"updates"| RR
    RSEL --> RTLR

    RR --> R
    RTLR --> RTL
    RSEL --- UR
    U --- UR

    RS --- JU
    RWS --- CDC

    RSL --- RSC

classDef client fill:#bbf,stroke:#333,stroke-width:2px;
classDef controller fill:#f9c,stroke:#333,stroke-width:2px;
classDef security fill:#f99,stroke:#333,stroke-width:2px;
classDef service fill:#9cf,stroke:#333,stroke-width:2px;
classDef workflow fill:#fc9,stroke:#333,stroke-width:2px;
classDef event fill:#cff,stroke:#333,stroke-width:2px;
classDef persistence fill:#9f9,stroke:#333,stroke-width:2px;
classDef utility fill:#ff9,stroke:#333,stroke-width:2px;

click AC "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/controllers/AuthController.java"
click RC "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/controllers/ReportController.java"
click SC "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/config/SecurityConfig.java"
click JF "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/config/JwtAuthFilter.java"
click RS "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/ReportService.java"
click RWS "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/ReportWorkflowService.java"
click RWF "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/ReportWorkflowFactory.java"
click IRS "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/IReportWorkflowStrategy.java"
click CRW "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/camunda/CamundaReportWorkflow.java"
click CTM "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/camunda/CamundaTaskManager.java"
click BPMN "https://github.com/youssefalmia/report-workflow/blob/main/src/main/resources/bpm/camunda/report-workflow.bpmn"
click RSL "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/camunda/ReportStateListener.java"
click RSEL "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/service/ReportStateEventListener.java"
click RSC "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/dto/ReportStateChangedEvent.java"
click R "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/domain/Report.java"
click RR "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/domain/ReportRepository.java"
click RTL "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/domain/ReportTransitionLog.java"
click RTLR "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/domain/ReportTransitionLogRepository.java"
click U "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/domain/User.java"
click UR "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/domain/UserRepository.java"
click JU "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/utils/JwtUtil.java"
click CDC "https://github.com/youssefalmia/report-workflow/blob/main/src/main/java/com/youssef/reportworkflow/utils/CamundaDatabaseCleaner.java"
```
