# ipb-halle/crimsy architecture

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

- Interactive diagram: https://gitdiagram.com/ipb-halle/crimsy
- Repository: https://github.com/ipb-halle/crimsy

## Overview

##### Project type and purpose
- This is a large, Maven-based, multi-module Java EE application (“CRIMSy”) providing a distributed research platform.
- It consists of UI modules (JSF webapps), REST API modules, background/agent modules, domain libraries, database persistence layers, utility scripts, Docker artifacts and extensive documentation.

##### High-level module breakdown
- Parent pom.xml (aggregator)
- “ui” & “kx-web”: JSF/UI web applications (WARs) behind Apache HTTPD/Tomcat/TomEE
- “crimsy-api”, “kx-api”, “reporting-api”, “crimsy-job-api”: API modules (JAX-RS endpoints + DTOs + WebClients)
- “crimsy-job-storage”, “reporting”, “tx”, “snowball”: Service modules implementing business logic, JPA entities and database persistence (JARs)
- “agency”: a scheduling/agent module for remote job execution
- “crimsy-test”: shared test utilities & testcontainers setup
- “util”: shell/python scripts, Docker-Compose specs, systemd templates, report templates
- “docker”: Dockerfiles for CI, DB, proxy, FASTA service, UI proxy

##### Key architectural components
a. Frontend layer
- Browser → Apache HTTPD (reverse-proxy) → UI WARs (ui and kx-web)
- UI uses JSF, CDI, EJB and faces-config, persistence.xml for JPA
b. API / service layer
- REST endpoints (JAX-RS) in each “-api” module expose CRUD & business operations
- WebClients in UI and other modules invoke these endpoints
c. Business / persistence layer
- Service modules (“-storage”, “reporting”, “tx”, “snowball”) contain JPA entities, @Stateless services, repositories
- All connect to a shared PostgreSQL database (Docker/db)
d. Scheduling & background jobs
- “agency” module runs scheduled handlers (Agency.java, Handler.java) to dispatch and monitor long-running tasks
e. External/auxiliary services
- FASTA search service (docker/fasta)
- TermVector/stemming library (“snowball”)
- Search & word-cloud modules under ui (invoking kx, tx services)

##### Interactions and data flow
- User → UI (webapp)
- UI → REST APIs (HTTP calls to crimsy-api, kx-api, reporting-api, job-api)
- REST APIs → Business services → JPA → PostgreSQL
- Business services may call other APIs (via WebClient) for cross-module coordination (e.g., job scheduling, reporting generation)
- “agency” polls or receives triggers to launch background jobs
- Docker Compose wires up HTTPD proxy, multiple service containers, DB container

##### Architectural patterns & principles
- Layered architecture: Presentation → API → Business → Persistence
- Maven multi-module for clear separation of concerns and independent lifecycle of subprojects
- JAX-RS / CDI / EJB for service endpoints and dependency injection
- Repository pattern via JPA entities and service interfaces
- Modularization by functional domain (search, reporting, job, kx, tx, UI)
- Use of Docker for environment consistency and CI/CD

##### Essential details
- Persistence units or schemas if modules use separate ones

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build
    subgraph "Build/CI"
        Maven["Maven Parent (Aggregator)"]:::build
    end

    %% UI Container
    subgraph "UI Container" 
        ui_ui["ui WAR"]:::ui
        ui_kx["kx-web WAR"]:::ui
    end

    %% API Services
    subgraph "API Services"
        crimsy_api["crimsy-api.jar"]:::api
        kx_api["kx-api.jar"]:::api
        reporting_api["reporting-api.jar"]:::api
        job_api["crimsy-job-api.jar"]:::api
    end

    %% Business/Service Modules
    subgraph "Business Services"
        job_storage["crimsy-job-storage"]:::service
        reporting_srv["reporting"]:::service
        tx_srv["tx"]:::service
        snowball_lib["snowball"]:::service
    end

    %% Agency Scheduler
    subgraph "Scheduler/Agency"
        agency["agency Scheduler"]:::agency
    end

    %% Database
    subgraph "Persistence"
        db["PostgreSQL"]:::db
    end

    %% External Services
    subgraph "External Services"
        fasta["FASTA Service"]:::external
    end

    %% User Interaction
    User(("User")):::user

    %% Interactions
    User -->|"HTTP"| ui_ui
    User -->|"HTTP"| ui_kx

    ui_ui -->|"REST API"| crimsy_api
    ui_ui -->|"REST API"| kx_api
    ui_ui -->|"REST API"| reporting_api
    ui_ui -->|"REST API"| job_api

    ui_kx -->|"REST API"| kx_api
    ui_kx -->|"REST API"| tx_srv

    crimsy_api -->|"EJB/REST"| job_storage
    crimsy_api -->|"EJB/REST"| reporting_srv
    crimsy_api -->|"EJB/REST"| tx_srv

    kx_api -->|"REST"| snowball_lib
    kx_api -->|"REST"| tx_srv

    reporting_api -->|"REST"| reporting_srv

    job_api -->|"REST"| job_storage

    job_storage -->|"JPA"| db
    reporting_srv -->|"JPA"| db
    tx_srv -->|"JPA"| db
    snowball_lib -->|"JPA"| db

    tx_srv -->|"HTTP"| fasta

    agency -->|"Schedules/Calls"| job_api
    agency -->|"Monitors"| job_storage

    %% Build flow
    Maven --> ui_ui
    Maven --> ui_kx
    Maven --> crimsy_api
    Maven --> kx_api
    Maven --> reporting_api
    Maven --> job_api
    Maven --> job_storage
    Maven --> reporting_srv
    Maven --> tx_srv
    Maven --> snowball_lib
    Maven --> agency

    %% Click Events
    click Maven "https://github.com/ipb-halle/crimsy/blob/master//pom.xml"
    click ui_ui "https://github.com/ipb-halle/crimsy/tree/master//ui"
    click ui_kx "https://github.com/ipb-halle/crimsy/tree/master//kx-web"
    click crimsy_api "https://github.com/ipb-halle/crimsy/tree/master//crimsy-api"
    click kx_api "https://github.com/ipb-halle/crimsy/tree/master//kx-api"
    click reporting_api "https://github.com/ipb-halle/crimsy/tree/master//reporting-api"
    click job_api "https://github.com/ipb-halle/crimsy/tree/master//crimsy-job-api"
    click job_storage "https://github.com/ipb-halle/crimsy/tree/master//crimsy-job-storage"
    click reporting_srv "https://github.com/ipb-halle/crimsy/tree/master//reporting"
    click tx_srv "https://github.com/ipb-halle/crimsy/tree/master//tx"
    click snowball_lib "https://github.com/ipb-halle/crimsy/tree/master//snowball"
    click agency "https://github.com/ipb-halle/crimsy/tree/master//agency"

    %% Styles
    classDef build fill:#8dd3c7,stroke:#333,stroke-width:1px
    classDef ui fill:#aec7e8,stroke:#333,stroke-width:1px
    classDef api fill:#98df8a,stroke:#333,stroke-width:1px
    classDef service fill:#ffbb78,stroke:#333,stroke-width:1px
    classDef db fill:#ff9896,stroke:#333,stroke-width:1px
    classDef external fill:#c7c7c7,stroke:#333,stroke-width:1px
    classDef agency fill:#c5b0d5,stroke:#333,stroke-width:1px
    classDef user fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
