Module Architecture

The repository uses a four-POM Maven structure grouping services by framework.

Repository Layout

quarkus/                          ← root aggregator
├── messaging-contracts/          ← Framework-agnostic message DTOs (Jackson)
├── messaging-infrastructure/     ← MessageBus, retry, idempotency, DLQ
├── quarkus/                      ← Quarkus parent
│   ├── common/                   ← Shared utilities
│   ├── metadata/                 ← Metadata domain
│   │   ├── metadata-consumer/    ← RabbitMQ consumer
│   │   ├── metadata-dto/         ← Data transfer objects
│   │   ├── metadata-persistence/ ← Panache entities
│   │   ├── metadata-producer/    ← Event producer
│   │   ├── metadata-rest/        ← REST API (Lambda-deployable)
│   │   ├── metadata-service/     ← Business logic
│   │   ├── metadata-sse/         ← SSE endpoints
│   │   └── metadata-test/        ← Tests
│   ├── organisation/             ← Organisation domain (same submodule pattern)
│   │   ├── organisation-consumer/
│   │   ├── organisation-dto/
│   │   ├── organisation-persistence/
│   │   ├── organisation-producer/
│   │   ├── organisation-rest/
│   │   ├── organisation-service/
│   │   ├── organisation-sse/
│   │   └── organisation-test/
│   └── consumer-worker/          ← Standalone worker (Fargate JVM container)
└── spring-boot/                  ← Spring Boot parent
    ├── processor/                ← DDL generation & Flyway migration
    │   ├── processor-consumer/   ← RabbitMQ consumer
    │   ├── processor-core/       ← Hibernate DDL, Flyway
    │   ├── processor-service/    ← Business logic
    │   └── processor-test/       ← Tests
    ├── workspace-api/            ← Dynamic CRUD REST API
    │   ├── workspace-api-core/
    │   ├── workspace-api-rest/
    │   ├── workspace-api-service/
    │   └── workspace-api-test/
    └── session/                  ← Session factory caching & tenant isolation

POM Hierarchy

root pom.xml (aggregator only — Java 21)
├── messaging-contracts
├── messaging-infrastructure
├── quarkus/pom.xml (framework parent — Java 21)
│   ├── common
│   ├── organisation
│   ├── metadata
│   └── consumer-worker
└── spring-boot/pom.xml (framework parent — Java 21)
    ├── session
    ├── processor/pom.xml (service aggregator)
    └── workspace-api

Java version

All modules compile with Java 21.

Module Dependency Rules

Allowed

• Any module → messaging-contracts (shared DTOs)
• Any Quarkus module → common
• Within a domain: *-rest → *-service → *-persistence
• *-consumer → *-service (processes incoming messages)
• *-producer → messaging-contracts (publishes messages)
• *-sse → *-service (streams events to clients)

Prohibited

• *-persistence → *-rest (no reverse dependency)
• *-dto → anything except messaging-contracts
• Cross-domain persistence imports (e.g., metadata-persistence → organisation-persistence)
• Spring Boot → Quarkus modules or vice versa (communicate via RabbitMQ only)

Key Modules

messaging-contracts

Framework-agnostic Jackson-based message DTOs shared between Quarkus and Spring Boot. Published to local Maven via install-contracts.sh.

metadata

Core domain. Manages workspaces, views, columns, constraints, presets, and relationships. The -rest module is Lambda-deployable. The -consumer handles task completion messages from the processor.

organisation

Manages organisations, memberships, invitations, authentication, 2FA, and user profiles. Same submodule pattern as metadata.

processor (Spring Boot)

Receives metadata-updates messages via RabbitMQ. Uses Hibernate to generate DDL and Flyway to apply migrations to customer workspace databases. Includes Resilience4j circuit breakers and retry logic.

workspace-api (Spring Boot)

Dynamically generates REST CRUD endpoints for workspace entities. Uses the schema metadata to serve data from customer databases without hardcoded entity classes.

consumer-worker

Standalone Quarkus JVM worker for Fargate deployment. Runs consumers that don't fit in the Lambda model.