# oenzoribas/flappybirdai architecture

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

- Interactive diagram: https://gitdiagram.com/oenzoribas/flappybirdai
- Repository: https://github.com/oenzoribas/flappybirdai

## Overview

##### File structure
- Root directory
- neat.config.txt – NEAT algorithm settings
- neat_run.py – orchestrates training loop (population initialization, fitness evaluation, selection, mutation)
- run.py – launches an interactive, human-playable instance of the game
- models/ – stores serialized (“.pkl”) winners from different generations
- media/ – contains showcase videos and GIFs
- Project/
- assets/ – sprite images and other static resources used by the game
- game/ – core game logic classes:
– bird.py, pipe.py, base.py, score.py
- tests, build scripts, microservices – none present, indicating a monolithic, single-process application

##### README for additional insights
- Describes NEAT’s evaluation loop: environment provides observations → neural network decides jump/no-jump → environment computes fitness
- Lists dependencies: Python 3.8+, Pygame, NEAT-Python, Matplotlib

##### Elements
- Config → Trainer → NEAT Engine
- NEAT Engine ↔ Game Environment
- Trainer → Model Storage
- Model Storage → Manual Runner / Visualizer
- Green for ML components (NEAT Engine, Trainer)
- Blue for game components (Game Environment, Manual Runner)
- Gray for file storage (models, media)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        Config["neat.config.txt"]:::config
    end

    subgraph "ML Components"
        Trainer["Trainer Script (neat_run.py)"]:::ml
        NEAT["NEAT Engine"]:::ml
    end

    subgraph "Game Components"
        subgraph "Game Environment"
            Base["base.py"]:::game
            Bird["bird.py"]:::game
            Pipe["pipe.py"]:::game
            Score["score.py"]:::game
        end
        Runner["Manual Runner (run.py)"]:::game
    end

    subgraph "Visualization"
        Visualizer["Visualization Module (visualize.py)"]:::viz
    end

    subgraph "Storage"
        Models["Model Storage"]:::storage
        Media["Media Showcase"]:::storage
    end

    subgraph "Assets"
        Assets["Assets (Project/assets/)"]:::storage
    end

    %% Relationships
    Config -->|"config settings"| Trainer
    Trainer -->|"initialize population"| NEAT
    NEAT -->|"genome"| Base
    Base -->|"fitness score"| NEAT
    Trainer -->|"best model.pkl"| Models
    Models -->|"model.pkl"| Runner
    Models -->|"model.pkl"| Visualizer
    Base -->|"load sprites"| Assets
    Runner -->|"launch game"| Base
    Visualizer -->|"plot.png"| Models

    %% Click Events
    click Config "https://github.com/oenzoribas/flappybirdai/blob/main/Project/neat.config.txt"
    click Trainer "https://github.com/oenzoribas/flappybirdai/blob/main/Project/neat_run.py"
    click Runner "https://github.com/oenzoribas/flappybirdai/blob/main/Project/run.py"
    click Visualizer "https://github.com/oenzoribas/flappybirdai/blob/main/Project/visualize.py"
    click Base "https://github.com/oenzoribas/flappybirdai/blob/main/Project/game/base.py"
    click Bird "https://github.com/oenzoribas/flappybirdai/blob/main/Project/game/bird.py"
    click Pipe "https://github.com/oenzoribas/flappybirdai/blob/main/Project/game/pipe.py"
    click Score "https://github.com/oenzoribas/flappybirdai/blob/main/Project/game/score.py"
    click Assets "https://github.com/oenzoribas/flappybirdai/tree/main/Project/assets/"
    click Models "https://github.com/oenzoribas/flappybirdai/blob/main/models/winner-122.pkl"
    click Media "https://github.com/oenzoribas/flappybirdai/blob/main/media/Showcase/neat_run-show-case.mp4"

    %% Styles
    classDef ml fill:#b2f2bb,stroke:#2f6627,stroke-width:1px
    classDef game fill:#cfe2ff,stroke:#084298,stroke-width:1px
    classDef storage fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef config fill:#fff3bf,stroke:#856404,stroke-width:1px
    classDef viz fill:#fcd5ce,stroke:#9d0208,stroke-width:1px
```
