# mher/flower architecture

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

- Interactive diagram: https://gitdiagram.com/mher/flower
- Repository: https://github.com/mher/flower

## Overview

This project is Flower – an open‐source web application designed specifically for monitoring and managing Celery clusters. Its purpose is to provide real-time dashboards and REST API endpoints for interacting with Celery workers, tasks, and broker statistics. The project’s file tree and the README give us a clear picture that Flower is a full-stack monitoring tool with a backend component (handling Celery events, control commands, etc.) and a frontend web interface (templates, static assets, and API endpoints).

##### Main Components
- Flower Web Application:
- Core server logic within files like flower/app.py and flower/command.py.
- Routing and view handlers found under the “flower/views” directory (handling authentication, task views, worker views, etc.).
- API functionality provided in “flower/api”, allowing administrators to restart worker pools, apply control changes, and monitor tasks.

- Frontend UI:
- HTML templates in “flower/templates”
- Static resources such as CSS and JavaScript in “flower/static” (which render the dashboard interface).

- Celery Cluster & Broker:
- External Celery workers and the message broker (e.g., RabbitMQ, Redis) are not internal code but form a critical part of the architecture.
- The Flower application connects with the message broker to capture real-time Celery events for task and worker monitoring.

- External Integrations:
- Authentication systems (HTTP Basic Auth, OAuth with providers like Google, Github, Gitlab, Okta).
- Prometheus integration for metrics monitoring (as described in the README and examples, such as “prometheus.yml” and examples/prometheus-alerts.yaml).

##### Component Relationships and Data Flow
- Data Flow:
- Celery Workers send events (task state updates, worker status, etc.) via the message broker.
- The Flower server listens to these events, aggregates real-time data, and updates the dashboard.
- Administrators use the web UI and API endpoints to send control commands (e.g., restart worker pool, revoke tasks), which are then issued to the connected Celery workers.

- Interaction Flow:
- REST API calls coming from clients (e.g., through curl) to the Flower server.

##### Architectural Patterns and Design Principles
- Layered Architecture:
- Separation between the presentation layer (Web UI templates and static assets) and the application logic (API and event handling logic).
- Modularity:
- Extensibility:
- The design allows for additional integrations (like OAuth and Prometheus) to be plugged into the system.

##### Specify Relevant Technologies
- Python is the core language.
- Celery, as the distributed task queue system.
- Celery Events for real-time monitoring.
- The Flower tool itself comes with REST API endpoints and a web dashboard.
- OAuth providers and Prometheus (as per integration examples) are part of the ecosystem.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    ExternalClient("External Client (API Calls)"):::external
    AuthProviders("Authentication Providers"):::external
    CeleryBroker("Celery Broker"):::external
    CeleryWorkers("Celery Workers & Tasks"):::external
    PrometheusSystem("Prometheus System"):::external

    %% Flower Web Application Subgraph
    subgraph "Flower Web Application"
      
      %% Core Server Components
      subgraph "Core Server"
        FlowerApp("Core App (flower/app.py)"):::internal
        FlowerCmd("Command (flower/command.py)"):::internal
      end

      %% API Functionality
      API("API Functionality"):::api

      %% View Handlers
      Views("View Handlers"):::internal

      %% Frontend UI Components
      subgraph "Frontend UI"
        Templates("Frontend Templates"):::frontend
        Static("Frontend Static Assets"):::frontend
      end

      %% Celery Integration Components
      subgraph "Celery Integration"
        CeleryEvents("Celery Events (flower/events.py)"):::internal
        BrokerUtils("Broker Utils (flower/utils/broker.py)"):::internal
      end

      %% Prometheus Integration Files
      subgraph "Prometheus Integration Files"
        PromYML("prometheus.yml"):::internal
        PromAlerts("prometheus-alerts.yaml"):::internal
      end

    end

    %% Connections between External Systems and Flower Web Application
    ExternalClient -->|"REST_API"| API
    AuthProviders -->|"Authentication"| Views
    PrometheusSystem -->|"Scrapes_Metrics"| PromYML

    %% Internal interactions within Flower Web Application
    FlowerApp -->|"Handles_Requests"| API
    FlowerCmd -->|"Handles_Commands"| API
    FlowerApp -->|"Renders_Views"| Views
    API -->|"Updates_Dashboard"| Views
    Views -->|"Serves_HTML"| Templates
    Static -->|"Provides_Assets"| Templates
    FlowerApp -->|"Collects_Events"| CeleryEvents
    FlowerCmd -->|"Processes_Broker"| BrokerUtils
    BrokerUtils -->|"Integrates_With"| CeleryEvents
    API -->|"Sends_Control"| CeleryWorkers

    %% External event flow from Celery Cluster
    CeleryWorkers -->|"Sends_Events"| CeleryBroker
    CeleryBroker -->|"Forwards_Events"| CeleryEvents

    %% Exporting Metrics Interaction
    API -->|"Exports_Metrics"| PrometheusSystem

    %% Styling Classes
    classDef internal fill:#D1E8FF,stroke:#1B4F72,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef api fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef frontend fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;

    %% Click Events for Component Mapping
    click FlowerApp "https://github.com/mher/flower/blob/master/flower/app.py"
    click FlowerCmd "https://github.com/mher/flower/blob/master/flower/command.py"
    click API "https://github.com/mher/flower/tree/master/flower/api/"
    click Views "https://github.com/mher/flower/tree/master/flower/views/"
    click Templates "https://github.com/mher/flower/tree/master/flower/templates/"
    click Static "https://github.com/mher/flower/tree/master/flower/static/"
    click CeleryEvents "https://github.com/mher/flower/blob/master/flower/events.py"
    click BrokerUtils "https://github.com/mher/flower/blob/master/flower/utils/broker.py"
    click PromYML "https://github.com/mher/flower/blob/master/prometheus.yml"
    click PromAlerts "https://github.com/mher/flower/blob/master/examples/prometheus-alerts.yaml"
```
