# tomster12/factorio-blueprints architecture

> Architecture diagram of the GitHub repository tomster12/factorio-blueprints, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tomster12/factorio-blueprints
- Repository: https://github.com/tomster12/factorio-blueprints

## Overview

##### Project Type & Purpose
- This is a standalone C++ command‐line tool (“FactorioBlueprints”) that generates optimal layout blueprints for the game Factorio.
- It combines a Simulated Annealing–based Optimization Engine (for assembler/inserter placement) with a CBS + A*–based Pathfinding Engine (for multi-agent conveyor routing).

##### File‐Structure Analysis
- Top level: a Visual Studio solution (FactorioBlueprints.sln) and single project directory.
- Core modules in `FactorioBlueprints/`:
- main.cpp        → CLI entry point, argument parsing
- ProblemSolver.* → SimulatedAnnealingCore
- PlacementState.*→ in‐memory representation of the current blueprint layout
- PlacementPathfinder.*→ ConveyorRoutingEngine (CBS + A* pathfinder)
- global.*, log.h, macros.h, types.h, ls.h, pf.h → configuration, logging, shared types, macro utilities

##### README Insights
- Uses Simulated Annealing to optimize assembler & inserter placement.
- Uses Conflict‐Based Search + A* for conveyor belt pathfinding.
- Core flow: load blueprint parameters → run optimization loop → output best blueprint.

1. CLI Frontend
– Parses user inputs (blueprint specs, iteration count, output path)
2. Input/Output Module
– Blueprint Loader/Parser (JSON or text format)
– Blueprint Serializer (final optimized blueprint export)
3. Optimization Engine (SimulatedAnnealingCore)
– “AssemblerInserterPlacementEngine”
– Manages temperature schedule, neighbor generation, acceptance criteria
4. Placement State
– Current layout model (factories, inserters, belts)
– Provides interface to evaluate and apply moves
5. Pathfinding Engine (ConveyorRoutingEngine)
– CBS Coordinator
– A* Sub‐searchers for individual conveyor agents
6. Support Services
– GlobalConfig (global constants, parameters)
– Logging Service (log.h) for metrics, debug output
– Shared Types & Macros (types.h, macros.h, ls.h, pf.h)

b. Relationships & Data Flow
- CLI Frontend → Input Parser: load blueprint spec → Initial PlacementState
- SimulatedAnnealingCore
↔ PlacementState: generate neighbor states (move an assembler/inserter)
↔ PathfindingEngine: whenever a change affects belts, recompute routes via CBS + A*
→ Logging Service: record energy/cost, temperature, acceptance decisions
- On termination: PlacementState → Output Serializer → final blueprint file

c. Architectural Patterns & Principles
- Modular separation: distinct layers for CLI, IO, optimization logic, pathfinding, and utilities
- Pipeline style: Input → Optimize (with inner loop) → Output
- Algorithmic kernels isolated into ProblemSolver and PlacementPathfinder

d. Key Technologies & Libraries
- C++17 (or later), Visual Studio project
- Custom Simulated Annealing implementation
- Custom multi-agent CBS + A* pathfinder

- Green for front‐end/Input/Output
- Blue for Optimization Engine
- Orange for Pathfinding Engine
- Gray for Support Services (Config, Logging)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend / IO
    subgraph "Frontend / IO" 
        direction TB
        CLI["CLI Frontend"]:::frontend
        Loader["Blueprint Loader/Parser"]:::frontend
        Serializer["Blueprint Serializer"]:::frontend
    end

    %% Core Optimization
    subgraph "Optimization Engine (SimulatedAnnealingCore)" 
        direction TB
        SA["Assembler & Inserter Placement Engine"]:::optimize
    end

    %% Placement State
    PS["Blueprint State Model"]:::optimize

    %% Pathfinding Engine
    subgraph "Pathfinding Engine (Conveyor Routing)" 
        direction TB
        CBS["CBS Coordinator"]:::path
        AStar["A* Sub-searcher"]:::path
    end

    %% Support Services
    subgraph "Support Services"
        direction TB
        Config["GlobalConfig"]:::support
        Logging["Logging Service"]:::support
        Types["Shared Types"]:::support
        Macros["Shared Macros"]:::support
        LS["List/State Utils"]:::support
        PFUtils["Pathfinding Utils"]:::support
    end

    %% Data Flow
    CLI -->|"parseArgs()"| Loader
    Loader -->|"loadBlueprint()"| PS
    PS -->|"initialState"| SA
    SA -->|"computeNeighbors()"| PS
    SA -->|"solvePaths()"| CBS
    CBS -->|"coordinate()"| AStar
    AStar -->|"pathResults"| PS
    SA -->|"logMetrics()"| Logging
    Config --> SA
    Types --> SA
    Macros --> SA
    LS --> SA
    PFUtils --> SA
    PS -->|"serialize()"| Serializer

    %% Loop Annotation
    SA --> SANote["loop: temperature schedule\nacceptance criteria"]:::note
    SANote -.-> SA

    %% Click Events
    click CLI "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/main.cpp"
    click SA "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/ProblemSolver.cpp"
    click PS "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/PlacementState.cpp"
    click CBS "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/PlacementPathfinder.cpp"
    click Config "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/global.cpp"
    click Logging "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/log.h"
    click Types "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/types.h"
    click Macros "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/macros.h"
    click LS "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/ls.h"
    click PFUtils "https://github.com/tomster12/factorio-blueprints/blob/master/FactorioBlueprints/pf.h"

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#2d7,stroke-width:1px
    classDef optimize fill:#e0f0ff,stroke:#28f,stroke-width:1px
    classDef path fill:#fff0e0,stroke:#f83,stroke-width:1px
    classDef support fill:#f0f0f0,stroke:#999,stroke-width:1px
    classDef note fill:#ffffff,stroke-dasharray: 2 2,stroke:#666,stroke-width:1px

    %% Legend
    subgraph Legend
        direction LR
        F["Frontend / IO"]:::frontend
        O["Optimization Engine"]:::optimize
        P["Pathfinding Engine"]:::path
        S["Support Services"]:::support
    end
```
