# adonisvip/py-space-invaders architecture

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

- Interactive diagram: https://gitdiagram.com/adonisvip/py-space-invaders
- Repository: https://github.com/adonisvip/py-space-invaders

## Overview

##### Project type and purpose
- This is a modular Python game (Space Invaders) built on Pygame for desktop and Android (via Buildozer).
- Purpose: arcade shooter with menu, gameplay, score tracking, history persistence, and sound effects.

##### File structure
- Top-level modules:
- main.py          – optimized game entry point and main loop
- main-base.py     – original monolithic version (for reference)
- config.py        – game constants and configuration
- game_manager.py  – orchestrates game state, scoring, sprites coordination
- sprites.py       – all game object classes (Spaceship, Alien, Bullet, Explosion)
- ui_manager.py    – UI rendering and input handling (menus, text fields)
- history.json     – persistent storage for last 3 games
- img/             – assets (images + WAV files)
- requirements.txt – Pygame dependency

##### Inspect the README for architecture hints
- Described as “modular architecture” with clear separation of concerns.
- Lists key classes and responsibilities.
- Mentions Android support via Buildozer (buildozer.spec is present).

a. Main components
1. Input Layer
– Keyboard / Mouse / Touch (Android)
2. Main Application
– main.py (Game Loop & Event Dispatcher)
3. UI Layer
– UIManager (menus, name input, pause, game-over screens)
4. Game Logic Layer
– GameManager (state machine: menu → countdown → playing → victory/game-over)
5. Domain Objects
– Sprite classes (Spaceship, Alien, Bullet, Explosion)
6. Configuration
– config.py (constants: screen size, FPS, speeds, health, cooldowns)
7. Asset Store
– img/ (PNG, WAV files)
8. Persistence
– history.json (read/write last 3 games)
9. External Services
– Pygame library
10. Build/Deployment
– Buildozer (Android packaging)

b. Relationships & interactions
– Input Layer → main.py (sends Pygame events)
– main.py → UIManager (route menu/input events), → GameManager (route gameplay events)
– UIManager ↔ GameManager (e.g., show/hide UI based on game state)
– GameManager ↔ Sprites (create, update, destroy game objects)
– GameManager → config.py (fetch constants)
– GameManager → history.json (read on start, write on game-over)
– Assets (img/) loaded by Sprites & UIManager at initialization
– Buildozer reads buildozer.spec & requirements.txt for Android packaging

c. Architectural patterns & principles
– Modular separation: UI vs. Logic vs. Data vs. Assets
– Single Responsibility: each module/class has one clear role
– Event-driven loop: Pygame main loop dispatches to subcomponents
– State machine in GameManager for game states (menu, play, pause, over)

d. Key technologies/frameworks
– Python 3.7+
– Pygame 2.x (core engine for rendering, input, sound)
– Buildozer (Android packaging)
– JSON (history persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    Input["Input Layer\n(Keyboard/Mouse/Touch)"]:::input
    click Input "https://github.com/adonisvip/py-space-invaders/blob/main/main.py"

    %% Main Application
    MainApp["main.py\n(Game Loop & Event Dispatcher)"]:::internal
    click MainApp "https://github.com/adonisvip/py-space-invaders/blob/main/main.py"

    %% UI Layer
    UIManager["ui_manager.py\n(UI Layer)"]:::internal
    click UIManager "https://github.com/adonisvip/py-space-invaders/blob/main/ui_manager.py"

    %% Game Logic Layer
    GameManager["game_manager.py\n(Game Logic Layer)"]:::internal
    click GameManager "https://github.com/adonisvip/py-space-invaders/blob/main/game_manager.py"

    %% Domain Objects
    Sprites["sprites.py\n(Domain Objects)"]:::internal
    click Sprites "https://github.com/adonisvip/py-space-invaders/blob/main/sprites.py"

    %% Configuration
    Config["config.py\n(Configuration)"]:::internal
    click Config "https://github.com/adonisvip/py-space-invaders/blob/main/config.py"

    %% Asset Store
    AssetStore["img/\n(Assets Store)"]:::datastore
    click AssetStore "https://github.com/adonisvip/py-space-invaders/tree/main/img/"

    %% Persistence
    History["history.json\n(Persistence)"]:::datastore
    click History "https://github.com/adonisvip/py-space-invaders/blob/main/history.json"

    %% External Services
    Pygame["requirements.txt\n(Pygame Dependency)"]:::external
    click Pygame "https://github.com/adonisvip/py-space-invaders/blob/main/requirements.txt"

    %% Build/Deployment
    Buildozer["buildozer.spec\n(Android Packaging)"]:::external
    click Buildozer "https://github.com/adonisvip/py-space-invaders/blob/main/buildozer.spec"

    %% Connections
    Input -->|"Pygame events"| MainApp
    MainApp -->|"menu/input events"| UIManager
    MainApp -->|"gameplay events"| GameManager
    UIManager <-->|"UI↔Game state"| GameManager
    GameManager -->|"create/update objects"| Sprites
    Sprites -->|"render/draw & sound"| Pygame
    GameManager -->|"fetch constants"| Config
    GameManager -->|"JSON read/write"| History
    Sprites -->|"load images/sounds"| AssetStore
    UIManager -->|"load assets"| AssetStore
    Pygame -->|"dependency list"| Buildozer

    %% Styles
    classDef internal fill:#1f77b4,stroke:#333,stroke-width:1px,color:#fff;
    classDef datastore fill:#2ca02c,stroke:#333,stroke-width:1px,color:#fff;
    classDef external fill:#ff7f0e,stroke:#333,stroke-width:1px,color:#fff;
    classDef input fill:#7f7f7f,stroke:#333,stroke-width:1px,color:#fff;
```
