Getting Started

Getting Started

This guide walks you through setting up your local development environment for StableBridge.

---

Prerequisites

Tool	Version	Notes
JDK	25+	Adoptium Temurin recommended
Docker	24+	Docker Desktop with Compose v2
Git	2.x

The Gradle wrapper (./gradlew) is checked in — you do not need to install Gradle separately.

---

Quick Start

# 1. Clone the repository
git clone https://github.com/Puneethkumarck/stablebridge-platform.git
cd stablebridge-platform

# 2. Start all infrastructure (PostgreSQL, Kafka, Temporal, Redis, etc.)
make infra-up

# 3. Build all modules (skip tests for speed)
make build

# 4. Run all tests
make test

# 5. Run a specific service
make run-merchant-onboarding

---

Local Infrastructure

All external dependencies are replaced with local equivalents via Docker Compose — $0 cost for development.

docker compose -f docker-compose.dev.yml up -d    # Start
docker compose -f docker-compose.dev.yml ps        # Status
make infra-logs                                    # Tail logs
make infra-destroy                                 # Full reset (removes volumes)

Service	Local Replacement	Port(s)
PostgreSQL	postgres:18-alpine	5432
TimescaleDB	timescale/timescaledb	5433
Kafka	Redpanda	9092 (broker), 9090 (console)
Redis	redis:8-alpine	6379
Temporal	temporalio/auto-setup	7233 (server), 8233 (UI)
Vault	vault dev mode	8200
Elasticsearch	elasticsearch:9.x	9200
Email	Mailpit	1025 (SMTP), 8025 (UI)
External APIs	WireMock	4444

Useful UIs

Tool	URL	Purpose
Redpanda Console	http://localhost:9090	Kafka topic browser
Temporal Web UI	http://localhost:8233	Workflow monitoring
Mailpit	http://localhost:8025	Captured emails
pgAdmin (optional)	Install locally	Database browser

---

Makefile Reference

Run make help for the full list.

Build

Target	Description
make build	Build all modules (skip tests)
make build-<service>	Build a single service
make format	Apply Spotless formatting
make lint	Check formatting (CI mode)
make ci	Full CI pipeline (lint + all tests)

Test

Target	Description
make test	Run all tests (unit + integration + business)
make test-unit	Unit tests only
make test-integration	Integration tests only (requires infra)
make test-business	Business tests only (requires infra)
make test-<service>-all	All tests for one service

Infrastructure

Target	Description
make infra-up	Start Docker Compose infrastructure
make infra-down	Stop infrastructure
make infra-destroy	Stop + remove volumes (full reset)
make infra-logs	Tail all container logs
make db-psql	Open psql shell

Run

Target	Description
make run-<service>	Run a service with dev profile

---

IDE Setup

IntelliJ IDEA (Recommended)

1. Open the root directory as a Gradle project
2. Enable annotation processing: Settings → Build → Compiler → Annotation Processors → Enable
3. Install plugins: Lombok, MapStruct Support
4. Import code style: the project uses Spotless with Google Java Format
5. Set SDK to Java 25+

VS Code

1. Install Extension Pack for Java
2. Install Lombok Annotations Support
3. Configure Java home to JDK 25+

---

Running a Single Service

# Via Makefile
make run-merchant-onboarding

# Via Gradle directly
./gradlew :merchant-onboarding:merchant-onboarding:bootRun

# With specific profile
./gradlew :merchant-onboarding:merchant-onboarding:bootRun --args='--spring.profiles.active=local'

Default ports:

Service	Port
S10 API Gateway	8080
S11 Merchant Onboarding	8081
S13 Merchant IAM	8082
S1 Payment Orchestrator	8083
S2 Compliance	8084
S6 FX Engine	8085
S3 Fiat On-Ramp	8086
S4 Blockchain	8087
S5 Fiat Off-Ramp	8088
S7 Ledger	8089

---

Verifying Your Setup

# 1. Check infrastructure is running
docker compose -f docker-compose.dev.yml ps

# 2. Build successfully
make build

# 3. Run unit tests (no infra needed)
make test-unit

# 4. Run integration tests (needs Docker for Testcontainers)
make test-integration

# 5. Verify database connectivity
make db-psql

---

Next Steps

• Read the Project Structure to understand the codebase layout
• Review the Coding Standards before writing code
• Check the Testing Standards for test conventions
• See the Contributing Guide for branch/PR workflow