# whyour/qinglong architecture

> Architecture diagram of the GitHub repository whyour/qinglong, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whyour/qinglong
- Repository: https://github.com/whyour/qinglong

## Overview

Qinglong is a web-based timed-task management platform for Python, JavaScript, Shell, and TypeScript scripts. Users manage scripts, environment variables, configuration, and scheduled tasks in the web panel, then inspect task logs and system status; scheduled work is executed by the backend. The repository also provides a remote CLI for managing panel resources and tasks. The tree and README establish these product areas, but sampled source is limited, so links between backend subsystems are shown only where their ownership is reasonably clear.

Main entry points: [`back/api/index.ts`](https://github.com/whyour/qinglong/blob/develop/back/api/index.ts) (API routes), [`src/pages`](https://github.com/whyour/qinglong/tree/develop/src/pages) (Management pages), [`src/app.ts`](https://github.com/whyour/qinglong/blob/develop/src/app.ts) (Web application), [`src/utils/http.tsx`](https://github.com/whyour/qinglong/blob/develop/src/utils/http.tsx) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_panel["Web panel"]
  node_web["Web application<br/>[app.ts]"]
  node_pages["Management pages"]
  node_http["HTTP client<br/>[http.tsx]"]
end

subgraph group_backend["Backend services"]
  node_routes["API routes<br/>[index.ts]"]
  node_api_tasks["Task API<br/>[cron.ts]"]
  node_api_scripts["Script API<br/>[script.ts]"]
  node_api_env["Environment API<br/>[env.ts]"]
  node_api_subscriptions["Subscription API<br/>[subscription.ts]"]
  node_api_open["Open API<br/>[open.ts]"]
  node_api_system["System APIs<br/>[system.ts]"]
  node_task_service["Task services<br/>[cron.ts]"]
  node_script_service["Script services<br/>[script.ts]"]
  node_subscription_service["Subscription services<br/>[subscription.ts]"]
  node_runtime_data["Runtime data<br/>[index.ts]"]
  node_database[("Database<br/>[database.ts]")]
end

subgraph group_execution["Task execution"]
  node_scheduler["Scheduler<br/>[schedule.ts]"]
  node_cron_runner["Cron runner<br/>[runCron.ts]"]
  node_language_runner["Script runner<br/>[runner.ts]"]
  node_log_reader["Task logs<br/>[logReader.ts]"]
end

subgraph group_remote["Remote CLI"]
  node_remote_cli["Remote commands<br/>[remote.ts]"]
  node_remote_dispatch["Command dispatch<br/>[dispatch.ts]"]
  node_remote_client["Remote API client<br/>[client.ts]"]
end

node_operator(("Panel operator"))
node_remote_user(("Remote CLI user"))
node_panel_api["Panel API"]

node_operator -->|"uses"| node_web
node_web -->|"renders"| node_pages
node_pages -->|"requests"| node_http
node_http -->|"calls"| node_routes
node_routes -->|"dispatches"| node_api_tasks
node_routes -->|"dispatches"| node_api_scripts
node_routes -->|"dispatches"| node_api_env
node_routes -->|"dispatches"| node_api_subscriptions
node_routes -->|"dispatches"| node_api_open
node_routes -->|"dispatches"| node_api_system
node_api_tasks -->|"handles"| node_task_service
node_api_scripts -->|"handles"| node_script_service
node_api_subscriptions -->|"handles"| node_subscription_service
node_task_service -->|"uses"| node_runtime_data
node_scheduler -->|"runs"| node_cron_runner
node_cron_runner -->|"executes"| node_language_runner
node_remote_user -->|"invokes"| node_remote_cli
node_remote_cli -->|"dispatches"| node_remote_dispatch
node_remote_dispatch -->|"calls"| node_remote_client
node_remote_client -->|"requests"| node_panel_api
node_panel_api -->|"serves"| node_routes
node_pages -->|"views logs"| node_log_reader

click node_web "https://github.com/whyour/qinglong/blob/develop/src/app.ts"
click node_pages "https://github.com/whyour/qinglong/tree/develop/src/pages"
click node_http "https://github.com/whyour/qinglong/blob/develop/src/utils/http.tsx"
click node_routes "https://github.com/whyour/qinglong/blob/develop/back/api/index.ts"
click node_api_tasks "https://github.com/whyour/qinglong/blob/develop/back/api/cron.ts"
click node_api_scripts "https://github.com/whyour/qinglong/blob/develop/back/api/script.ts"
click node_api_env "https://github.com/whyour/qinglong/blob/develop/back/api/env.ts"
click node_api_subscriptions "https://github.com/whyour/qinglong/blob/develop/back/api/subscription.ts"
click node_api_open "https://github.com/whyour/qinglong/blob/develop/back/api/open.ts"
click node_api_system "https://github.com/whyour/qinglong/blob/develop/back/api/system.ts"
click node_task_service "https://github.com/whyour/qinglong/blob/develop/back/services/cron.ts"
click node_script_service "https://github.com/whyour/qinglong/blob/develop/back/services/script.ts"
click node_subscription_service "https://github.com/whyour/qinglong/blob/develop/back/services/subscription.ts"
click node_runtime_data "https://github.com/whyour/qinglong/blob/develop/back/data/index.ts"
click node_database "https://github.com/whyour/qinglong/blob/develop/back/bootstrap/database.ts"
click node_scheduler "https://github.com/whyour/qinglong/blob/develop/back/services/schedule.ts"
click node_cron_runner "https://github.com/whyour/qinglong/blob/develop/back/shared/runCron.ts"
click node_language_runner "https://github.com/whyour/qinglong/blob/develop/cli/src/internal/execution/runner.ts"
click node_log_reader "https://github.com/whyour/qinglong/blob/develop/back/shared/logReader.ts"
click node_remote_cli "https://github.com/whyour/qinglong/blob/develop/cli/src/entrypoints/remote.ts"
click node_remote_dispatch "https://github.com/whyour/qinglong/blob/develop/cli/src/remote/commands/dispatch.ts"
click node_remote_client "https://github.com/whyour/qinglong/blob/develop/cli/src/remote/api/client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_pages,node_http,node_remote_user toneBlue
class node_routes,node_api_tasks,node_api_scripts,node_api_env,node_api_subscriptions,node_api_open,node_api_system,node_task_service,node_script_service,node_subscription_service,node_runtime_data,node_database toneAmber
class node_scheduler,node_cron_runner,node_language_runner,node_log_reader,node_panel_api toneMint
class node_remote_cli,node_remote_dispatch,node_remote_client toneRose
class node_operator toneIndigo
```

## Components

### Web panel

- [Web application](https://github.com/whyour/qinglong/blob/develop/src/app.ts): `src/app.ts`
- [Management pages](https://github.com/whyour/qinglong/tree/develop/src/pages): `src/pages`
- [HTTP client](https://github.com/whyour/qinglong/blob/develop/src/utils/http.tsx): `src/utils/http.tsx`

### Backend services

- [API routes](https://github.com/whyour/qinglong/blob/develop/back/api/index.ts): `back/api/index.ts`
- [Task API](https://github.com/whyour/qinglong/blob/develop/back/api/cron.ts): `back/api/cron.ts`
- [Script API](https://github.com/whyour/qinglong/blob/develop/back/api/script.ts): `back/api/script.ts`
- [Environment API](https://github.com/whyour/qinglong/blob/develop/back/api/env.ts): `back/api/env.ts`
- [Subscription API](https://github.com/whyour/qinglong/blob/develop/back/api/subscription.ts): `back/api/subscription.ts`
- [Open API](https://github.com/whyour/qinglong/blob/develop/back/api/open.ts): `back/api/open.ts`
- [System APIs](https://github.com/whyour/qinglong/blob/develop/back/api/system.ts): `back/api/system.ts`
- [Task services](https://github.com/whyour/qinglong/blob/develop/back/services/cron.ts): `back/services/cron.ts`
- [Script services](https://github.com/whyour/qinglong/blob/develop/back/services/script.ts): `back/services/script.ts`
- [Subscription services](https://github.com/whyour/qinglong/blob/develop/back/services/subscription.ts): `back/services/subscription.ts`
- [Runtime data](https://github.com/whyour/qinglong/blob/develop/back/data/index.ts): `back/data/index.ts`
- [Database](https://github.com/whyour/qinglong/blob/develop/back/bootstrap/database.ts): `back/bootstrap/database.ts`

### Task execution

- [Scheduler](https://github.com/whyour/qinglong/blob/develop/back/services/schedule.ts): `back/services/schedule.ts`
- [Cron runner](https://github.com/whyour/qinglong/blob/develop/back/shared/runCron.ts): `back/shared/runCron.ts`
- [Script runner](https://github.com/whyour/qinglong/blob/develop/cli/src/internal/execution/runner.ts): `cli/src/internal/execution/runner.ts`
- [Task logs](https://github.com/whyour/qinglong/blob/develop/back/shared/logReader.ts): `back/shared/logReader.ts`

### Remote CLI

- [Remote commands](https://github.com/whyour/qinglong/blob/develop/cli/src/entrypoints/remote.ts): `cli/src/entrypoints/remote.ts`
- [Command dispatch](https://github.com/whyour/qinglong/blob/develop/cli/src/remote/commands/dispatch.ts): `cli/src/remote/commands/dispatch.ts`
- [Remote API client](https://github.com/whyour/qinglong/blob/develop/cli/src/remote/api/client.ts): `cli/src/remote/api/client.ts`

### Other components

- **Panel operator**
- **Remote CLI user**
- **Panel API**

## Connections

- Panel operator → Web application: uses
- Web application → Management pages: renders
- Management pages → HTTP client: requests
- HTTP client → API routes: calls
- API routes → Task API: dispatches
- API routes → Script API: dispatches
- API routes → Environment API: dispatches
- API routes → Subscription API: dispatches
- API routes → Open API: dispatches
- API routes → System APIs: dispatches
- Task API → Task services: handles
- Script API → Script services: handles
- Subscription API → Subscription services: handles
- Task services → Runtime data: uses
- Scheduler → Cron runner: runs
- Cron runner → Script runner: executes
- Remote CLI user → Remote commands: invokes
- Remote commands → Command dispatch: dispatches
- Command dispatch → Remote API client: calls
- Remote API client → Panel API: requests
- Panel API → API routes: serves
- Management pages → Task logs: views logs