Banking Domain Conventions

Firefly Banking Platform Conventions

1. Service Taxonomy

The Firefly Banking Platform organizes ~55 repositories into six domain prefixes. Each prefix defines the service's role, architectural tier, and framework starter.

Additional non-service repos:

2. Package Naming

All Firefly platform code uses groupId = com.firefly. Java packages follow the pattern:

com.firefly.{tier}.{domain-short-name}.{module-layer}.{sub-package}

Real examples from the codebase:

Key pattern: the domain short name drops the prefix category and management suffix. For example, core-common-customer-mgmt becomes core.customer, and domain-customer-people becomes domain.people.

3. POM Inheritance Chain

Every service follows a three-level POM hierarchy:

org.fireflyframework:fireflyframework-parent (1.0.0-SNAPSHOT)
    |
    v
com.firefly:firefly-parent (1.0.0-SNAPSHOT)
    |
    v
com.firefly:{service-artifactId} (1.0.0-SNAPSHOT)

What fireflyframework-parent provides

• Spring Boot parent (version management for Spring Boot, Spring Cloud, etc.)
• Plugin management (maven-compiler-plugin, spring-boot-maven-plugin, etc.)
• Dependency versions for framework artifacts (org.fireflyframework groupId)

What firefly-parent adds on top

• Imports two BOMs: fireflyframework-bom (version 26.02.06) and firefly-bom (version 1.0.0-SNAPSHOT)
• OpenAPI conventions: Properties base.package, openapi.base.package, openapi.model.package, openapi.api.package
• OpenAPI generation profile (generate-openapi): always active unless -DskipOpenApiGen. Uses spring-boot-maven-plugin to start/stop a lightweight OpenApiGenApplication, then springdoc-openapi-maven-plugin to fetch the spec from http://localhost:18080/v3/api-docs.yaml and write it to target/openapi/openapi.yml
• Skip-by-default control: openapi.gen.skip=true by default; only -web modules set it to false

Service-level POM pattern

<parent>
    <groupId>com.firefly</groupId>
    <artifactId>firefly-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <relativePath/>
</parent>

<artifactId>core-common-customer-mgmt</artifactId>
<packaging>pom</packaging>
<modules>
    <module>core-common-customer-mgmt-core</module>
    <module>core-common-customer-mgmt-interfaces</module>
    <module>core-common-customer-mgmt-models</module>
    <module>core-common-customer-mgmt-sdk</module>
    <module>core-common-customer-mgmt-web</module>
</modules>

<properties>
    <java.version>25</java.version>
</properties>

All services use Java 25 with maven.compiler.release set accordingly.

4. BOM Usage

firefly-bom (com.firefly:firefly-bom:1.0.0-SNAPSHOT) is a flat POM that manages versions for every artifact in the platform. It is imported automatically by firefly-parent, so individual services never need to import it directly.

What it manages (all at 1.0.0-SNAPSHOT):

• 7 common libraries: library-common-core, library-common-web, library-common-r2dbc, library-common-auth, library-common-eda, library-common-cache, library-common-batch
• 2 domain libraries: library-psps, library-rails
• 3 utility libraries: library-utils, library-commons-validators, library-workflow-engine
• 2 plugin manager libs: library-plugin-manager-core, library-plugin-manager-api
• 5 core-banking service artifacts + 5 matching SDKs
• 11 core-lending service artifacts + 11 matching SDKs
• 15 core-common service artifacts + 15 matching SDKs
• 2 core-data service artifacts + 2 matching SDKs
• 10 domain service artifacts + 10 matching SDKs
• 3 application artifacts + 1 app SDK (bfc-initconfig-sdk)
• 1 flow SDK: firefly-flow-sdk

Version strategy: All artifacts use 1.0.0-SNAPSHOT during development. The BOM ensures no version conflicts across the platform.

When you add a dependency on another Firefly service's SDK, you omit the <version> tag because the BOM manages it:

<dependency>
    <groupId>com.firefly</groupId>
    <artifactId>core-common-customer-mgmt-sdk</artifactId>
    <!-- version managed by firefly-bom via firefly-parent -->
</dependency>

5. Module Structure

Core services (core-banking-*, core-lending-*, core-common-*, core-data-*)

Domain services (domain-*)

Experience services (exp-*)

Note: Experience services consume only domain SDKs, never core SDKs directly. They have -infra for domain SDK client factories.

Application services (app-*)

Note: App services typically do not have -models or -sdk modules. They also do not have -infra.

6. Inter-Service Communication

Synchronous: SDK Import

Services communicate synchronously by importing another service's -sdk module. The SDK is an auto-generated OpenAPI client using openapi-generator-maven-plugin with the webclient library (reactive).

Concrete example -- domain-customer-people calling core-common-customer-mgmt:

1. The -infra module declares the SDK dependency:

   <dependency>
       <groupId>com.firefly</groupId>
       <artifactId>core-common-customer-mgmt-sdk</artifactId>
   </dependency>
   

2. A @ConfigurationProperties class maps the base URL:

   @ConfigurationProperties(prefix = "api-configuration.common-platform.customer-mgmt")
   public class CustomerMgmtProperties {
       private String basePath;
   }
   

3. A ClientFactory creates API beans:

   @Component
   public class ClientFactory {
       private final ApiClient apiClient;
   
       public ClientFactory(CustomerMgmtProperties props) {
           this.apiClient = new ApiClient();
           this.apiClient.setBasePath(props.getBasePath());
       }
   
       @Bean
       public PartiesApi partiesApi() {
           return new PartiesApi(apiClient);
       }
       // ... more API beans
   }
   

4. application.yaml provides the base path:

   api-configuration:
     common-platform.customer-mgmt:
       base-path: http://localhost:8082
   

5. Environment-specific overrides come from firefly-config:

   # config/dev/application-dev.yaml
   endpoints:
     common:
       core-common-customer-mgmt: https://app-core-common-customer-mgmt.dev.soon.es
   

Asynchronous: Events via Kafka

Domain services use the Firefly EDA (Event-Driven Architecture) library for async communication:

firefly:
  eda:
    enabled: true
    default-publisher-type: KAFKA
    default-connection-id: default
    publishers:
      kafka:
        default:
          default-topic: domain-layer
          bootstrap-servers: localhost:9092

Domain services also enable CQRS and saga support:

firefly:
  cqrs:
    enabled: true
    command:
      timeout: 30s
      metrics-enabled: true
      tracing-enabled: true
    query:
      timeout: 15s
      caching-enabled: true
      cache-ttl: 15m
  saga.performance.enabled: true
  stepevents.enabled: true

7. Layer Rules

+-------------------+
|  channel (web/    |  Browser, Mobile App, API Consumer
|  mobile/API)      |
+-------------------+
         |
         v
+-------------------+       +-------------------+
|  exp-* (BFF per   |       |  app-* (edge/     |
|  user journey)    |       |  gateway/auth)    |
+-------------------+       +-------------------+
         |                           |
         | calls via domain SDK      | calls via domain SDK or routes
         v                           v
+-------------------+
|   domain-* (orch) |  Workflows, Sagas, CQRS Commands/Queries
+-------------------+
         |
         | calls via SDK (sync) or Kafka events (async)
         v
+-------------------+
| core-* (CRUD/biz) |  Entities, Repositories, Business Rules
+-------------------+
         |
         | R2DBC / PostgreSQL
         v
+-------------------+
|    Database        |
+-------------------+

Strict dependency direction -- violations break the architecture:

The -infra module exists ONLY in domain services. It houses SDK client factories and configuration properties that wire up downstream core service connections. Core services do not have an -infra module because they do not call other services.

8. Configuration

Spring Cloud Config Repository (firefly-config)

Centralized configuration lives in firefly-config with the following structure:

firefly-config/
  config/
    dev/
      application.yaml            # Local development defaults
      application-dev.yaml        # Dev environment endpoints for all services
      domain/
        customer-domain-people-dev.yaml
        customer-domain-kyc-kyb-dev.yaml
        lending-domain-loan-origination-dev.yaml
        ...
    pre/
      application-pre.yaml        # Pre-production endpoints
      domain/
        customer-domain-people-pre.yaml
        ...
    pro/
      application-pro.yaml        # Production endpoints
      domain/
        customer-domain-people-pro.yaml
        ...

Environment Profiles

Service-Level Configuration (application.yaml)

Each service's -web module contains an application.yaml with:

• spring.application.name matching the repo name (e.g., core-common-customer-mgmt)
• Database connection via environment variables: DB_HOST, DB_PORT, DB_NAME, DB_SSL_MODE, DB_USERNAME, DB_PASSWORD
• R2DBC connection pool settings
• Flyway migrations from classpath:db/migration
• SpringDoc OpenAPI scanning the controller package
• Actuator endpoints: health, info, prometheus
• Liveness and readiness probes enabled
• Virtual threads enabled (spring.threads.virtual.enabled: true)

Domain services additionally configure firefly.cqrs, firefly.eda, firefly.saga, and api-configuration base paths for downstream SDKs.

Profile-Specific Sections

Services embed multi-profile configuration using Spring's --- document separator:

---
spring:
  config:
    activate:
      on-profile: dev
logging:
  level:
    com.firefly: DEBUG

---
spring:
  config:
    activate:
      on-profile: prod
logging:
  level:
    com.firefly: INFO
springdoc:
  api-docs.enabled: false
  swagger-ui.enabled: false

9. API Contract Conventions

OpenAPI Spec Ownership

Each service owns its OpenAPI spec. The spec is auto-generated at build time from the -web module's annotated controllers:

1. The -web module sets openapi.gen.skip=false and openapi.gen.mainClass to a lightweight Spring Boot application:

   <properties>
       <openapi.gen.skip>false</openapi.gen.skip>
       <openapi.gen.mainClass>com.firefly.core.customer.web.openapi.OpenApiGenApplication</openapi.gen.mainClass>
   </properties>
   

2. During integration-test phase, spring-boot-maven-plugin starts the app on port 18080, springdoc-openapi-maven-plugin fetches the spec from /v3/api-docs.yaml, and writes it to target/openapi/openapi.yml.

SDK Generation

The -sdk module uses openapi-generator-maven-plugin (v7.0.1) to generate a Java client from the spec:

<configuration>
    <inputSpec>${project.parent.basedir}/${project.parent.artifactId}-web/target/openapi/openapi.yml</inputSpec>
    <generatorName>java</generatorName>
    <library>webclient</library>
    <apiPackage>com.firefly.core.customer.sdk.api</apiPackage>
    <modelPackage>com.firefly.core.customer.sdk.model</modelPackage>
    <invokerPackage>com.firefly.core.customer.sdk.invoker</invokerPackage>
    <configOptions>
        <reactive>true</reactive>
        <returnResponse>true</returnResponse>
        <useTags>true</useTags>
        <dateLibrary>java8-localdatetime</dateLibrary>
    </configOptions>
</configuration>

How Consumers Import SDKs

Consumers add the SDK as a Maven dependency (version managed by the BOM) and create API beans through a ClientFactory in their -infra module. See section 6 for the full pattern.

REST API Conventions

Controllers observed in the codebase follow these patterns:

• Base path: /api/v1/{resource}
• Fully reactive: all endpoints return Mono<ResponseEntity<T>>
• @Tag annotation on every controller for OpenAPI grouping
• @Operation annotation on every endpoint with summary and description
• @Valid on request bodies
• UUID-based resource identifiers
• Sub-resources under parent: /api/v1/customers/{partyId}/addresses/{addressId}
• Swagger UI at /swagger-ui.html, API docs at /v3/api-docs
• Packages scanned via springdoc.packages-to-scan
• Paths filtered via springdoc.paths-to-match: /api/**

10. Quick Reference

11. SDK Model DTO Patterns

Generated SDK model DTOs (from openapi-generator-maven-plugin) have patterns that differ from hand-written DTOs:

Read-Only ID Fields

ID fields (dateCreated, dateUpdated, and the entity ID) are read-only -- set only via the constructor:

// CORRECT -- set ID via constructor
KycVerificationDTO dto = new KycVerificationDTO(null, null, UUID.randomUUID());

// WRONG -- setter does not exist for ID fields
KycVerificationDTO dto = new KycVerificationDTO();
dto.setKycVerificationId(UUID.randomUUID());  // Compilation error

Fluent Setters for Mutable Fields

Mutable fields use fluent setters (return this):

SendNotificationCommand command = new SendNotificationCommand()
    .partyId(partyId)
    .notificationType(SendNotificationCommand.NotificationTypeEnum.WELCOME)
    .channels(List.of(SendNotificationCommand.ChannelsEnum.EMAIL));

Inline Enums

Enum fields generate inner enum classes within the DTO:

// NOT a standalone enum -- it is an inner class of the DTO
SendNotificationCommand.NotificationTypeEnum.WELCOME
SendNotificationCommand.PriorityEnum.NORMAL

Getter Naming

Getters use the full field name from the OpenAPI spec:

• getKycVerificationId() (NOT getId())
• getVerificationDocumentId() (NOT getDocumentId())
• getComplianceCaseId() (NOT getCaseId())

12. Module Dependency Rules

-web MUST depend on -core

When controllers reference service interfaces, commands, or any types from -core, the -web module must declare the dependency:

<!-- {service}-web/pom.xml -->
<dependency>
    <groupId>com.firefly</groupId>
    <artifactId>{service}-core</artifactId>
</dependency>

-interfaces MUST NOT depend on -core

This creates an inverted/circular dependency. Correct direction:

-core → -interfaces (core uses DTOs from interfaces)
-web  → -core       (web uses services from core)
-web  → -interfaces (web uses DTOs from interfaces)

NotImplementedException Requires fireflyframework-web

If a -core module needs NotImplementedException (from org.fireflyframework.web.error.exceptions), it must add fireflyframework-web as a dependency. The starters fireflyframework-starter-core and fireflyframework-starter-domain do NOT include it transitively.

StepStatus Enum Values

The StepStatus enum has values: PENDING, RUNNING, DONE, FAILED, SKIPPED, TIMED_OUT, RETRYING. StepStatus.COMPLETED does not exist -- use StepStatus.DONE.

13. ClientFactory Conventions

In domain services, the -infra module wires SDK clients using ClientFactory beans:

// CORRECT -- @Component, not @Configuration
@Component
public class KycbClientFactory {
    private final ApiClient apiClient;

    public KycbClientFactory(KycbMgmtProperties props) {
        this.apiClient = new ApiClient();
        this.apiClient.setBasePath(props.getBasePath());
    }

    @Bean
    public KycVerificationApi kycVerificationApi() {
        return new KycVerificationApi(apiClient);
    }
}

Key conventions:

• Use @Component (not @Configuration) -- this is a banking platform convention
• Use @ConfigurationProperties without @Configuration on the properties class (when @ConfigurationPropertiesScan is on the application class)
• One ClientFactory per downstream service
• One @Bean method per API class from the SDK

14. Cross-Layer Reflexive Property

When generating code for an upper-layer service (domain/app) that calls a lower-layer service (core), if the lower-layer method does not exist, you MUST create it:

1. Create the endpoint in the core service's -web controller
2. Create the service interface and implementation in -core
3. Rebuild the core service's SDK
4. Then implement the upper-layer call

Never leave upper-layer methods returning static/mock data or empty results. If the core service is not yet available, define a port interface with a stub adapter that throws NotImplementedException.

15. Javadoc and README Documentation Standards

Javadoc

All public classes and methods must include Javadoc:

/**
 * Orchestrates KYC verification lifecycle including identity checks,
 * document collection, and compliance case management.
 */
@Service
public class KycServiceImpl implements KycService {

    /**
     * Initiates identity verification for the given compliance case.
     *
     * @param caseId the compliance case identifier
     * @return a {@link SagaResult} with verification outcome
     */
    public Mono<SagaResult> verify(UUID caseId) { ... }
}

README.md

Every microservice MUST have a README.md at the project root with:

1. Service description -- purpose and role in the platform
2. Architecture -- tier, dependencies, how it fits in the broader platform
3. Module structure -- table of modules and their purposes
4. API reference -- main endpoints with HTTP method, path, and description
5. Configuration -- required environment variables and properties
6. Getting started -- build and run instructions
7. Dependencies -- upstream (calls) and downstream (called by) services

16. PII Logging Rules

Never log personally identifiable information. Use resource identifiers instead:

// WRONG
log.info("Processing customer: name={}, email={}", name, email);

// CORRECT
log.info("Processing customer: partyId={}", partyId);

17. Quick Reference