# thembatman0/synthforge architecture

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

- Interactive diagram: https://gitdiagram.com/thembatman0/synthforge
- Repository: https://github.com/thembatman0/synthforge
- Video tour (about a minute): https://gitdiagram.com/thembatman0/synthforge/video

## Overview

SynthForge is the repository’s documented product: a Spring Boot library that seeds JPA entities at startup in enabled profiles. The graph also shows RemitFlow, a separate remittance API represented by source files in the tree and sampled order-flow code. SynthForge’s subsystem wiring follows README documentation where available; unsampled implementation details and uncertain links are omitted.

Main entry points: [`synthforge-core/src/main/java/com/themba/synthforge/core/SeedRunner.java`](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/SeedRunner.java) (Seed runner), [`remitflow/src/main/java/com/themba/remitflow/OrderService.java`](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/OrderService.java) (Order workflow), [`synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeAutoConfiguration.java`](https://github.com/thembatman0/synthforge/blob/main/synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeAutoConfiguration.java) (Auto configuration), [`synthforge-core/src/main/java/com/themba/synthforge/core/EntityScanner.java`](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/EntityScanner.java) (Entity scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_synthforge_spring["Spring startup integration"]
  node_autoconfiguration["Auto configuration"]
  node_seed_annotation["@Seed entities<br/>[Seed.java]"]
  node_synth_properties["Seed settings"]
end

subgraph group_synthforge_core["Seed generation core"]
  node_seed_runner["Seed runner<br/>[SeedRunner.java]"]
  node_entity_scanner["Entity scanner<br/>[EntityScanner.java]"]
  node_seed_graph["Dependency ordering<br/>[SeedGraph.java]"]
  node_field_metadata["Field metadata<br/>[FieldMetadata.java]"]
  node_generator_registry["Value generation"]
  node_generation_context["Generation context"]
  node_field_generator["Custom generators"]
end

subgraph group_synthforge_demo["Demo seed entities"]
  node_demo_entities["Demo JPA entities<br/>[Counterparty.java]"]
  node_payment_entity["Payment entity<br/>[Payment.java]"]
end

subgraph group_remitflow_api["RemitFlow API and domain"]
  node_order_controller["Order endpoints"]
  node_order_service["Order workflow<br/>[OrderService.java]"]
  node_counterparty_controller["Counterparty endpoints"]
  node_counterparty_service["Counterparty service"]
  node_corridor_controller["Corridor endpoints"]
  node_corridor_service["Corridor service"]
end

subgraph group_remitflow_data["RemitFlow persistence"]
  node_order_repository["Order repository"]
  node_counterparty_repository["Counterparty repository"]
  node_corridor_repository["Corridor repository"]
end

node_application_start(("Spring app startup"))
node_jpa_database[("Application database")]
node_api_client(("API client"))
node_remitflow_database[("Remittance database")]

node_application_start -->|"starts"| node_autoconfiguration
node_autoconfiguration -->|"reads settings"| node_synth_properties
node_autoconfiguration -->|"configures"| node_seed_runner
node_seed_runner -->|"scans entities"| node_entity_scanner
node_entity_scanner -->|"reads metamodel"| node_jpa_database
node_entity_scanner -->|"provides entities"| node_seed_graph
node_seed_graph -->|"orders entities"| node_seed_runner
node_seed_runner -->|"inspects fields"| node_field_metadata
node_seed_runner -->|"generates values"| node_generator_registry
node_generator_registry -->|"uses state"| node_generation_context
node_generator_registry -->|"checks custom"| node_field_generator
node_seed_runner -->|"persists seeds"| node_jpa_database
node_seed_annotation -->|"marks for seeding"| node_demo_entities
node_demo_entities -->|"referenced by"| node_payment_entity
node_payment_entity -->|"seeded as entity"| node_jpa_database
node_api_client -->|"sends requests"| node_order_controller
node_api_client -->|"sends requests"| node_counterparty_controller
node_api_client -->|"sends requests"| node_corridor_controller
node_order_controller -->|"dispatches"| node_order_service
node_counterparty_controller -->|"dispatches"| node_counterparty_service
node_corridor_controller -->|"dispatches"| node_corridor_service
node_order_service -->|"checks beneficiary"| node_counterparty_repository
node_order_service -->|"loads corridor"| node_corridor_repository
node_order_service -->|"saves and queries"| node_order_repository
node_counterparty_service -->|"reads and saves"| node_counterparty_repository
node_corridor_service -->|"reads and saves"| node_corridor_repository
node_order_repository -->|"persists orders"| node_remitflow_database
node_counterparty_repository -->|"persists counterparties"| node_remitflow_database
node_corridor_repository -->|"persists corridors"| node_remitflow_database

click node_autoconfiguration "https://github.com/thembatman0/synthforge/blob/main/synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeAutoConfiguration.java"
click node_seed_annotation "https://github.com/thembatman0/synthforge/blob/main/synthforge-spring/src/main/java/com/themba/synthforge/spring/Seed.java"
click node_synth_properties "https://github.com/thembatman0/synthforge/blob/main/synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeProperties.java"
click node_seed_runner "https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/SeedRunner.java"
click node_entity_scanner "https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/EntityScanner.java"
click node_seed_graph "https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/SeedGraph.java"
click node_field_metadata "https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/FieldMetadata.java"
click node_generator_registry "https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/GeneratorRegistry.java"
click node_generation_context "https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/GenerationContext.java"
click node_field_generator "https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/FieldGenerator.java"
click node_demo_entities "https://github.com/thembatman0/synthforge/blob/main/synthforge-demo/src/main/java/com/themba/synthforge/demo/Counterparty.java"
click node_payment_entity "https://github.com/thembatman0/synthforge/blob/main/synthforge-demo/src/main/java/com/themba/synthforge/demo/Payment.java"
click node_order_controller "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/OrderController.java"
click node_order_service "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/OrderService.java"
click node_counterparty_controller "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CounterpartyController.java"
click node_counterparty_service "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CounterpartyService.java"
click node_corridor_controller "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CorridorController.java"
click node_corridor_service "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CorridorService.java"
click node_order_repository "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/RemittanceOrderRepository.java"
click node_counterparty_repository "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CounterpartyRepository.java"
click node_corridor_repository "https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CorridorRepository.java"

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_autoconfiguration,node_seed_annotation,node_synth_properties,node_api_client toneBlue
class node_seed_runner,node_entity_scanner,node_seed_graph,node_field_metadata,node_generator_registry,node_generation_context,node_field_generator,node_jpa_database,node_remitflow_database toneAmber
class node_demo_entities,node_payment_entity toneMint
class node_order_controller,node_order_service,node_counterparty_controller,node_counterparty_service,node_corridor_controller,node_corridor_service toneRose
class node_order_repository,node_counterparty_repository,node_corridor_repository,node_application_start toneIndigo
```

## Components

### Spring startup integration

- [Auto configuration](https://github.com/thembatman0/synthforge/blob/main/synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeAutoConfiguration.java): `synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeAutoConfiguration.java`
- [@Seed entities](https://github.com/thembatman0/synthforge/blob/main/synthforge-spring/src/main/java/com/themba/synthforge/spring/Seed.java): `synthforge-spring/src/main/java/com/themba/synthforge/spring/Seed.java`
- [Seed settings](https://github.com/thembatman0/synthforge/blob/main/synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeProperties.java): `synthforge-spring/src/main/java/com/themba/synthforge/spring/SynthforgeProperties.java`

### Seed generation core

- [Seed runner](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/SeedRunner.java): `synthforge-core/src/main/java/com/themba/synthforge/core/SeedRunner.java`
- [Entity scanner](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/EntityScanner.java): `synthforge-core/src/main/java/com/themba/synthforge/core/EntityScanner.java`
- [Dependency ordering](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/SeedGraph.java): `synthforge-core/src/main/java/com/themba/synthforge/core/SeedGraph.java`
- [Field metadata](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/FieldMetadata.java): `synthforge-core/src/main/java/com/themba/synthforge/core/FieldMetadata.java`
- [Value generation](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/GeneratorRegistry.java): `synthforge-core/src/main/java/com/themba/synthforge/core/GeneratorRegistry.java`
- [Generation context](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/GenerationContext.java): `synthforge-core/src/main/java/com/themba/synthforge/core/GenerationContext.java`
- [Custom generators](https://github.com/thembatman0/synthforge/blob/main/synthforge-core/src/main/java/com/themba/synthforge/core/FieldGenerator.java): `synthforge-core/src/main/java/com/themba/synthforge/core/FieldGenerator.java`

### Demo seed entities

- [Demo JPA entities](https://github.com/thembatman0/synthforge/blob/main/synthforge-demo/src/main/java/com/themba/synthforge/demo/Counterparty.java): `synthforge-demo/src/main/java/com/themba/synthforge/demo/Counterparty.java`
- [Payment entity](https://github.com/thembatman0/synthforge/blob/main/synthforge-demo/src/main/java/com/themba/synthforge/demo/Payment.java): `synthforge-demo/src/main/java/com/themba/synthforge/demo/Payment.java`

### RemitFlow API and domain

- [Order endpoints](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/OrderController.java): `remitflow/src/main/java/com/themba/remitflow/OrderController.java`
- [Order workflow](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/OrderService.java): `remitflow/src/main/java/com/themba/remitflow/OrderService.java`
- [Counterparty endpoints](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CounterpartyController.java): `remitflow/src/main/java/com/themba/remitflow/CounterpartyController.java`
- [Counterparty service](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CounterpartyService.java): `remitflow/src/main/java/com/themba/remitflow/CounterpartyService.java`
- [Corridor endpoints](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CorridorController.java): `remitflow/src/main/java/com/themba/remitflow/CorridorController.java`
- [Corridor service](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CorridorService.java): `remitflow/src/main/java/com/themba/remitflow/CorridorService.java`

### RemitFlow persistence

- [Order repository](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/RemittanceOrderRepository.java): `remitflow/src/main/java/com/themba/remitflow/RemittanceOrderRepository.java`
- [Counterparty repository](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CounterpartyRepository.java): `remitflow/src/main/java/com/themba/remitflow/CounterpartyRepository.java`
- [Corridor repository](https://github.com/thembatman0/synthforge/blob/main/remitflow/src/main/java/com/themba/remitflow/CorridorRepository.java): `remitflow/src/main/java/com/themba/remitflow/CorridorRepository.java`

### Other components

- **Spring app startup**
- **Application database**
- **API client**
- **Remittance database**

## Connections

- Spring app startup → Auto configuration: starts
- Auto configuration → Seed settings: reads settings
- Auto configuration → Seed runner: configures
- Seed runner → Entity scanner: scans entities
- Entity scanner → Application database: reads metamodel
- Entity scanner → Dependency ordering: provides entities
- Dependency ordering → Seed runner: orders entities
- Seed runner → Field metadata: inspects fields
- Seed runner → Value generation: generates values
- Value generation → Generation context: uses state
- Value generation → Custom generators: checks custom
- Seed runner → Application database: persists seeds
- @Seed entities → Demo JPA entities: marks for seeding
- Demo JPA entities → Payment entity: referenced by
- Payment entity → Application database: seeded as entity
- API client → Order endpoints: sends requests
- API client → Counterparty endpoints: sends requests
- API client → Corridor endpoints: sends requests
- Order endpoints → Order workflow: dispatches
- Counterparty endpoints → Counterparty service: dispatches
- Corridor endpoints → Corridor service: dispatches
- Order workflow → Counterparty repository: checks beneficiary
- Order workflow → Corridor repository: loads corridor
- Order workflow → Order repository: saves and queries
- Counterparty service → Counterparty repository: reads and saves
- Corridor service → Corridor repository: reads and saves
- Order repository → Remittance database: persists orders
- Counterparty repository → Remittance database: persists counterparties
- Corridor repository → Remittance database: persists corridors