Domain — FractalX Project

Literature Survey

Background & Prior Work

Existing research in microservices decomposition and automated tooling.

Microservices Architecture

Lewis and Fowler (2014) established the foundational principles of microservices — small, independently deployable services each owning their data. While widely adopted, the migration path from monolith remains manual and costly.

Static Code Analysis

AST-based program analysis (Eclipse JDT, JavaParser) enables tooling to reason about module structure, dependencies, and boundaries without executing code. This forms the core of FractalX's decomposition engine.

Service Decomposition Strategies

Decomposition-by-business-capability and decomposition-by-subdomain (DDD) are the two dominant strategies. Prior tools such as Mono2Micro and ServiceCutter focus on runtime data; FractalX uses annotation-driven static decomposition.

Distributed Sagas

Garcia-Molina and Salem (1987) introduced sagas for long-lived transactions. The choreography vs. orchestration debate is well-documented; FractalX adopts orchestration via an auto-generated saga orchestrator.

gRPC & Inter-Service Communication

HTTP/REST remains the default, but gRPC (Google, 2016) offers superior type safety, performance, and bidirectional streaming. FractalX generates gRPC stubs (NetScope) for all cross-module calls.

Code Generation & Templates

Template-based code generation (FreeMarker, Mustache, JavaPoet) powers frameworks like Spring Initializr. FractalX extends this to full microservice scaffolding, treating generation as a first-class concern.

Research Gap

What Was Missing

Despite extensive research on microservices patterns and decomposition strategies, no existing tool provides fully automated, annotation-driven, static decomposition for Java Spring Boot applications that generates a complete, deployment-ready microservice platform from a single command.

Tool / Approach	Decomposition Method	Code Generation	Infrastructure Gen.	Saga Support
Mono2Micro (IBM)	Runtime call graph analysis	Partial	No	No
ServiceCutter	Domain model + heuristics	No	No	No
Strangler Fig (manual)	Incremental, manual	No	No	No
Spring Initializr	Project scaffolding only	Scaffold	No	No
FractalX	Static AST + annotations	Full	Full	Full

Research Problem

The Problem Statement

RESEARCH PROBLEM

"How can a static, annotation-driven decomposition framework automatically transform a modular Spring Boot monolith into a fully operational, production-ready microservice platform — including inter-service communication, data isolation, distributed transaction management, observability, and Docker infrastructure — from a single build command, without requiring runtime profiling or manual architectural decisions?"

Challenge 1 — Module Detection

Reliably identifying module boundaries in a codebase through AST traversal and annotation parsing, without false positives.

Challenge 2 — Dependency Resolution

Resolving cross-module dependencies and generating the correct gRPC stubs and client wiring for each produced service.

Challenge 3 — Data Isolation

Splitting a shared database schema into per-service schemas, generating Flyway migrations and removing JPA cross-module relationships.

Challenge 4 — Distributed Consistency

Automatically detecting saga patterns and generating a fully functional orchestrator service with compensation logic from source annotations.

Research Objectives

Project Objectives

Design and implement a static annotation-driven decomposition framework for Spring Boot

Objective 01

Build a Maven plugin that reads source code via AST analysis, resolves @DecomposableModule boundaries, and drives the entire generation pipeline.

Automate inter-service communication via a type-safe gRPC fabric (NetScope)

Objective 02

Generate @NetScopeClient interfaces and the corresponding gRPC stubs, eliminating hand-written Protobuf definitions and service stubs.

Generate per-service data isolation with automated Flyway migration scaffolding

Objective 03

Partition shared database schemas into isolated per-service schemas, generate migration scripts, and enforce no-cross-module JPA relationships.

Implement distributed saga orchestration from source-level annotations

Objective 04

Detect @DistributedSaga methods, generate a full saga orchestrator with compensation methods, rollback logic, and a transactional outbox.

Auto-inject observability, resilience, and admin infrastructure

Objective 05

Auto-generate OpenTelemetry tracing, Resilience4j circuit breakers, a centralised logger service, and a 15-section admin dashboard for every generated deployment.

Validate through real-world monolith decomposition

Objective 06

Evaluate FractalX against a realistic e-commerce monolith (order, payment, inventory modules) and measure service generation time, correctness, and deployment readiness.

Methodology

How We Built It

The development process follows a build-measure-validate methodology with iterative decomposition pipeline refinement.

PHASE 01

Domain Analysis & Literature Survey

Surveyed existing decomposition tools, identified gaps, and defined the annotation model and generation contract. Established naming conventions and structural rules.

PHASE 02

Framework Core — AST Engine

Built the annotation processor and AST scanner using JavaParser. Implemented module graph construction, dependency resolver, and cross-module reference detection.

PHASE 03

Code Generation Pipeline

Implemented generators for each service type: business services, gateway, registry, admin, saga orchestrator, and logger. Each generator uses template-based output production.

PHASE 04

NetScope gRPC & Saga Generation

Developed NetScope client generation from interface definitions, and the saga orchestrator generator including compensation method binding and outbox pattern integration.

PHASE 05

Validation & Evaluation

Validated against multiple monolith implementations. Measured generation time, service correctness, runtime stability, and developer productivity. Published evaluation report.

PHASE 06

Release & Documentation

Published to Maven Central. Produced developer guide, evaluation report, and project website. Open-sourced under Apache 2.0 license on GitHub.

Technologies Used

Technology Stack

The technologies selected for building and running the FractalX framework.

J21

Java 21+

Primary language, LTS

SB4

Spring Boot 3.2+ / 4.x

Target application framework

MVN

Apache Maven

Build & plugin host

AST

JavaParser

AST analysis engine

gRPC

gRPC / Protobuf

Inter-service communication

OTEL

OpenTelemetry

Distributed tracing

R4J

Resilience4j

Circuit breaker, retry

FLY

Flyway

Database migrations

DCK

Docker / Compose

Container deployment

MCN

Maven Central

Artifact distribution

Project Domain