Skip to content

Jafly. Starter Application

Starter Application

Build application-layer request contexts and business process coordination.

Use the application context/resolver and orchestration facilities to connect authenticated requests to domain operations. Inspect the context and security tests before customizing header or session interpretation.

Maven artifact Packaging Source project
org.fireflyframework:fireflyframework-starter-application jar modules/starter-application

Part of Team-wide architecture.

In the onboarding service

An application-tier onboarding API can use these request/context conventions while coordinating domain services. Populate tenant and identity values only from the service's trusted authentication boundary.

Add the component

Installation and version availability explains source builds and published releases.

<dependency>
    <groupId>org.fireflyframework</groupId>
    <artifactId>fireflyframework-starter-application</artifactId>
    <version>26.10.20-SNAPSHOT</version>
</dependency>

Quick start

The Java examples in this section are API fragments for application code. Use the stated imports and supply the application-owned collaborators described alongside them.

import org.fireflyframework.common.application.controller.AbstractApplicationController;
import org.fireflyframework.common.application.security.annotation.Secure;

@RestController
@RequestMapping("/api/accounts")
public class AccountController extends AbstractApplicationController {

    @Secure(roles = {"ADMIN", "ACCOUNT_MANAGER"})
    @PostMapping
    public Mono<AccountResponse> create(@RequestBody AccountRequest request) {
        return accountService.create(request);
    }
}

Configuration and wiring

The firefly.application namespace is bound by ApplicationLayerProperties.java. Nested configuration is declared in the linked class. Defaults are the field initializers.

Setting Java type Source default
firefly.application.security Security new Security()
firefly.application.context Context new Context()
firefly.application.config Config new Config()

Property-based wiring conditions found in this module:

Public API and extension points

Type Contract and responsibility
AbstractApplicationController Abstract Base Controller for Application-Layer Endpoints This base class is for controllers that operate on application-level resources .
ApplicationLayerProperties Configuration properties for the Application Layer.
AbstractResourceController Abstract Base Controller for Resource Endpoints This base class is a thin, product-agnostic foundation for REST controllers.
ConfigResolver Interface for resolving tenant configuration.
ContextResolver Resolves the product-agnostic AppContext for a request from the validated security context.
Related component Why it belongs nearby
Security Resource Server Validate signed JWT bearer tokens in a reactive resource server with hardened default security behavior.
Security Method Policy Enable reactive method authorization through Secure and the core authorization evaluator.
Observability Provide a common metrics, tracing, health, and context-propagation foundation for framework components.
Kernel Share a consistent exception vocabulary across application, domain, and infrastructure boundaries.
Common Client Library Call REST, SOAP, and gRPC services through reactive client builders with shared resilience and observability facilities.
Common Cache Library Use a common cache API with a local Caffeine default and pluggable distributed providers.
Common CQRS Library Separate commands and queries with reactive dispatch, execution context, validation, and authorization hooks.
Common EDA Library Publish and consume events through a common envelope and transport-independent APIs.
: Orchestration Coordinate workflows, compensating sagas, and try-confirm-cancel operations in a reactive application.

Build and test

Use Java 25. From the repository root, build this component with its required dependencies:

git clone https://github.com/fireflyframework/fireflyframework-jafly.git
cd fireflyframework-jafly
./mvnw -pl :fireflyframework-starter-application -am verify
./mvnw -pl :fireflyframework-starter-application -am install

verify runs the selected projects' tests. install makes the current build available in your local Maven repository.

Representative test sources:

Test fixture

The shouldCreateProviderConfigWithBuilder test demonstrates one concrete behavior. Excerpt from AppConfigTest.java. The test class supplies its fixtures and imports.

@Test
@DisplayName("Should create ProviderConfig with builder")
void shouldCreateProviderConfigWithBuilder() {
    Map<String, Object> properties = Map.of("apiKey", "secret123", "timeout", 5000);

    ProviderConfig config = ProviderConfig.builder()
        .providerType("PAYMENT_GATEWAY")
        .implementation("stripe")
        .properties(properties)
        .enabled(true)
        .priority(10)
        .build();

    assertEquals("PAYMENT_GATEWAY", config.getProviderType());
    assertEquals("stripe", config.getImplementation());
    assertTrue(config.isEnabled());
    assertEquals(10, config.getPriority());
}

Detailed reference

Configuration

firefly:
  application:
    security:
      enabled: true
    config-cache:
      enabled: true
      ttl: 5m
    domain-passthrough:
      enabled: true

Continue the application

Use the Security Resource Server guide for the next part of this integration. The runnable submission/query service is in Getting started.

Source and further reading