# blackholll/loonflow architecture

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

- Interactive diagram: https://gitdiagram.com/blackholll/loonflow
- Repository: https://github.com/blackholll/loonflow

## Overview

##### Project type and purpose
- This is a full-stack workflow engine (“loonflow”) built on Django.
- It exposes HTTP/REST APIs for external systems (OA, CMDB, ITSM, etc.) and also bundles a React+Ant Design Pro frontend for ticket creation, handling, management, and workflow configuration.

##### File structure
- Top-level folders:
- apps/ – Django “apps” implementing domain modules (account, ticket, workflow, manage).
- service/ – a thin service-layer abstraction that encapsulates business logic (e.g., workflow_permission_service, ticket_base_service, etc.).
- loonflow/ – Django project settings, URL router, WSGI entry point.
- frontend/ – React/TypeScript SPA scaffolded with UmiJS/Ant Design Pro for user-facing UI.
- docker_compose_deploy/ – Docker Compose definitions and per-container Dockerfiles for web, task, base, MySQL, media.
- settings/ – Django settings modules for different environments.
- media/ & static/ – file storage for scripts, attachments, and static images.
- tests/ & apps/*/tests.py – unit/integration tests for models, views, services.

##### README for additional insights
- Two main subsystems:
a. Backend Engine (Django + service layer + MySQL + Redis)
b. Frontend UI (React + Ant Design Pro)
- Docker Compose orchestrates these components into containers: loonflow-web (uWSGI + Nginx), loonflow-task (worker), loonflow-mysql, loonflow-media (file volume), loonflow-base (common utilities).

a. Main components
- Frontend SPA (React/AntD Pro)
- Backend API Server (Django + uWSGI + Nginx)
- Business Logic Layer (service/* modules)
- Django Apps (account, ticket, workflow, manage)
- Data Store: MySQL
- Cache/Session: Redis
- File Storage: Media Container (scripts, attachments)
- Task Worker Container (loonflow-task)
- Docker Compose orchestrator
b. Relationships & interactions
- Frontend ↔︎ Backend over HTTPS/REST (login, CRUD on tickets, workflows, users)
- Backend (views) → Service Layer → Django ORM → MySQL
- Backend → Redis for locks, caching, CSRF/session management
- Task Worker polls Redis or DB for asynchronous tasks (e.g., scheduled reminders)
- Nginx (loonflow-web) routes external requests to uWSGI; serves static assets or proxies API calls
- Media container mounted into web + task containers for reading/writing scripts & attachments
c. Architectural patterns & design principles
- Layered architecture: Presentation (React UI), API/Controller (Django views), Service (service/*), Data Access (Django ORM)
- Modular apps in Django following “apps as modules” for separation of concerns
- Docker-based micro-containers for isolation of web, worker, database, media
- Config-as-code: settings modules, Dockerfiles, Compose YAML
d. Key technologies & frameworks
- Frontend: React, UmiJS, Ant Design Pro, TypeScript, Jest/Puppeteer for tests
- Backend: Django, Python, Django REST (views/format_response), uwsgi, Nginx
- Persistence: MySQL (loonflow-mysql), Django ORM
- Caching/Queue: Redis (redis_pool.py), service/redis_pool
- Orchestration: Docker Compose, individual Dockerfiles (loonflow-web, loonflow-task, loonflow-base)
- Documentation: Sphinx

##### Capturing essential architectural elements
- Entry points: manage.py → wsgi.py → Django URL router → views.
- How static files and media are served (e.g., Nginx → static/, media/).
- Don’t overload—focus on separation into:
- Frontend
- API Gateway (Nginx+uWSGI)
- Django Application (Views + Services + ORM)
- Data Stores (MySQL, Redis, Media)
- Asynchronous Worker

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["React SPA"]:::frontend
    end

    %% API Gateway
    FE -->|"HTTPS/REST"| NGINX["Nginx + uWSGI (API Gateway)"]:::infra

    %% Backend Layer
    subgraph "Backend Layer"
        DJANGO_PROJECT["Django Project"]:::backend
        DJANGO_VIEWS["Django Views (API Controllers)"]:::backend
        SERVICE["Service Layer"]:::backend
        ORM["Django ORM"]:::backend
    end

    NGINX -->|"WSGI"| DJANGO_PROJECT
    DJANGO_PROJECT -->|"URL Routing"| DJANGO_VIEWS
    DJANGO_VIEWS -->|"calls"| SERVICE
    SERVICE -->|"ORM Calls"| ORM

    %% Data Stores
    ORM -->|"SQL"| MYSQL["MySQL"]:::datastore
    SERVICE -->|"Cache/Queue"| REDIS["Redis"]:::datastore
    DJANGO_VIEWS -->|"Read/Write"| MEDIA["Media Volume"]:::datastore

    %% Worker
    subgraph "Task Worker"
        WORKER["Task Worker"]:::infra
    end

    WORKER -->|"Polls"| ORM
    WORKER -->|"Polls"| REDIS
    WORKER -->|"Read/Write"| MEDIA

    %% Orchestration
    COMPOSE["Docker Compose"]:::infra
    COMPOSE -.-> NGINX
    COMPOSE -.-> WORKER
    COMPOSE -.-> MYSQL
    COMPOSE -.-> MEDIA

    %% Click Events
    click FE "https://github.com/blackholll/loonflow/tree/master/frontend/"
    click NGINX "https://github.com/blackholll/loonflow/blob/master/docker_compose_deploy/loonflow-web/nginx.conf"
    click DJANGO_PROJECT "https://github.com/blackholll/loonflow/blob/master/manage.py"
    click SERVICE "https://github.com/blackholll/loonflow/tree/master/service/"
    click REDIS "https://github.com/blackholll/loonflow/blob/master/service/redis_pool.py"
    click MYSQL "https://github.com/blackholll/loonflow/tree/master/docker_compose_deploy/loonflow-mysql/"
    click MEDIA "https://github.com/blackholll/loonflow/tree/master/docker_compose_deploy/loonflow-media/"
    click WORKER "https://github.com/blackholll/loonflow/tree/master/docker_compose_deploy/loonflow-task/Dockerfile"
    click COMPOSE "https://github.com/blackholll/loonflow/blob/master/docker_compose_deploy/docker-compose.yml"

    %% Styles
    classDef frontend fill:#C3DDF9,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#D6EFD8,stroke:#28a745,color:#28a745;
    classDef datastore fill:#FFE5B4,stroke:#d48806,color:#d48806;
    classDef infra fill:#E2E2E2,stroke:#6a737d,color:#6a737d;
```
