# fatihak/inkypi architecture

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

- Interactive diagram: https://gitdiagram.com/fatihak/inkypi
- Repository: https://github.com/fatihak/inkypi

## Overview

##### Project Type & Purpose
- InkyPi is a full-stack application for managing and displaying custom content on an E-Ink display.
- It provides a web interface (for configuration and content updates), a plugin system for extensibility (e.g., Clock, Weather, AI plugins, etc.), and interacts with hardware (Raspberry Pi and E-Ink display).
- The application is organized as a Python project (using Flask-style blueprints for API/route handling) that integrates static assets, templates, and scheduled tasks.

##### Analyzing the File Structure
- Top-Level Directories:
- install: Contains installation, update, and uninstallation scripts as well as service configuration files. This highlights key deployment aspects (e.g., enabling SPI and I2C interfaces).
- src: The heart of the application. Under src, several subdirectories segregate the code into logical components:
▪ blueprints: Likely implementing different web routes/endpoints (e.g., main interface, playlist, plugin management, settings).
▪ plugins: Contains individual plugin implementations. Each plugin has its own directory (ai_image, ai_text, clock, newspaper, screenshot, weather, etc.) along with associated HTML templates or CSS.
▪ config & config.py: Contains configuration settings including logging; this defines runtime behavior.
▪ templates and static: The web UI components such as HTML views, CSS, JavaScript, and fonts.
▪ utils: Contains helper functions for application, image, or time processing.
- docs: Provides documentation on installation, troubleshooting, plugin development, and more.
- scripts and .github: Contain testing scripts and CI/CD or issue reporting configurations respectively.

a. Web Interface Layer (Frontend):
- Client devices (e.g., browsers on local network devices) that interact with the system.
- That the web UI is served with HTML templates from src/templates and static assets (CSS, JS, images).
b. Application Server (Backend):
- InkyPi Main Controller (src/inkypi.py): The entry point of the application.
- Blueprints (src/blueprints): Include main, playlist, plugin, and settings endpoints. Emphasize the use of Flask (or similar microframework) patterns.
- Plugin Registry & Manager: Illustrate src/plugins/plugins.json, src/plugins/plugin_registry.py, and the individual plugin modules. This forms a modular extension point where custom content (weather, clock, newspaper, etc.) is handled.
- & Refresh Modules: Include src/display_manager.py and src/refresh_task.py that handle updating the E-Ink display at scheduled intervals.
- Utility Functions: Represent src/utils as supporting infrastructure for image processing, time handling, etc.
c. Hardware Interface:
- Raspberry Pi hardware including the E-Ink display. Also note that installation scripts configure the OS-level SPI and I2C interfaces.
d. Installation & Maintenance:
- Install scripts (install/install.sh, update.sh, uninstall.sh) and related configuration files which support system deployment and lifecycle management.

##### Relationships & Interactions
- The web clients communicate with the backend via HTTP requests.
- The backend receives requests (via Flask blueprints) and may trigger actions in the plugin manager (loading or switching plugins).
- The display manager takes aggregated data and, possibly using the refresh task scheduler, periodically updates the E-Ink display.
- Utility functions support data processing and configuration modules manage runtime settings.
- The plugin mechanism allows dynamic loading and updating of different content modules, which are registered in the plugin registry.
- Installation scripts ensure that system-level configurations and dependencies are properly set for hardware access.

##### Important Architectural Patterns
- Modular design: The extensive use of plugins and blueprints emphasizes separation of concerns.
- Full-stack layering: Clear division between frontend (HTML, CSS, JS) and backend (Python controllers, plugins, hardware interfacing).
- Configurability & extensibility: Through separate configuration files and a plugin registry, new functionality can be added without disturbing existing code.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        client("Web Client"):::frontend
        ui_templates("HTML Templates"):::frontend
        static_assets("Static Assets"):::frontend
    end

    %% Application Server Layer
    subgraph "Application Server Layer"
        controller("InkyPi Main Controller"):::backend
        blueprints("Flask Blueprints"):::backend
        config("Configuration & Logging"):::backend
        plugin_manager("Plugin Registry & Manager"):::backend
        plugins("Individual Plugins"):::backend
        display_manager("Display Manager"):::backend
        refresh_task("Scheduled Task"):::backend
        utils("Utility Functions"):::backend
    end

    %% Hardware & Deployment Layer
    subgraph "Hardware & Deployment"
        hardware("Raspberry Pi Hardware"):::hardware
        display("E-Ink Display"):::hardware
        install("Installation & Deployment"):::hardware
    end

    %% Relationships
    client -->|"HTTP_request"| blueprints
    blueprints -->|"routes_to"| controller
    blueprints -->|"serves"| ui_templates
    blueprints -->|"serves"| static_assets
    controller -->|"loads_config"| config
    controller -->|"initiates_plugin"| plugin_manager
    plugin_manager -->|"manages"| plugins
    controller -->|"updates_display"| display_manager
    refresh_task -->|"triggers_update"| display_manager
    controller -->|"uses"| utils
    display_manager -->|"controls"| display
    install -->|"configures"| hardware
    install -->|"sets_up"| display

    %% Styles
    classDef frontend fill:#c2f0c2,stroke:#008000,stroke-width:2px;
    classDef backend fill:#cce5ff,stroke:#003399,stroke-width:2px;
    classDef hardware fill:#fff2cc,stroke:#b8860b,stroke-width:2px;

    %% Click Events
    click ui_templates "https://github.com/fatihak/inkypi/tree/main/src/templates"
    click static_assets "https://github.com/fatihak/inkypi/tree/main/src/static"
    click controller "https://github.com/fatihak/inkypi/blob/main/src/inkypi.py"
    click blueprints "https://github.com/fatihak/inkypi/tree/main/src/blueprints"
    click config "https://github.com/fatihak/inkypi/blob/main/src/config.py"
    click config "https://github.com/fatihak/inkypi/blob/main/src/config/logging.conf"
    click display_manager "https://github.com/fatihak/inkypi/blob/main/src/display_manager.py"
    click refresh_task "https://github.com/fatihak/inkypi/blob/main/src/refresh_task.py"
    click plugin_manager "https://github.com/fatihak/inkypi/blob/main/src/plugins/plugin_registry.py"
    click plugins "https://github.com/fatihak/inkypi/tree/main/src/plugins"
    click utils "https://github.com/fatihak/inkypi/tree/main/src/utils"
    click install "https://github.com/fatihak/inkypi/tree/main/install"
```
