# python-eel/eel architecture

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

- Interactive diagram: https://gitdiagram.com/python-eel/eel
- Repository: https://github.com/python-eel/eel

## Overview

##### Project Type & Purpose
- Eel is a Python library designed for making simple, Electron-like GUI applications. It bridges Python and frontend (HTML/JS) code by launching a local webserver (using Bottle and Gevent) and establishing a bidirectional communication channel (using websockets).
- The key idea is to let developers quickly build light-weight desktop applications that leverage Python’s libraries alongside common web technologies (HTML, CSS, JS).

##### File Structure
- The core Python library resides in the “eel” directory which contains key modules like __init__.py, __main__.py, browsers.py, and platform-specific modules (chrome.py, edge.py, electron.py, msIE.py). This indicates the library’s support for multiple “modes” or browsers for presenting the GUI.
- The “examples” directory contains myriad standalone usage demos (e.g., hello_world, callbacks, file_access, etc.) that illustrate different features and deployment methods (including integration with frameworks like CreateReactApp).
- There are extensive testing directories (“tests/unit”, “tests/integration”) and CI configuration (in .github, .travis.yml, tox.ini) that articulate the process for validating the library.
- Supporting files like setup.py, requirements.txt, and configuration files for package management imply this is a well-packaged and distributed Python package.

##### Key Components
a. Backend (Python Layer):
– The “eel” module: This is the heart of the project handling webserver initialization, serving static assets, and binding Python functions to be callable from the frontend.
– Integration with Bottle and Gevent: Depicted as sub-components managing route registration and asynchronous processing respectively.
– Function exposing mechanism: Illustrate how Python functions (decorated with @eel.expose) are registered for cross-language calls.

b. Frontend (Web Layer):
– Static Web Files: Represent the “web” directories found in the examples (HTML, CSS, JavaScript) that form the UI.
– Eel.js library: This file is injected into the served web pages to enable communication with Python.
– Various examples (hello_world, callbacks, etc.): These can be highlighted as different use-case implementations of the basic architecture.

c. Communication Channel:
– Synchronous vs. asynchronous calls: Optionally include annotations that differentiate between queued calls (prior to window launch) and live calls across the websocket.

d. External/Deployment Components:
– Packaging & Distribution: A node indicating support for creating standalone executables using PyInstaller (with references to build scripts like setup.py, manifest, etc.)
– CI/CD and Testing Pipeline: Represent the Continuous Integration tools (GitHub Actions, Travis CI) and testing layers (unit tests, integration tests) that ensure stability.

##### Architectural Patterns & Technologies
- Separation of concerns between the frontend (UI using standard web technologies) and the backend (Python logic with specific modules for exposing functions).
- Asynchronous architecture enabled by Gevent and the simple web server (Bottle) that serves static content.
- Design principle of “exposing functions” through decorators and the use of websockets for non-blocking, two-way communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Layer
    subgraph "Backend Layer"
        EEL["Python Backend (Eel Library)"]:::backend
        BOTTLE["Bottle Webserver"]:::backend
        GEVENT["Gevent Async Engine"]:::backend
        BROWSER["Browser Modes Integration"]:::backend
        EEL -->|"initializes"| BOTTLE
        EEL -->|"handles_async"| GEVENT
        EEL -->|"selects_browser"| BROWSER
    end

    %% Communication Layer
    subgraph "Communication Layer"
        WS["Websockets Communication"]:::communication
        EELS_JS["Eel.js Library"]:::frontend
        %% Bidirectional websocket communication
        EEL <-->|"websockets"| EELS_JS
        EELS_JS -->|"utilizes"| WS
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        STATIC["Static Web UI (Demo UIs)"]:::frontend
        HELLO["Hello World Demo (@eel.expose)"]:::frontend
        CALLBACKS["Callbacks Demo (@eel.expose)"]:::frontend
        EELS_JS -->|"injects_script_into"| STATIC
        STATIC -->|"triggers_function"| HELLO
        STATIC -->|"triggers_function"| CALLBACKS
    end

    %% External & Deployment
    PACKAGING["Packaging & Distribution"]:::deployment
    CI["CI/CD & Testing Pipeline"]:::testing

    PACKAGING -->|"packages"| EEL
    CI -->|"validates"| EEL

    %% Click Events
    click EEL "https://github.com/python-eel/eel/blob/main/eel/__init__.py"
    click BROWSER "https://github.com/python-eel/eel/blob/main/eel/browsers.py"
    click EELS_JS "https://github.com/python-eel/eel/blob/main/eel/eel.js"
    click STATIC "https://github.com/python-eel/eel/tree/main/examples/01 - hello_world/web"
    click HELLO "https://github.com/python-eel/eel/blob/main/examples/01 - hello_world/hello.py"
    click CALLBACKS "https://github.com/python-eel/eel/blob/main/examples/02 - callbacks/callbacks.py"
    click CI "https://github.com/python-eel/eel/blob/main/.github"
    click PACKAGING "https://github.com/python-eel/eel/blob/main/setup.py"

    %% Styles
    classDef backend fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef frontend fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef communication fill:#f94144,stroke:#333,stroke-width:2px;
    classDef deployment fill:#577590,stroke:#fff,stroke-width:2px;
    classDef testing fill:#43aa8b,stroke:#333,stroke-width:2px;
```
