Docs Blog CLI Map AI Contribute Enterprise Start →
Past Event / Introduction to Microservices & FractalX Framework — SLIIT Dev Conf 2026
Apr 4, 2026  •  1:30 PM View Recap →
Static decomposition — build-time, not runtime

Monolith to
Microservices.
One Command.

FractalX reads your Spring Boot source tree, finds module boundaries from annotations, and generates a fully operational microservice platform — with gRPC communication, observability, service discovery, and Docker deployment included.

fractalx — zsh
$ mvn fractalx:decompose
[INFO] FractalX 0.4.1 — starting decomposition
Parsing 52 source files          Phase 1 ██████████ 100%
Analysing dependencies          Phase 2 ██████████ 100%
Generating 9 microservices       Generate ██████████ 100%
[INFO] BUILD SUCCESS — 9 services — 1.48s
$ ./fractalx-output/start-all.sh
Starting fractalx-registry       :8761  ✓
Starting domain services         :8081–8089 ✓
All services healthy — Admin at http://localhost:9090
30+
Code generators
<2s
Decomposition time
554
Automated tests
0
Runtime agents

Three steps from monolith to platform

FractalX is a build-time tool. It reads source files, never runs them. No agent, no bytecode manipulation, no framework lock-in.

01
🆕
Annotate boundaries
Add one @DecomposableModule per bounded context. Declare cross-module dependencies as fields — or let FractalX detect them from imports automatically.
@DecomposableModule(
  serviceName = "order-service",
  port = 8081
)
public class OrderModule {
  private PaymentService paymentService;
}
02
Run decomposition
FractalX performs two-phase AST analysis: parse all source files into an in-memory AST, then map each module to its package prefix and extract cross-module call graphs.
# One command does everything
mvn fractalx:decompose

# Or use the interactive TUI
mvn fractalx:menu
03
🚀
Deploy
A complete docker-compose.yml is generated alongside each service. Start everything with one command — services, gateway, registry, admin, and Jaeger all included.
# Docker Compose
docker compose up --build

# Or locally
./fractalx-output/start-all.sh

Bootstrap a project in seconds

The FractalX CLI generates a Spring Boot modular monolith — pre-annotated and ready to decompose — from an interactive wizard or a fractalx.yaml spec. No browser required.

Homebrew
macOS & Linux
brew install fractalx-org/tap/fractalx-cli
Installs the fractalx binary via Homebrew. Updates automatically with brew upgrade.
curl
macOS & Linux
curl -fsSL …/install.sh | sh
Detects your OS and arch, downloads the right binary from GitHub Releases, and places it in /usr/local/bin.
Go install
Any platform
go install github.com/fractalx-org/fractalx-cli@latest
Requires Go 1.21+. Installs the latest release directly from source. Works on Windows too.
After install, run fractalx to launch the wizard  ·  Full CLI docs →

Everything from three annotations

Your domain code stays untouched. FractalX generates all inter-service wiring, resilience, and observability code alongside your business logic.

Your monolith — before
input
// One annotation per module. That is it.
@DecomposableModule(
  serviceName = "order-service",
  port = 8081,
  ownedSchemas = {"orders"}
)
public class OrderModule {
  private PaymentService paymentService;
}

// Saga orchestration from one annotation
@DistributedSaga(
  sagaId = "checkout",
  compensation = "cancelCheckout"
)
public void processCheckout(Long orderId) {
  paymentService.charge(orderId);
  inventoryService.reserve(orderId);
}

// Mark methods explicitly if needed
@ServiceBoundary
public boolean isConfirmed(Long id) {
  return repo.existsById(id);
}
Generated — after decompose
output
// order-service/PaymentServiceClient.java
@NetScopeClient(
  server = "payment-service",
  beanName = "paymentService"
)
public interface PaymentServiceClient {
  boolean charge(Long orderId);
}

// order-service/OtelConfig.java
public class OtelConfig {
  // OTLP/gRPC -> Jaeger, W3C traceparent
  // BatchSpanProcessor, auto service.name
}

// fractalx-saga-orchestrator/
// CheckoutSagaService.java
// SagaInstance.java (JPA entity)
// POST /saga/checkout/start
// GET  /saga/status/{correlationId}

// payment-service/OrderService.java
@NetworkPublic // added automatically
public boolean isConfirmed(Long id) {
  return repo.existsById(id);
}

Everything a production platform needs

Every non-functional requirement is generated automatically. No boilerplate to write, no configuration to copy-paste.

🔗
NetScope — gRPC inter-service
Auto-generated @NetScopeClient interfaces replace Feign. Strongly typed, resilience-wrapped, with dynamic host resolution from the registry. gRPC port = HTTP + 10,000.
grpc · type-safe · zero-config
🔭
OpenTelemetry + Jaeger tracing
OtelConfig.java generated per service. OTLP/gRPC export to Jaeger. W3C traceparent propagates through HTTP and gRPC calls. X-Correlation-Id ties logs to traces end-to-end.
otel · jaeger · w3c traceparent
🛡
Resilience4j per dependency
CircuitBreaker, Retry, and TimeLimiter configured per cross-module dependency. 50% failure threshold, 3 retries with exponential backoff, 2s call timeout — all configurable.
circuit breaker · retry · timeout
🏠
Service registry & gateway
Lightweight fractalx-registry (no Eureka dependency). Spring Cloud Gateway with dynamic routing, rate limiting (token-bucket, no Redis), CORS, JWT/OAuth2/API-key auth — all disabled by default.
registry · gateway · rate-limit
📊
Admin dashboard — 14 sections
Full-stack ops dashboard generated at port 9090. Topology graph, API Explorer, gRPC browser, alert rules (SSE + Webhook + Slack + Email), incident tracker, live config diff and override.
dashboard · alerts · incidents
🗃
Data isolation & sagas
Per-service datasource, scoped @EntityScan, Flyway scaffold, transactional outbox, and ReferenceValidator replacing cross-service FKs. @DistributedSaga generates a full orchestrator service.
flyway · outbox · saga
🚧
Docker-ready from day one
Multi-stage Dockerfile per service. docker-compose.yml for the entire platform including Jaeger. Three Spring profiles: base / dev / docker. All env vars pre-wired for container DNS.
docker · compose · multi-stage
Static verification
6-level verifier: structural checks, NetScope compatibility, port conflicts, SQL schema validity, circular dependency detection, secret scanning, and optional compile + Spring context smoke tests.
verify · analysis ·6 levels
📈
Health metrics & Prometheus
ServiceHealthConfig.java per service: TCP HealthIndicator per gRPC dependency, Micrometer gauge fractalx.service.dependency.up. All services expose /actuator/prometheus for scraping.
micrometer · prometheus · health

A full platform, not just source files

For a monolith with N annotated modules, FractalX generates N independent Spring Boot services plus four shared infrastructure services.

📦
your-service-1
:8081  gRPC :18081
One per @DecomposableModule. Copied + transformed source, NetScope client, OtelConfig, Resilience4j config
📦
your-service-2
:8082  gRPC :18082
Own datasource, Flyway migration scaffold, outbox publisher, ReferenceValidator
🏭
fractalx-registry
:8761
Lightweight REST service registry. Self-registration, heartbeat, eviction. Starts first.
🌐
fractalx-gateway
:9999
Spring Cloud Gateway. Dynamic routing, rate limiting, circuit breaker, CORS, tracing filters
📄
logger-service
:9099
Centralized structured log ingestion. Paginated search by correlationId, service, level
🛠
admin-service
:9090
14-section ops dashboard. Topology, alerts (4 channels), traces, API explorer, incident tracker
🎉
saga-orchestrator
:8099  (conditional)
Generated only when @DistributedSaga is detected. Forward + compensation steps, SagaInstance JPA
📋
docker-compose.yml
all services + Jaeger
Complete multi-container setup. OTEL env vars pre-wired. Service DNS names. start-all.sh included

Why not just do it manually?

A manual migration involves weeks of repetitive scaffolding. FractalX generates it all correctly and consistently in under two seconds.

Concern Manual migration With FractalX
Service scaffolding Days per service — pom.xml, main class, config profiles Generated in milliseconds per service
Inter-service communication Write Feign clients or gRPC stubs manually @NetScopeClient interfaces auto-generated
Distributed tracing Add OTel dependency + configure each service OtelConfig.java generated per service
Circuit breaking & retry Configure Resilience4j per service per dependency Auto-generated per cross-module call
Service discovery Set up Eureka or Consul, configure all clients fractalx-registry generated + all registration code
Database isolation Split schemas, rewire JPA, handle FK integrity DataIsolationGenerator + ReferenceValidator
Saga orchestration Design and build orchestrator service from scratch Full service from @DistributedSaga annotation
Container deployment Write Dockerfiles, docker-compose, env vars Multi-stage Dockerfiles + compose generated
Admin & observability Build dashboards, alert rules, topology views 14-section dashboard auto-generated

Principles that guide every decision

FractalX is opinionated where it saves you time and stays out of the way everywhere else.

Annotation-minimal
One @DecomposableModule per module is the entire developer contract. Cross-module dependencies are detected automatically from imports and field types.
Zero-intrusion
FractalX never modifies your monolith source tree. It reads source files and writes all generated code to a separate output directory. Your original codebase is never touched.
Safe-by-default
When FractalX cannot determine whether a class belongs to a module, it copies it to every service that imports it. Unknown code is never silently dropped.
Incremental
Re-running mvn fractalx:decompose replaces the output directory cleanly. Iterate on module boundaries without side effects.
Observable from day one
Every generated service ships with distributed tracing, health metrics, Prometheus endpoint, correlation ID propagation, and log shipping — no developer action required.
Extensible by design
Implement the ServiceFileGenerator interface and register it in the pipeline. Each step receives a full GenerationContext with no coupling to existing steps.

Validated across three real POC systems

FractalX was evaluated against three purpose-built Spring Boot systems ranging from 4 to 9 modules, demonstrating consistent decomposition correctness and sub-second generation across all scales.

Small system
E-Commerce
Modules4
Source files22
Cross-module deps3
LOC999
Decomposition time0.61 s
Generated services8
Dependency pruningavg 8.5 / 14
Medium system
HR System
Modules6
Source files38
Cross-module deps5
LOC1 420
Decomposition time0.92 s
Generated services10
Dependency pruningavg 7.8 / 14
Large system
University System
Modules9
Source files52
Cross-module deps12
LOC2 097
Decomposition time1.48 s
Generated services13
Dependency pruningavg 6.9 / 14
📚
Full analysis including dependency pruning charts, code amplification ratios, and cross-module dependency graphs is available in the Evaluation Report (PDF, 21 pages).

Start decomposing
your monolith today

Add two XML blocks to your pom.xml, annotate your module boundaries, and run one command. The entire platform is waiting in fractalx-output/.

Apache 2.0  ·  No telemetry  ·  Runs locally