# mizentui/fractal-flame architecture

> Architecture diagram of the GitHub repository mizentui/fractal-flame, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizentui/fractal-flame
- Repository: https://github.com/mizentui/fractal-flame

## Overview

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: [`generator/src/main/java/com/fractalflame/generator/service/GeneratationService.java`](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/service/GeneratationService.java) (Generation Pipeline), [`generator/src/main/java/com/fractalflame/generator/repository/FractalsRepository.java`](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/repository/FractalsRepository.java) (Repositories), [`gateway/src/main/java/com/fractalflame/gateway/controller/FractalsController.java`](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/controller/FractalsController.java) (Controllers), [`gateway/src/main/java/com/fractalflame/gateway/service/FractalsService.java`](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/service/FractalsService.java) (Gateway Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge API"]
  node_client(("Client<br/>caller"))
  node_contract["gRPC Contract<br/>proto<br/>[generator.proto]"]
end

subgraph group_gateway["Gateway"]
  node_gateway_api["HTTP API<br/>openapi/rest<br/>[openapi.yaml]"]
  node_gateway_auth["JWT Filter<br/>security<br/>[JwtAuthFilter.java]"]
  node_gateway_ctrl["Controllers"]
  node_gateway_map["Mappers<br/>dto mapping<br/>[FractalMapper.java]"]
  node_gateway_service["Gateway Service<br/>orchestration"]
  node_gateway_grpc["gRPC Client"]
  node_gateway_errors["Error Handler<br/>exception mapping"]
end

subgraph group_generator["Generator"]
  node_gen_auth["JWT Interceptor<br/>security"]
  node_gen_domain["Domain Model<br/>entities<br/>[Fractal.java]"]
  node_gen_functions["Function Models<br/>transforms"]
  node_gen_pipeline["Generation Pipeline<br/>compute pipeline"]
  node_gen_render["Render Engine<br/>rendering<br/>[Render.java]"]
  node_gen_storage["Storage Service<br/>object storage"]
  node_gen_repo["Repositories<br/>persistence"]
  node_gen_liquibase["Schema Changelog<br/>db migrations<br/>[master.yaml]"]
end

subgraph group_infra["Infra"]
  node_postgres[("PostgreSQL<br/>relational db")]
  node_minio[("MinIO<br/>object storage")]
end

node_client -->|"HTTP"| node_gateway_api
node_gateway_api -->|"auth"| node_gateway_auth
node_gateway_auth -->|"dispatch"| node_gateway_ctrl
node_gateway_ctrl -->|"map"| node_gateway_map
node_gateway_map -->|"invoke"| node_gateway_service
node_gateway_service -->|"rpc"| node_gateway_grpc
node_gateway_grpc -->|"uses"| node_contract
node_contract -.->|"proto"| node_gen_auth
node_gen_auth -->|"forward"| node_gen_pipeline
node_gen_pipeline -->|"load"| node_gen_domain
node_gen_pipeline -->|"build"| node_gen_functions
node_gen_functions -->|"compute"| node_gen_render
node_gen_render -->|"write"| node_gen_storage
node_gen_pipeline -->|"read/write"| node_gen_repo
node_gen_repo -.->|"migrated by"| node_gen_liquibase
node_gen_repo -->|"sql"| node_postgres
node_gen_storage -->|"s3"| node_minio
node_gen_pipeline -.->|"result"| node_gateway_service
node_gateway_errors -.->|"translate"| node_gateway_ctrl

click node_gateway_api "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/openapi.yaml"
click node_gateway_auth "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/filter/JwtAuthFilter.java"
click node_gateway_ctrl "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/controller/FractalsController.java"
click node_gateway_map "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/mapper/FractalMapper.java"
click node_gateway_service "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/service/FractalsService.java"
click node_gateway_grpc "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/configuration/GrpcConfiguration.java"
click node_gateway_errors "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/advice/GlobalExceptionHandler.java"
click node_contract "https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/proto/generator.proto"
click node_gen_auth "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/interceptor/JwtAuthInterceptor.java"
click node_gen_domain "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/entity/Fractal.java"
click node_gen_functions "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/model/functions/LinearFunction.java"
click node_gen_pipeline "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/service/GeneratationService.java"
click node_gen_render "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/utils/Render.java"
click node_gen_storage "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/service/StorageService.java"
click node_gen_repo "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/repository/FractalsRepository.java"
click node_gen_liquibase "https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/resources/db/changelog/master.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_contract toneBlue
class node_gateway_api,node_gateway_auth,node_gateway_ctrl,node_gateway_map,node_gateway_service,node_gateway_grpc,node_gateway_errors toneAmber
class node_gen_auth,node_gen_domain,node_gen_functions,node_gen_pipeline,node_gen_render,node_gen_storage,node_gen_repo,node_gen_liquibase toneMint
class node_postgres,node_minio toneRose
```

## Components

### Edge API

Public HTTP entrypoint and request translation

- **Client**: caller · External HTTP consumer
- [gRPC Contract](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/proto/generator.proto): proto · Shared service interface between gateway and generator · `gateway/src/main/proto/generator.proto`

### Gateway

HTTP adapter and orchestration layer

- [HTTP API](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/openapi.yaml): openapi/rest · Contract-driven public API surface · `gateway/openapi.yaml`
- [JWT Filter](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/filter/JwtAuthFilter.java): security · Edge authentication and request filtering · `gateway/src/main/java/com/fractalflame/gateway/filter/JwtAuthFilter.java`
- [Controllers](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/controller/FractalsController.java): rest controllers · Fractals and images endpoints · `gateway/src/main/java/com/fractalflame/gateway/controller/FractalsController.java`
- [Mappers](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/mapper/FractalMapper.java): dto mapping · API-to-protocol and response shaping · `gateway/src/main/java/com/fractalflame/gateway/mapper/FractalMapper.java`
- [Gateway Service](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/service/FractalsService.java): orchestration · Gateway-side coordination and gRPC client calls · `gateway/src/main/java/com/fractalflame/gateway/service/FractalsService.java`
- [gRPC Client](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/configuration/GrpcConfiguration.java): rpc client · Client stub and inter-service transport · `gateway/src/main/java/com/fractalflame/gateway/configuration/GrpcConfiguration.java`
- [Error Handler](https://github.com/mizentui/fractal-flame/blob/coursework/gateway/src/main/java/com/fractalflame/gateway/advice/GlobalExceptionHandler.java): exception mapping · Central HTTP error translation · `gateway/src/main/java/com/fractalflame/gateway/advice/GlobalExceptionHandler.java`

### Generator

Core fractal generation service

- [JWT Interceptor](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/interceptor/JwtAuthInterceptor.java): security · Internal auth enforcement on gRPC boundary · `generator/src/main/java/com/fractalflame/generator/interceptor/JwtAuthInterceptor.java`
- [Domain Model](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/entity/Fractal.java): entities · Fractal, function, affine params, and user model · `generator/src/main/java/com/fractalflame/generator/entity/Fractal.java`
- [Function Models](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/model/functions/LinearFunction.java): transforms · Composable fractal transform implementations · `generator/src/main/java/com/fractalflame/generator/model/functions/LinearFunction.java`
- [Generation Pipeline](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/service/GeneratationService.java): compute pipeline · Load config, build transforms, render output · `generator/src/main/java/com/fractalflame/generator/service/GeneratationService.java`
- [Render Engine](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/utils/Render.java): rendering · Pixel computation and image writing · `generator/src/main/java/com/fractalflame/generator/utils/Render.java`
- [Storage Service](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/service/StorageService.java): object storage · S3/MinIO blob persistence for generated images · `generator/src/main/java/com/fractalflame/generator/service/StorageService.java`
- [Repositories](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/java/com/fractalflame/generator/repository/FractalsRepository.java): persistence · Relational persistence for fractal metadata · `generator/src/main/java/com/fractalflame/generator/repository/FractalsRepository.java`
- [Schema Changelog](https://github.com/mizentui/fractal-flame/blob/coursework/generator/src/main/resources/db/changelog/master.yaml): db migrations · Versioned database schema management · `generator/src/main/resources/db/changelog/master.yaml`

### Infra

External runtime dependencies and deployment

- **PostgreSQL**: relational db · Authoritative metadata store
- **MinIO**: object storage · Blob store for generated images

## Connections

- 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
