# kivy-school/kivy-reloader architecture

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

- Interactive diagram: https://gitdiagram.com/kivy-school/kivy-reloader
- Repository: https://github.com/kivy-school/kivy-reloader

## Overview

##### Project Type and Purpose
- This is a developer tool built around the Kivy framework. Its main purpose is to “hot reload” Kivy apps in real-time on multiple devices (Android phones, emulators, desktops) so developers can see changes instantly without having to recompile every time.
- It integrates with build systems like Buildozer and supports configurations via a TOML file (kivy-reloader.toml) and even works within a Poetry-managed environment.

##### File Structure
- At the top level, you find configuration files (.gitignore, buildozer.spec, pyproject.toml) and key directories: “beautifulapp” (an example advanced Kivy app structure) and “kivy_reloader” (the core library modules).
- The “kivy_reloader” directory contains critical modules:
- app.py – which likely wraps and extends Kivy’s App functionality to enable hot reloading.
- bootstrap.py, compile_app.py, config.py, send_app_to_phone.py, and utils.py – these modules suggest responsibilities such as starting the application, compiling the app to an APK, reading configuration, linking to Android, and utility functions for file watching.
- Additionally, directories like “bin” contain pre-built APKs for quick testing. There is also a “beautifulapp” folder that demonstrates an advanced project structure with separate modules for screens (using Kivy’s language file .kv and Python screen definitions).

##### Key System Components
a. Core Library (Kivy Reloader):
- Components:
- App wrapper (kivy_reloader/app.py)
- Bootstrap and startup code (bootstrap.py)
- Compilation and deployment logic (compile_app.py, send_app_to_phone.py)
- Configuration handling (config.py)
- Utility functions (utils.py)
- These modules work together to monitor file changes (using a dependency like watchdog via Kaki) and trigger reloading on connected devices.

b. Client Application(s):
- The “beautifulapp” directory exemplifies an advanced Kivy application structure that uses the reloader. It includes:
- The Main App definition (in __init__.py, which creates a MainApp subclass extending the Kivy Reloader App)
- Screens (with separate KV and Python files that define UI layout and logic)
- The “main.py” at the root level (and similarly the one inside beautifulapp) serves as the entry point where the app is initialized and run.

c. Configuration & Build Layer:
- The “kivy-reloader.toml” file for configuring watched files/folders, the IP addresses for phones, and hot reload settings.
- Buildozer spec files (at both the root and within the kivy_reloader directory) for building the Android APK.
- The CLI commands and scripts that facilitate running commands such as “kivy-reloader run” which handle app compilation, deployment, and starting a scrcpy mirror.

##### Relationships and Data Flow
- The entry point (main.py) initializes the MainApp which is defined in either the “beautifulapp” folder or the core library.
- Once running, the app monitors file system changes as specified in “kivy-reloader.toml”. When a change is detected (using the underlying “watchdog” mechanism integrated via Kaki), the Kivy Reloader’s utility functions trigger a live reload.
- For Android and other device targets, the buildozer configuration is used to compile and deploy the updated APKs.
- External tools (ADB, scrcpy) are used to interact with connected devices, showing mirrored logs and interfaces.

##### Architectural Patterns and Design Principles
- Modular design: The project cleanly separates the developer tool’s core functionality (in the “kivy_reloader” directory) from the example client app (“beautifulapp”).
- Configuration-driven behavior: The use of a TOML configuration file lets you control which directories/files trigger a reload.
- Event-driven design: The hot reload mechanism is reactive – file changes trigger events that cause the app’s state to update in real time.
- Encapsulation of platform-specific tasks: The build and deployment logic is abstracted behind the utility modules and buildozer spec files.

##### Elements
- Each major component should be clearly labeled (e.g., “Configuration Module”, “File Watcher & Reload Engine”, “Compilation & Deployment Module”, “Client Kivy App”).
- Initialization flow from main.py to MainApp.
- Data flow from file watcher → configuration check → reload trigger.
- Build and deployment flow from compilation module to device (APK deployment via ADB and mirroring via scrcpy).
- Annotations that mention the use of external libraries and frameworks (e.g., Kivy, Kaki, watchdog, Buildozer).

a. The Client-side: Represent the “beautifulapp” with its screens and UI logic.
b. The Core Tool: Represent the “kivy_reloader” directory modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client App Layer
    subgraph "Client App Layer"
        entry["Application Entry Point: main.py"]:::entry
        client["Client Kivy App: MainApp"]:::client
        screens["UI Screens & Layouts"]:::client
    end

    %% Core Reloader Layer
    subgraph "Core Reloader Layer"
        wrapper["Core App Wrapper"]:::core
        bootstrap["Bootstrap/Startup Module"]:::core
        config["Configuration Handler"]:::config
        toml["Config File: kivy-reloader.toml"]:::config
        utils["Utility Functions"]:::core
        compile["Compilation Module"]:::core
        deploy["Deployment Module"]:::core
        build["Build/Packaging Configuration"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        adb["ADB & scrcpy"]:::external
        android["Android Device"]:::external
    end

    %% Connections in Client Layer
    entry -->|"initializes"| client
    client -->|"loads"| screens

    %% Connections between Client and Core Layers
    screens -->|"file-change trigger"| utils

    %% Connections in Core Reloader Layer
    toml -->|"configure"| config
    config -->|"provide settings"| bootstrap
    wrapper -->|"initializes"| bootstrap
    bootstrap -->|"starts compilation"| compile
    build -->|"used by"| compile
    utils -->|"triggers build"| compile
    compile -->|"builds & compiles"| deploy
    deploy -->|"deploys APK"| adb

    %% Connections to External Systems
    adb -->|"interfaces with"| android

    %% Click Events
    click entry "https://github.com/kivy-school/kivy-reloader/blob/main/main.py"
    click client "https://github.com/kivy-school/kivy-reloader/tree/main/beautifulapp"
    click screens "https://github.com/kivy-school/kivy-reloader/tree/main/beautifulapp/screens"
    click wrapper "https://github.com/kivy-school/kivy-reloader/blob/main/kivy_reloader/app.py"
    click bootstrap "https://github.com/kivy-school/kivy-reloader/blob/main/kivy_reloader/bootstrap.py"
    click config "https://github.com/kivy-school/kivy-reloader/blob/main/kivy_reloader/config.py"
    click toml "https://github.com/kivy-school/kivy-reloader/blob/main/kivy-reloader.toml"
    click utils "https://github.com/kivy-school/kivy-reloader/blob/main/kivy_reloader/utils.py"
    click compile "https://github.com/kivy-school/kivy-reloader/blob/main/kivy_reloader/compile_app.py"
    click deploy "https://github.com/kivy-school/kivy-reloader/blob/main/kivy_reloader/send_app_to_phone.py"
    click build "https://github.com/kivy-school/kivy-reloader/blob/main/buildozer.spec"

    %% Styles
    classDef entry fill:#FFD700,stroke:#333,stroke-width:2px
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef core fill:#90EE90,stroke:#333,stroke-width:2px
    classDef config fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef external fill:#F4A460,stroke:#333,stroke-width:2px
```
