Development Setup

Prerequisites

• Java 21 (all modules compile and run with Java 21)
• Maven 3.8+ (Maven wrapper mvnw is included in the repo)
• Docker and Docker Compose

Quick Start (Full Stack)

Starting the complete stack requires three repositories and multiple terminal sessions.

Backend (schemastack-be)

# Terminal 1 — Quarkus REST + infrastructure (Docker, RabbitMQ, PostgreSQL)
./scripts/dev-start.sh

# Terminal 2 — Spring Boot Processor (DDL/migrations)
./scripts/processor-start.sh

# Terminal 3 — Spring Boot Workspace API (dynamic CRUD)
./scripts/workspace-api-start.sh

Frontend (schemastack-fe)

# Terminal 4 — Spread (Data Platform)
ng serve --port=4200 spread

# Terminal 5 — Admin Console
ng serve --port=4201 admin

Docs (schemastack-docs)

npm run dev        # Public docs
npm run dev:dev    # Dev docs

Backend Tests

# Run full test suite in an isolated copy (non-blocking)
./scripts/run-tests-background.sh

# Auto-run tests on file changes
./scripts/run-tests-watch.sh

Infrastructure Services

Docker Compose starts two services:

Service	Port	Credentials
PostgreSQL 18	localhost:5432	postgres / your-password, database dynamicdb
RabbitMQ AMQP	localhost:5673	guest / guest
RabbitMQ Management	localhost:15673	guest / guest

Non-standard RabbitMQ port

RabbitMQ runs on 5673 (not the default 5672) to avoid conflicts with other local services. The management UI is on 15673.

Environment Files

File	Purpose
.env	Base configuration (database, JWT, mailer, RabbitMQ)
.env.local	Local development overrides
.env.test	Test configuration with TestContainers and in-memory messaging

Building

# Full recompile without tests (fast)
./mvnw clean install -DskipTests=true

# Full recompile with tests (slow)
./mvnw clean install -DskipTests=false

# Build a specific module
./mvnw clean install -pl quarkus/metadata/metadata-rest -am

Service URLs

Service	URL
Quarkus REST API	http://localhost:8080
Spring Boot Processor	http://localhost:8082
Spring Boot Workspace API	http://localhost:8083
RabbitMQ Management	http://localhost:15673

Data Persistence

Docker volumes persist data between restarts:

• postgres_data — PostgreSQL data
• rabbitmq_data — RabbitMQ state
• rabbitmq_logs — RabbitMQ logs

To reset all data: docker compose down -v

RabbitMQ Consumer Timeout

The Docker Compose config sets a 30-second consumer timeout (consumer_timeout 30000). This prevents zombie consumers from accumulating during Quarkus dev mode hot-reloads.

Scripts Reference

All scripts live in the scripts/ directory.

Startup & Shutdown

Script	Description
dev-start.sh	Start Docker services + Quarkus dev mode. Pass --reset to drop and recreate dynamicdb. Also purges dev RabbitMQ queues and cleans up failed migrations.
dev-stop.sh	Kill Maven processes (graceful, then force) and docker compose down.
processor-start.sh	Start the Spring Boot Processor on port 8082. Checks that Quarkus is running on 8080 first.
workspace-api-start.sh	Start the Spring Boot Workspace API on port 8083. Checks that Quarkus is running on 8080 first.

Build Helpers

Script	Description
install-contracts.sh	Build and install messaging-contracts to local Maven (~/.m2). Run this after changing shared message DTOs so both Quarkus and Spring Boot pick them up.

Testing

Script	Description
run-tests-background.sh	Rsync the source to an isolated directory and run the full build+test suite in the background. Sends macOS notifications on success/failure. Use --watch to follow output, --status to check progress.
run-tests-watch.sh	Watch for file changes using fswatch and auto-run tests after an idle period (default 10s, configure with --idle <seconds>). Use --stop to stop the watcher. Requires brew install fswatch.

Diagnostics

Script	Description
rabbitmq-status.sh	Query RabbitMQ Management API. Subcommands: status (queue overview), messages [queue] (peek at messages), dlq (dead letter queue), purge <queue> (empty a queue).

Database Diagnostics (scripts/diagnostics/)

Run via diagnostics/run-all-diagnostics.sh (interactive — prompts for credentials and runs all checks), or individually:

Script	Run against	Description
check-duplicate-columns.sql	Metadata DB (dynamicdb)	Find duplicate columns in the metadata tables. Drift detection crashes with "Duplicate key" errors when these exist.
cleanup-duplicate-columns.sql	Metadata DB (dynamicdb)	Delete duplicate columns, keeping the first occurrence (lowest ID). Runs in a transaction — any error rolls back.
check-workspace-catalog.sql	Workspace DB (customer)	Check PostgreSQL pg_attribute system catalog for duplicate columns. Rows found = real database corruption (not just a code bug).

Liquibase Migrations

Three independent Liquibase changelogs (the metadata master includes the other two):

Module	Master File	Changesets
Metadata	metadata-persistence/.../changelog-metadata.xml	46 (1.0 — 1.47)
Organisation	organisation-persistence/.../changelog-organisation.xml	11 (1.0 — 6.0)
Messaging	messaging-infrastructure/.../changelog-messaging.xml	1 (1.0)
Total	3 masters	58 production changesets

Key migration landmarks:

Version	What
1.0	Initial schema (entities, views, columns)
1.3	RBAC permissions
1.20	Relationship column support
1.21-1.22	Bulk action jobs
1.23-1.25	Filter presets + sorts
1.26	Sync operation tracking
1.27	Outbox messages
1.32	View guest access
1.40	Workspace API keys
1.47	Usage tracking
org-4.4	Two-factor authentication
org-6.0	Subscription tiers

Dev seed data files (context="dev") provide local development fixtures: test users, organisations, workspace memberships.

Deployment

Two deployment patterns:

Lambda (REST API)

FROM public.ecr.aws/lambda/provided:al2
COPY target/function/bootstrap /var/task/bootstrap
CMD ["bootstrap"]

Quarkus native binary built for Lambda. Stateless, cold start optimized.

Fargate (Consumer Worker)

Multi-stage Maven build → JVM-based Quarkus fast-jar:

• Build: maven:3.9.9-eclipse-temurin-21 with Maven cache mount
• Runtime: eclipse-temurin:21-jre-alpine
• Build arg: QUARKUS_PROFILE=worker
• Copies cert.pem for TLS
• Port 8080