How ipb-halle/crimsy works
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