# bishal0602/chaotic-canvas architecture

> Architecture diagram of the GitHub repository bishal0602/chaotic-canvas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bishal0602/chaotic-canvas
- Repository: https://github.com/bishal0602/chaotic-canvas

## Overview

##### Project Type and Purpose
- chaotic-canvas is a CLI tool (monolithic Go application) that implements a genetic algorithm to evolve random images toward a target image.
- Its purpose is to demonstrate and experiment with genetic operations (selection, crossover, mutation) in the domain of image processing.

##### File Structure Analysis
- Top-level:
- main.go: entry point, CLI flag parsing, orchestration
- config/config.go: CLI argument loader and validation
- genetic/: core GA engine (algorithm.go, individual.go, selection.go, crossover.go, mutation.go)
- imageio/: image I/O, resizing, compression utilities
- mathutil/: random number generation, numeric helpers
- assets/, examples/: static resources (target images, samples)
- Patterns:
- Layered/Modular – CLI layer, GA engine layer, utility layer
- Pipeline-style within GA: init → fitness → selection → crossover → mutation → replacement → termination

##### README Insights
- Shows high-level flowchart of the GA loop
- Describes each GA phase (initialization, fitness, selection, crossover, mutation, replacement, termination)
- Lists command-line flags, default values, and expected outputs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Config Layer
    subgraph "CLI & Config" 
        direction TB
        Main["main.go"] 
        Config["config/config.go"]
    end

    %% Core GA Engine
    subgraph "Core GA Engine"
        direction TB
        Engine["GA Engine\n(core loop & replacement)"]
        PopMgr["Population Manager"]
        Individual["Individual Representation"]
        Selection["Selection Module"]
        Crossover["Crossover Module"]
        Mutation["Mutation Module"]
        Replacement["Replacement Module"]
        FitnessEval["Fitness Evaluator\n(Image Comparator)"]
        Profiler["pprof Profiler"]
    end

    %% Utilities Layer
    subgraph "Utilities"
        direction TB
        ImageIO["Image I/O & Resizer"]
        Resizer["Image Resizer"]
        RandomUtil["Random Util"]
        NumericUtil["Numeric Util"]
    end

    %% File System Layer
    subgraph "File System"
        direction TB
        Assets["Assets"]
        Examples["Examples"]
        Output["Output Images"]
    end

    %% Connections
    Main -->|"parses flags"| Config
    Config -->|"provides params"| Engine

    Engine -->|1 Init| PopMgr
    PopMgr -->|provides initial population| Engine
    Engine -->|2 Fitness| FitnessEval
    Engine -->|3 Selection| Selection
    Selection -->|selects Individuals| Engine
    Engine -->|4 Crossover| Crossover
    Crossover -->|generates Individuals| Engine
    Engine -->|5 Mutation| Mutation
    Mutation -->|modifies Individuals| Engine
    Engine -->|6 Replacement| Replacement
    Replacement -->|updates population| PopMgr
    Engine -->|7 Check Termination| Engine

    FitnessEval -->|uses| ImageIO
    FitnessEval -->|uses| RandomUtil
    Selection -->|uses| RandomUtil
    Crossover -->|uses| RandomUtil
    Mutation -->|uses| RandomUtil
    ImageIO -->|uses| Resizer

    Engine -->|writes| Output
    Assets -->|read target image| FitnessEval
    Examples -->|read samples| Engine

    Engine --- Profiler

    %% Click Events
    click Main "https://github.com/bishal0602/chaotic-canvas/blob/main/main.go"
    click Config "https://github.com/bishal0602/chaotic-canvas/blob/main/config/config.go"
    click Engine "https://github.com/bishal0602/chaotic-canvas/blob/main/genetic/algorithm.go"
    click PopMgr "https://github.com/bishal0602/chaotic-canvas/blob/main/genetic/algorithm.go"
    click Individual "https://github.com/bishal0602/chaotic-canvas/blob/main/genetic/individual.go"
    click Selection "https://github.com/bishal0602/chaotic-canvas/blob/main/genetic/selection.go"
    click Crossover "https://github.com/bishal0602/chaotic-canvas/blob/main/genetic/crossover.go"
    click Mutation "https://github.com/bishal0602/chaotic-canvas/blob/main/genetic/mutation.go"
    click FitnessEval "https://github.com/bishal0602/chaotic-canvas/blob/main/imageio/image.go"
    click ImageIO "https://github.com/bishal0602/chaotic-canvas/blob/main/imageio/image.go"
    click Resizer "https://github.com/bishal0602/chaotic-canvas/blob/main/imageio/resize.go"
    click RandomUtil "https://github.com/bishal0602/chaotic-canvas/blob/main/mathutil/random.go"
    click NumericUtil "https://github.com/bishal0602/chaotic-canvas/blob/main/mathutil/numeric.go"
    click Assets "https://github.com/bishal0602/chaotic-canvas/tree/main/assets/"
    click Examples "https://github.com/bishal0602/chaotic-canvas/tree/main/examples/"

    %% Styles
    classDef cli fill:#bbe1fa,stroke:#3282b8,stroke-width:2px
    classDef core fill:#d1f2a5,stroke:#4caf50,stroke-width:2px
    classDef util fill:#ffd8a9,stroke:#ff8c00,stroke-width:2px
    classDef fs fill:#eeeeee,stroke:#999999,stroke-width:2px

    class Main,Config cli
    class Engine,PopMgr,Individual,Selection,Crossover,Mutation,Replacement,FitnessEval,Profiler core
    class ImageIO,Resizer,RandomUtil,NumericUtil util
    class Assets,Examples,Output fs
```
