Opinionated starter for application-layer microservices providing business process orchestration, context management, security, authorization, and session management.

• Overview
• Features
• Requirements
• Installation
• Quick Start
• Configuration
• Documentation
• Contributing
• License

Firefly Framework Starter Application is an opinionated starter for application-layer microservices that orchestrate business processes across domain services. It provides a complete foundation for building application-tier microservices with enterprise-grade context management, security authorization, and session handling.

This starter supplies context management (application config, security context, session context) and security authorization with annotation-driven endpoint protection. It's designed for the application tier in a multi-tier architecture — the orchestration layer that coordinates domain services and implements business workflows.

The starter also includes abstract controllers for standardized REST endpoints, configuration caching, domain passthrough for cross-service data propagation, and SPI-based session management.

• AppContext and AppSecurityContext for application-wide context management
• @Secure and @RequireContext annotations for declarative endpoint security
• SecurityAuthorizationService with configurable endpoint security registry
• Abstract controllers: AbstractApplicationController, AbstractResourceController
• Configuration caching auto-configuration
• Domain passthrough for cross-service data propagation
• Session management SPI with SessionManager and SessionContext
• Application metadata with @FireflyApplication annotation
• Health indicators for application layer
• Actuator info contributor for Firefly application metadata
• Orchestration engine support (Saga, TCC, Workflow) via optional dependency

• Java 21+
• Spring Boot 3.x
• Maven 3.9+

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

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);
    }
}

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

Additional documentation is available in the docs/ directory:

• Architecture
• Usage Guide
• Security Guide
• Security Center Integration
• Api Reference
• Cache Architecture
• Example Microservice Architecture
• Testing

Contributions are welcome. Please read the CONTRIBUTING.md guide for details on our code of conduct, development process, and how to submit pull requests.

Copyright 2024-2026 Firefly Software Foundation.

Licensed under the Apache License, Version 2.0. See LICENSE for details.