Project Structure

Project Structure

Repository Layout

stablebridge-platform/
├── api-gateway-iam/              # S10 — API Gateway & IAM
├── blockchain-custody/           # S4  — Blockchain & Custody
├── compliance-travel-rule/       # S2  — Compliance & Travel Rule
├── fiat-off-ramp/                # S5  — Fiat Off-Ramp
├── fiat-on-ramp/                 # S3  — Fiat On-Ramp
├── fx-liquidity-engine/          # S6  — FX & Liquidity Engine
├── ledger-accounting/            # S7  — Ledger & Accounting
├── merchant-iam/                 # S13 — Merchant IAM
├── merchant-onboarding/          # S11 — Merchant Onboarding
├── payment-orchestrator/         # S1  — Payment Orchestrator
│
├── platform-api/                 # Shared API DTOs and contracts
├── platform-infra/               # Shared infrastructure (Kafka DLQ, outbox base, Feign)
├── platform-test/                # Shared test utilities (Testcontainers config)
│
├── phase2-integration-tests/     # Cross-service integration tests (Phase 2)
├── phase3-integration-tests/     # Cross-service integration tests (Phase 3)
│
├── buildSrc/                     # Gradle convention plugins
│   └── src/main/kotlin/
│       ├── stablebridge.api-library.gradle.kts
│       ├── stablebridge.client-library.gradle.kts
│       └── stablebridge.service.gradle.kts
│
├── infra/
│   ├── k8s/                      # Kubernetes manifests
│   ├── local/
│   │   ├── postgres/init.sql     # Multi-database init (14 service DBs)
│   │   └── wiremock/             # WireMock stubs for external providers
│   ├── postman/                  # Postman collections
│   └── terraform/                # AWS Terraform modules
│
├── services/                     # Service specification documents (14 specs)
├── playbook/                     # Architecture & coding standards (10 docs)
├── docs/                         # Research, OpenAPI specs, phase reviews
├── config/                       # OWASP suppressions, etc.
├── monitoring/                   # Observability configuration
│
├── docker-compose.dev.yml        # Local development stack
├── Makefile                      # Build, test, and infra shortcuts
├── build.gradle.kts              # Root Gradle build configuration
├── settings.gradle.kts           # Multi-module settings
└── gradle.properties             # Dependency versions

---

Service Module Layout (Tri-Module)

Every service follows a three-module Gradle structure:

<service>/
├── <service>-api/                # PUBLIC_API — shared contract
│   └── src/main/java/com/stablecoin/payments/<service>/api/
│       ├── request/              # Request DTOs (Java records)
│       └── response/             # Response DTOs (Java records)
│
├── <service>-client/             # Feign client for inter-service calls
│   └── src/main/java/com/stablecoin/payments/<service>/client/
│       └── <Service>Client.java  # Feign interface
│
└── <service>/                    # Main Spring Boot application
    ├── src/main/java/com/stablecoin/payments/<service>/
    │   ├── bootstrap/
    │   │   └── <Service>Application.java    # @SpringBootApplication
    │   │
    │   ├── application/                     # APPLICATION LAYER
    │   │   ├── controller/                  # REST controllers (thin)
    │   │   │   ├── <Resource>Controller.java
    │   │   │   └── mapper/                  # Request/response mappers
    │   │   └── config/                      # Spring configuration
    │   │
    │   ├── domain/                          # DOMAIN LAYER (pure business logic)
    │   │   ├── model/                       # Aggregates, value objects, enums
    │   │   │   ├── <Aggregate>.java         # Aggregate root (record)
    │   │   │   ├── <ValueObject>.java       # Value objects (records)
    │   │   │   ├── command/                 # Command records
    │   │   │   └── event/                   # Domain event records
    │   │   ├── port/                        # Port interfaces
    │   │   │   ├── <Aggregate>Repository.java   # Outbound persistence port
    │   │   │   └── <Provider>Port.java          # Outbound integration port
    │   │   └── service/                     # Command handlers
    │   │       └── <Aggregate>CommandHandler.java  # @Service @Transactional
    │   │
    │   └── infrastructure/                  # INFRASTRUCTURE LAYER
    │       ├── adapter/                     # Port implementations
    │       │   ├── persistence/
    │       │   │   ├── <Aggregate>Entity.java
    │       │   │   ├── <Aggregate>JpaRepository.java
    │       │   │   ├── <Aggregate>RepositoryAdapter.java
    │       │   │   └── <Aggregate>EntityMapper.java
    │       │   └── provider/
    │       │       └── <Provider>Adapter.java
    │       ├── messaging/                   # Kafka publishers, outbox
    │       └── config/                      # Infrastructure config
    │
    ├── src/main/resources/
    │   ├── application.yml
    │   ├── application-local.yml
    │   └── db/migration/                    # Flyway SQL migrations
    │
    ├── src/test/                             # Unit tests
    ├── src/testFixtures/                     # Shared test fixtures
    │   └── java/.../fixtures/
    │       ├── <Aggregate>Fixtures.java     # Factory methods
    │       └── TestUtils.java               # eqIgnoringTimestamps, eqIgnoring
    ├── src/integration-test/                 # Integration tests (Testcontainers)
    └── src/business-test/                    # End-to-end business tests

---

Shared Platform Modules

platform-api

Shared API DTOs and contracts used across services. Contains common request/response types, error codes, and enums.

platform-infra

Shared infrastructure code:

• CorrelationIdFeignInterceptor — HTTP client correlation ID propagation
• KafkaDlqConfig — Dead-letter queue configuration
• AbstractOutboxEventPublisher — Base class for Namastack outbox publishers
• AbstractOutboxHandler — Base class for Kafka relay handlers
• BaseGlobalExceptionHandler — Shared exception handling

platform-test

Shared test utilities: Testcontainers configuration, base test classes.

---

Gradle Convention Plugins

The buildSrc/ directory contains three convention plugins that standardize module configuration:

Plugin	Applied To	What It Configures
stablebridge.api-library	-api modules	Java library, Lombok, Jakarta Validation
stablebridge.client-library	-client modules	Java library, Feign dependencies
stablebridge.service	Main service modules	Spring Boot, JPA, Kafka, test source sets, JaCoCo

---

Dependency Direction

                    ┌─────────────┐
                    │ PUBLIC_API   │  (separate -api module)
                    │  DTOs only   │  depends on: NOTHING
                    └──────┬──────┘
                           │ imported by
            ┌──────────────┼──────────────┐
            ▼              ▼              ▼
   ┌──────────────┐ ┌───────────┐ ┌────────────────┐
   │ APPLICATION  │ │  DOMAIN   │ │ INFRASTRUCTURE │
   │              │ │           │ │                │
   │ controllers  │ │ aggregate │ │ DB adapters    │
   │ config       │ │ services  │ │ HTTP clients   │
   │              │ │ ports     │ │ publishers     │
   └──────────────┘ └───────────┘ └────────────────┘

   APPLICATION  ──calls──▶  DOMAIN
   INFRASTRUCTURE ─calls──▶  DOMAIN (implements ports)
   DOMAIN       ──calls──▶  NOTHING (zero outward deps)

---

Key Conventions

Convention	Rule
Build tool	Gradle 9.3.1, Kotlin DSL (build.gradle.kts)
Base package	com.stablecoin.payments.<service>
Module layout	Flat top-level (no nested services/ directory)
No web/ package	Controllers go under application.controller
No wildcard imports	Every import is explicit
Static imports	Used wherever they improve readability

---

Related Pages

• Coding Standards — Naming and style conventions
• Architecture Overview — Layer rules and hexagonal architecture
• Testing Standards — Test source set details