How mizentui/fractal-flame works
1. Top-level architecture
- This repository is a small distributed system with two Spring Boot services: gateway and generator.
- The gateway is the public-facing HTTP entrypoint; the generator is the internal service that owns fractal generation, persistence, and image storage.
2. Request path
- A client calls the gateway on port 8080.
- The gateway validates/authenticates the request and forwards domain operations to the generator over gRPC.
- The generator performs the actual work, then returns data back to the gateway for response shaping.
3. Gateway service boundary
- gateway contains REST controllers for fractals and images, plus service and mapper layers.
- It has openapi.yaml, which indicates the external HTTP API is contract-driven.
- The gateway is primarily an orchestration and translation layer: request/response mapping, auth enforcement, and gRPC client integration.
4. Generator service boundary
- generator is the core domain service.
- It contains the business entities, repositories, generation logic, and storage integration.
- This service is responsible for producing fractal images and managing the underlying data model.
5. Domain model
- The main domain concepts are Fractal, Function, AffineParams, Image, Task, and User.
- The presence of multiple function implementations such as Linear, Sinusoidal, Swirl, Polar, Heart, Disc, etc. shows the generator builds images from composable mathematical transforms.
- The gateway mirrors these concepts with mapper classes to convert between API DTOs and generator-facing/protocol types.
6. Generation pipeline
- The generator includes GeneratationService, Render, Generator, GenerationTask, and ImageWriter.
- That suggests a pipeline of: load fractal configuration → build function set → compute pixels/points → render image → write output to storage.
- The code is organized so the computational path is isolated from transport and persistence concerns.
7. Persistence layer
- The generator uses repositories for fractal definitions, affine params, and functions.
- It also ships Liquibase changelogs under src/main/resources/db/changelog, which means schema management is versioned and applied at startup/deploy time.
- This is the authoritative data store for generation metadata and related entities.
8. Object storage
- The generator has a dedicated S3/MinIO integration via S3ClientConfig, S3ClientProperties, and StorageService.
- The README’s port mapping confirms MinIO runs alongside the app on 9000/9001.
- This indicates generated image blobs are stored separately from the relational metadata.
9. Authentication and security
- Both services include JWT-related components: gateway has JwtAuthFilter and generator has JwtAuthInterceptor.
- Each service also has a security configuration class, so auth is enforced at both the public edge and the internal service boundary.
- A shared JwtService exists in both modules, which implies token validation/claims handling is central to request authorization.
10. Inter-service contract
- gateway/src/main/proto/generator.proto and generator/src/main/proto/generator.proto define the gRPC API between the two services.
- The gateway uses a gRPC configuration class, while the generator hosts the server-side gRPC handling and a global gRPC exception handler.
- This is the key architectural boundary: HTTP at the edge, gRPC between services.
11. Error handling
- Both services define centralized error translation layers: GlobalExceptionHandler in the gateway and GlobalGrpcExceptionHandler in the generator.
- The generator also defines rich domain exceptions such as FractalParametersException, TaskNotFoundException, ImageException, and BlobNotFoundException.
- This suggests the system treats validation, storage, and generation failures as first-class domain errors.
12. Build and deployment
- Each service is a standalone Gradle/Spring Boot application with its own Dockerfile.
- compose.yaml and the README show the intended deployment is containerized with:
- gateway on 8080
- generator on 9090
- PostgreSQL on 5432
- MinIO on 9000/9001
- The repo is designed to be run locally or in containers with all dependencies bundled.
13. Testing and support tooling
- The generator has broader test support, including Testcontainers, indicating integration tests against real dependencies.
- The root-level CI file and per-service Gradle wrappers show the project is set up for automated build/test pipelines.
- Logging is explicitly configured in the generator with logback.xml.
14. How to draw the diagram
- Model the system as:
- Client → Gateway (HTTP/OpenAPI, JWT) → Generator (gRPC, JWT) → PostgreSQL + MinIO
- Put the gateway outside the core domain as an API/auth adapter.
- Put the generator at the center of the domain, with separate arrows to relational storage and object storage.
Main entry points: GeneratationService.java Generation Pipeline · FractalsRepository.java Repositories · FractalsController.java Controllers · FractalsService.java Gateway Service
Components 19
Edge API
Public HTTP entrypoint and request translation
- Client · External HTTP consumer
- gRPC Contract · Shared service interface between gateway and generator
gateway/src/main/proto/generator.proto
Gateway
HTTP adapter and orchestration layer
- HTTP API · Contract-driven public API surface
gateway/openapi.yaml - JWT Filter · Edge authentication and request filtering
gateway/src/main/java/com/fractalflame/gateway/filter/JwtAuthFilter.java - Controllers · Fractals and images endpoints
gateway/src/main/java/com/fractalflame/gateway/controller/FractalsController.java - Mappers · API-to-protocol and response shaping
gateway/src/main/java/com/fractalflame/gateway/mapper/FractalMapper.java - Gateway Service · Gateway-side coordination and gRPC client calls
gateway/src/main/java/com/fractalflame/gateway/service/FractalsService.java - gRPC Client · Client stub and inter-service transport
gateway/src/main/java/com/fractalflame/gateway/configuration/GrpcConfiguration.java - Error Handler · Central HTTP error translation
gateway/src/main/java/com/fractalflame/gateway/advice/GlobalExceptionHandler.java
Generator
Core fractal generation service
- JWT Interceptor · Internal auth enforcement on gRPC boundary
generator/src/main/java/com/fractalflame/generator/interceptor/JwtAuthInterceptor.java - Domain Model · Fractal, function, affine params, and user model
generator/src/main/java/com/fractalflame/generator/entity/Fractal.java - Function Models · Composable fractal transform implementations
generator/src/main/java/com/fractalflame/generator/model/functions/LinearFunction.java - Generation Pipeline · Load config, build transforms, render output
generator/src/main/java/com/fractalflame/generator/service/GeneratationService.java - Render Engine · Pixel computation and image writing
generator/src/main/java/com/fractalflame/generator/utils/Render.java - Storage Service · S3/MinIO blob persistence for generated images
generator/src/main/java/com/fractalflame/generator/service/StorageService.java - Repositories · Relational persistence for fractal metadata
generator/src/main/java/com/fractalflame/generator/repository/FractalsRepository.java - Schema Changelog · Versioned database schema management
generator/src/main/resources/db/changelog/master.yaml
Infra
External runtime dependencies and deployment
- PostgreSQL · Authoritative metadata store
- MinIO · Blob store for generated images
Connections 19
- Client → HTTP API: HTTP · Public API entrypoint
- HTTP API → JWT Filter: auth · Validates and filters requests
- JWT Filter → Controllers: dispatch · Authorized requests reach controllers
- Controllers → Mappers: map · Transforms API payloads to internal types
- Mappers → Gateway Service: invoke · Orchestrates domain operations
- Gateway Service → gRPC Client: rpc · Calls generator over gRPC
- gRPC Client → gRPC Contract: uses · Client-side contract binding
- gRPC Contract → JWT Interceptor: proto · Shared service boundary
- JWT Interceptor → Generation Pipeline: forward · Authenticated internal requests reach service logic
- Generation Pipeline → Domain Model: load · Reads fractal and task data
- Generation Pipeline → Function Models: build · Constructs transform set
- Function Models → Render Engine: compute · Transforms feed rendering math
- Render Engine → Storage Service: write · Persists generated image blobs
- Generation Pipeline → Repositories: read/write · Uses repositories for generation metadata
- Repositories → Schema Changelog: migrated by · Schema managed through changelogs
- Repositories → PostgreSQL: sql · Relational persistence backend
- Storage Service → MinIO: s3 · Object storage backend
- Generation Pipeline → Gateway Service: result · Generated data returned for response shaping
- Error Handler → Controllers: translate · Converts domain failures to HTTP responses