# techwithtim/neat-flappy-bird architecture

> Architecture diagram of the GitHub repository techwithtim/neat-flappy-bird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/techwithtim/neat-flappy-bird
- Repository: https://github.com/techwithtim/neat-flappy-bird

## Overview

##### Project Type and Purpose
- This is a Python-based demonstration tool that uses the NEAT (NeuroEvolution of Augmenting Topologies) algorithm to train an AI to play Flappy Bird.
- The core deliverables are:
- flappy_bird.py – orchestrates the game loop, neural network evaluation, and evolution cycle
- config-feedforward.txt – NEAT configuration file
- best.pickle – the serialized “champion” genome after training
- imgs/ – game asset directory (bird, pipe, background images)

##### File Structure Analysis
- Top-level scripts:
- flappy_bird.py (main orchestrator)
- Configuration: config-feedforward.txt (NEAT-Python parameters)
- Data artifacts: best.pickle (pickled best genome)
- Assets: imgs/ (PNG images for Pygame)
- Environment descriptors: requirements.txt, .replit, .gitpod.yml
- README.md explains usage: “run flappy_bird.py” and mentions NEAT Python module

##### Key Components & Responsibilities
A. Game Environment (Pygame)
- Loads images from imgs/
- Presents pipes, bird sprite, handles physics & collision
- Provides state vector (e.g., bird y-position, distance to next pipe)
B. NEAT Engine (neat-python library)
- Reads config-feedforward.txt
- Maintains a population of Genomes (neural nets)
- Evaluates each genome by playing the game environment
- Assigns fitness based on survival/time/score
- Applies selection, crossover, mutation to evolve new generation
C. Orchestrator Script (flappy_bird.py)
- Initializes NEAT config and population
- Loops through generations, feeding environment state → neural net → action
- Updates environment with neural net outputs (flap or do nothing)
- Tracks fitness, checkpoints population, saves best genome to best.pickle
- Loads best.pickle and/or NEAT log/statistics files
- Renders fitness-over-time graphs, species diversity charts
- Draws the neural network topology of the best genome
E. Configuration Store & Artifacts
- config-feedforward.txt (text file)
- best.pickle (serialized model)
- requirements.txt (dependency list)

##### Relationships & Data Flows
- flappy_bird.py → reads → config-feedforward.txt
- flappy_bird.py → imports → neat, pygame, pickle
- flappy_bird.py → loads → imgs/ assets
- flappy_bird.py → creates → NEAT Population
- NEAT Population ↔ Game Environment (state in, action out)
- NEAT Engine → evolves → Genomes → best.pickle

##### Architectural Patterns & Principles
- Separation of Concerns:
- Game rendering/physics (Pygame)
- AI evolution logic (neat-python)
- Result visualization
- Modular Configuration: config file separated from code
- Data Persistence: pickled genome, logging for reproducibility
- Single-Process, Event-Loop Driven (no microservices)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Training Phase"
        Config["config-feedforward.txt"]:::doc
        Requirements["requirements.txt"]:::doc
        Replit[".replit"]:::doc
        Gitpod[".gitpod.yml"]:::doc
        Readme["README.md"]:::doc
        Runtime["Python Runtime & Libraries"]:::cloud
        Assets["imgs/"]:::folder
        Orchestrator["flappy_bird.py"]:::app
        GameEnv["Pygame Game Environment"]:::app
        NEATEngine["NEAT Engine (Population Manager)"]:::app
        DataStore[(best.pickle)]:::data
    end

    subgraph "Visualization Phase"
        Visualizer["visualize.py"]:::app
        DataStore
    end

    Config -->|load config| NEATEngine
    Requirements -->|install deps| Runtime
    Replit -->|env config| Runtime
    Gitpod -->|env config| Runtime
    Runtime -->|execute| Orchestrator
    Readme -->|run instructions| Orchestrator
    Orchestrator -->|load assets| Assets
    Orchestrator -->|initialize population| NEATEngine
    Orchestrator -->|game loop| GameEnv
    Assets -->|provide images| GameEnv
    GameEnv -->|state vector| NEATEngine
    NEATEngine -->|action outputs| GameEnv
    NEATEngine -->|save best & logs| DataStore
    DataStore -->|input data| Visualizer

    click Config "https://github.com/techwithtim/neat-flappy-bird/blob/master/config-feedforward.txt"
    click Requirements "https://github.com/techwithtim/neat-flappy-bird/blob/master/requirements.txt"
    click Replit "https://github.com/techwithtim/neat-flappy-bird/blob/master/.replit"
    click Gitpod "https://github.com/techwithtim/neat-flappy-bird/blob/master/.gitpod.yml"
    click Readme "https://github.com/techwithtim/neat-flappy-bird/blob/master/README.md"
    click Runtime "https://github.com/techwithtim/neat-flappy-bird/blob/master/requirements.txt"
    click Assets "https://github.com/techwithtim/neat-flappy-bird/tree/master/imgs/"
    click Orchestrator "https://github.com/techwithtim/neat-flappy-bird/blob/master/flappy_bird.py"
    click Visualizer "https://github.com/techwithtim/neat-flappy-bird/blob/master/visualize.py"
    click DataStore "https://github.com/techwithtim/neat-flappy-bird/blob/master/best.pickle"

    classDef app fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef data fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef folder fill:#ffe5b4,stroke:#cc8400,stroke-width:1px
    classDef doc fill:#f5c6cb,stroke:#721c24,stroke-width:1px
    classDef cloud fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
