# labulakalia/crocodile architecture

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

- Interactive diagram: https://gitdiagram.com/labulakalia/crocodile
- Repository: https://github.com/labulakalia/crocodile

## Overview

##### Main Components
- Scheduler Center: This is the heart of the application (see core/cmd/server.go and related modules). It handles scheduling tasks, managing system state, and interacting with other components.
- Worker Nodes: Represent nodes (see core/cmd/client.go and Dockerfile.worker) that receive tasks via gRPC calls from the scheduling center and execute them. They also push real-time logs back.
- Frontend Web UI: Located under the “web” directory, it provides a rich client interface for task management (creating, editing, deleting, cloning tasks) and viewing logs.
- Database and Cache: The system uses MySQL (SQL schema in sql/) for persistent storage and Redis for handling real-time data such as task states, logs, and locks.
- Notification & Alarm: Based on the “common/notify” directory, this module integrates with various external alarm platforms (email, WeChat, DingDing, Slack, Telegram, etc.) for custom notifications.
- Security Components: The project supports certificate-based authentication and access tokens (see core/cert and common/jwt) to encrypt communications and control access.
- Supporting Utilities: Common modules for database operations (common/db), logging (common/log), error groups (common/errgroup), and utilities (common/utils) provide cross-cutting functionality.

##### Relationships and Interactions
- The Web UI communicates (typically using RESTful API calls, routed via core/router/api/v1) with the Scheduler Center to submit and control tasks.
- The Scheduler Center uses gRPC (core/middleware/grpcmidd.go and core/schedule/grpc.go) to interact with multiple Worker nodes.
- Worker nodes report back real-time task logs to the Scheduler Center.
- Both Scheduler and Worker nodes access shared resources like MySQL (persistent task and user data) and Redis (caching and real-time status).
- Security and Certificate modules ensure that communication between Scheduler and Worker nodes is encrypted and authenticated.
- Notification modules trigger alerts based on the task execution outcomes, utilizing integrations with multiple external services.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project clearly separates the concerns by modularizing scheduling (core), task execution (worker/client), frontend (web), and common/utility libraries.
- Distributed Design: The system supports multiple dispatch centers to avoid single points of failure. Worker nodes are designed to scale and be discovered automatically.
- Extensibility: The notification module includes different subdirectories for multiple platforms, indicating a plug-in or extensible notification strategy.
- Secure Communication: Use of JWT authentication, TLS certificates, and secure communication channels is emphasized.

##### Relevant Technologies/Frameworks and Their Roles
- Golang is used for the core logic and backend services.
- gRPC is the communication protocol between scheduling centers and worker nodes.
- MySQL and Redis are the underlying persistence and caching systems.
- A modern JavaScript framework (Vue.js is indicated by the .vue files) is used for building a rich web UI.
- Docker and Docker Compose facilitate container deployment, as indicated by the Dockerfiles and docker-compose.yml.

##### Additional Elements to Capture
- Modular structure from “core”, “common”, and “web” directories to indicate that you are capturing low-level details such as business logic, middleware, and request routing.
- Certificate and JWT authentication modules as part of the secure connection between distributed components.
- Mention that logs, task state, and scheduling strategies (random, rotation, worker weight, minimum worker number) are key parts of how the Scheduler Center interacts with Worker Nodes.

- The Web Frontend (user interaction layer)
- The Scheduler Center (core scheduling and control logic)
- Multiple Worker Nodes (distributed task execution)
- Data Stores (MySQL for persistent data and Redis for caching/locks)
- Security layers (JWT and certificate-based authentication)
- Notification services (integrated external services for alerts)
- Communication channels (gRPC and REST)

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        WebUI("Web Frontend"):::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Schedule("Scheduler Center (调度中心)"):::backend
        Worker("Worker Nodes"):::backend
        Security("Security Layer"):::security
        subgraph "Supporting Utilities"
            UtilsDB("DB Utils"):::utility
            UtilsLog("Log Utils"):::utility
            UtilsErr("Errgroup Utils"):::utility
            UtilsCommon("Common Utils"):::utility
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        MySQL("MySQL Database"):::database
        Redis("Redis Cache"):::cache
    end

    %% Notification Layer
    subgraph "Notification Layer"
        Notify("Notification/Alert System"):::notification
    end

    %% External Services
    subgraph "External Services"
        External("External Alarm Platforms"):::external
    end

    %% Connections
    WebUI -->|"REST_API"| Schedule
    Schedule -->|"gRPC_TaskDispatch"| Worker
    Worker -->|"RealTime_Logs"| Schedule

    Schedule -->|"ReadWrite"| MySQL
    Worker -->|"ReadWrite"| MySQL

    Schedule -->|"CacheOps"| Redis
    Worker -->|"CacheOps"| Redis

    Schedule -->|"TriggerAlerts"| Notify
    Notify -->|"SendNotifications"| External

    Security ---|"Secures"| Schedule
    Security ---|"Secures"| Worker

    UtilsDB --- Schedule
    UtilsLog --- Schedule
    UtilsErr --- Schedule
    UtilsCommon --- Schedule

    %% Click Events for Components
    click Schedule "https://github.com/labulakalia/crocodile/blob/master/core/cmd/server.go"
    click Schedule "https://github.com/labulakalia/crocodile/blob/master/core/schedule/grpc.go"
    click Worker "https://github.com/labulakalia/crocodile/blob/master/core/cmd/client.go"
    click Worker "https://github.com/labulakalia/crocodile/blob/master/Dockerfile.worker"
    click WebUI "https://github.com/labulakalia/crocodile/tree/master/web/"
    click MySQL "https://github.com/labulakalia/crocodile/tree/master/sql/"
    click Redis "https://github.com/labulakalia/crocodile/blob/master/core/schedule/cache.go"
    click Notify "https://github.com/labulakalia/crocodile/tree/master/common/notify/"
    click Notify "https://github.com/labulakalia/crocodile/blob/master/core/alarm/alarm.go"
    click Security "https://github.com/labulakalia/crocodile/tree/master/core/cert/"
    click Security "https://github.com/labulakalia/crocodile/tree/master/common/jwt/"
    click UtilsDB "https://github.com/labulakalia/crocodile/tree/master/common/db/"
    click UtilsLog "https://github.com/labulakalia/crocodile/tree/master/common/log/"
    click UtilsErr "https://github.com/labulakalia/crocodile/tree/master/common/errgroup/"
    click UtilsCommon "https://github.com/labulakalia/crocodile/tree/master/common/utils/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef cache fill:#F5CBA7,stroke:#CA6F1E,stroke-width:2px;
    classDef notification fill:#D7BDE2,stroke:#7D3C98,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
    classDef security fill:#D6EAF8,stroke:#5499C7,stroke-width:2px;
    classDef utility fill:#F0B27A,stroke:#BA4A00,stroke-width:2px;
```
