# openspug/spug architecture

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

- Interactive diagram: https://gitdiagram.com/openspug/spug
- Repository: https://github.com/openspug/spug

## Overview

1. **Repository shape**
   - This is a split-stack project: `spug_api` is the backend control plane, and `spug_web` is a React single-page admin console.
   - The product is an **agentless operations platform**: the backend talks to managed hosts primarily over SSH, while the browser talks to the backend over HTTP and WebSocket.

2. **Backend framework boundary**
   - `spug_api` is a Django 2.2 application with the usual split between `settings.py`, `urls.py`, `wsgi.py`, and `asgi.py`.
   - The presence of `consumer/` and `spug/routing.py` shows that the backend also serves **real-time channels** for terminal/output streams, not just REST APIs.

3. **Core domain subsystems**
   - The backend is organized into Django apps by domain: `host`, `exec`, `deploy`, `schedule`, `monitor`, `alarm`, `config`, `repository`, `file`, `account`, `setting`, `notify`, and `home`.
   - Each app typically contains its own `models.py`, `views.py`, `urls.py`, and supporting `utils.py` or helper modules, so the architecture is modular but still monolithic at deploy time.

4. **Host management and SSH operations**
   - `apps/host` is the inventory and grouping layer: host CRUD, group management, import/sync, and host detail views.
   - Low-level host interaction is centralized in `libs/ssh.py`, `libs/channel.py`, and related helpers, which are used by terminal, file transfer, command execution, and deployment flows.

5. **Interactive execution and file transfer**
   - `apps/exec` implements batch command execution and file transfer workflows.
   - It has dedicated background execution pieces (`executors.py`, `transfer.py`) and a worker command (`management/commands/runworker.py`), indicating asynchronous job execution with streamed output back to the UI.

6. **Deployment and repository management**
   - `apps/repository` manages source repositories and repository metadata.
   - `apps/deploy` coordinates application release flows, including deployment requests, helper utilities, and workflow/state logic.
   - `libs/gitlib.py` and filesystem paths under `spug_api/repos/` suggest local checkout/build staging is part of the deployment pipeline.

7. **Scheduling and monitoring loops**
   - `apps/schedule` and `apps/monitor` each have their own scheduler/executor modules plus dedicated startup commands (`runscheduler.py`, `runmonitor.py`).
   - This implies separate background processes for periodic task orchestration and monitoring checks rather than running everything in the web request process.

8. **Alerting and notifications**
   - `apps/alarm` models alarm rules, and `apps/notify` is the delivery/notification layer.
   - `libs/mail.py` and `libs/push.py` show external notification channels, which likely receive events from monitoring, scheduling, or deployment failures.

9. **Configuration center**
   - `apps/config` manages application/environment/service configuration, including diffing, version/history, and rendering helpers.
   - On the frontend this is one of the larger feature areas, which matches the backend being a distinct domain with its own data model and views.

10. **Identity, permissions, and system settings**
    - `apps/account` and `apps/setting` handle users, roles, permissions, login history, security settings, and integration settings.
    - `libs/ldap.py` indicates optional LDAP integration for enterprise authentication.
    - This layer is the main authorization boundary for all other modules.

11. **Frontend structure**
    - `spug_web` mirrors backend domains one-for-one in `src/pages/`, with separate page folders for host, exec, deploy, schedule, monitor, alarm, config, system, and ssh.
    - Shared UI composition lives in `src/layout/` and reusable widgets in `src/components/`.
    - `src/libs/http.js` is the API client layer, and `src/routes.js` defines the navigation structure.

12. **Client-server interaction pattern**
    - Most pages use page-local `store.js` files, suggesting each feature page owns its own data fetching and state wiring.
    - The UI appears to load data via REST endpoints and subscribe to live execution/terminal updates via WebSocket where needed.

13. **Runtime/process model**
    - The backend is not a single process: there are explicit startup scripts for API, worker, scheduler, monitor, and WebSocket services under `spug_api/tools/`.
    - Docker and supervisor configs in `docs/docker/` and `tools/supervisor-spug.ini` show the app is designed to run as multiple cooperating services behind Nginx and Redis.

14. **Storage and operational boundaries**
    - Persistent data is split between the database-backed Django models, local filesystem areas for logs/repo/build artifacts/transfer files, and external systems like SSH targets and notification providers.
    - `spug_api/logs/`, `spug_api/repos/`, and `spug_api/storage/transfer/` indicate that runtime artifacts are intentionally kept outside the request path.

15. **Architecture summary for a diagram**
    - A good diagram would show: browser SPA → Django API → domain apps/models → background workers/schedulers/monitors → SSH-managed hosts and external services.
    - Add a separate real-time path from backend consumers/WebSocket routing back to the browser for terminal output, exec logs, and task progress.

Main entry points: [`spug_api/apps`](https://github.com/openspug/spug/tree/3.0/spug_api/apps) (Domain apps), [`spug_api/apps/exec`](https://github.com/openspug/spug/tree/3.0/spug_api/apps/exec) (Exec), [`spug_api/apps/deploy`](https://github.com/openspug/spug/tree/3.0/spug_api/apps/deploy) (Deploy), [`spug_api/libs`](https://github.com/openspug/spug/tree/3.0/spug_api/libs) (Core libs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_api_root["Django app<br/>backend entrypoint"]
  node_api_urls["URL map<br/>HTTP routing<br/>[urls.py]"]
  node_api_settings["Settings<br/>configuration<br/>[settings.py]"]
  node_api_apps["Domain apps<br/>modular monolith"]
  node_api_host["Hosts<br/>inventory domain"]
  node_api_exec["Exec<br/>job domain"]
  node_api_deploy["Deploy<br/>release domain"]
  node_api_config["Config"]
  node_api_schedmon["Schedule/Monitor<br/>background domains"]
  node_api_alarm_notify["Alarm/Notify<br/>alerting domain"]
  node_api_account_setting["Identity/Settings<br/>authz domain"]
  node_api_libs["Core libs<br/>integration helpers"]
end

subgraph group_frontend["Frontend"]
  node_web_spa["SPA<br/>React admin app<br/>[App.js]"]
  node_web_routes["Routes<br/>navigation map<br/>[routes.js]"]
  node_web_layout["Layout<br/>shell UI<br/>[index.js]"]
  node_web_http["HTTP client<br/>API client<br/>[http.js]"]
  node_web_pages["Feature pages<br/>page modules"]
end

subgraph group_runtime["Runtime"]
  node_api_consumer["WebSocket consumer<br/>realtime channels<br/>[consumers.py]"]
  node_workers["Workers<br/>processes"]
  node_repo_fs["Repo storage<br/>filesystem staging"]
end

subgraph group_external["External systems"]
  node_hosts[("Managed hosts<br/>ssh targets")]
  node_services[("External services<br/>providers")]
end

node_web_spa -->|"navigates"| node_web_routes
node_web_spa -->|"uses"| node_web_layout
node_web_spa -->|"calls API"| node_web_http
node_web_routes -->|"maps to"| node_web_pages
node_web_layout -->|"hosts"| node_web_pages
node_web_pages -->|"fetches data"| node_web_http
node_api_root -->|"routes"| node_api_urls
node_api_root -->|"configures"| node_api_settings
node_api_urls -->|"dispatches to"| node_api_apps
node_api_apps -->|"contains"| node_api_host
node_api_apps -->|"contains"| node_api_exec
node_api_apps -->|"contains"| node_api_deploy
node_api_apps -->|"contains"| node_api_config
node_api_apps -->|"contains"| node_api_schedmon
node_api_apps -->|"contains"| node_api_alarm_notify
node_api_apps -->|"contains"| node_api_account_setting
node_api_host -->|"uses"| node_api_libs
node_api_exec -->|"streams"| node_api_consumer
node_api_exec -->|"uses"| node_api_libs
node_api_deploy -->|"stages in"| node_repo_fs
node_api_deploy -->|"uses"| node_api_libs
node_api_config -->|"uses"| node_api_libs
node_api_schedmon -->|"runs as"| node_workers
node_api_consumer -->|"served by"| node_workers
node_api_account_setting -->|"auth/integrates"| node_services
node_api_alarm_notify -->|"notifies via"| node_services
node_api_exec -->|"executes on"| node_hosts
node_api_deploy -->|"deploys to"| node_hosts
node_api_host -->|"tracks"| node_hosts

click node_web_spa "https://github.com/openspug/spug/blob/3.0/spug_web/src/App.js"
click node_web_routes "https://github.com/openspug/spug/blob/3.0/spug_web/src/routes.js"
click node_web_layout "https://github.com/openspug/spug/blob/3.0/spug_web/src/layout/index.js"
click node_web_http "https://github.com/openspug/spug/blob/3.0/spug_web/src/libs/http.js"
click node_web_pages "https://github.com/openspug/spug/tree/3.0/spug_web/src/pages"
click node_api_root "https://github.com/openspug/spug/tree/3.0/spug_api/spug"
click node_api_urls "https://github.com/openspug/spug/blob/3.0/spug_api/spug/urls.py"
click node_api_settings "https://github.com/openspug/spug/blob/3.0/spug_api/spug/settings.py"
click node_api_apps "https://github.com/openspug/spug/tree/3.0/spug_api/apps"
click node_api_host "https://github.com/openspug/spug/tree/3.0/spug_api/apps/host"
click node_api_exec "https://github.com/openspug/spug/tree/3.0/spug_api/apps/exec"
click node_api_deploy "https://github.com/openspug/spug/tree/3.0/spug_api/apps/deploy"
click node_api_config "https://github.com/openspug/spug/tree/3.0/spug_api/apps/config"
click node_api_schedmon "https://github.com/openspug/spug/tree/3.0/spug_api/apps/schedule"
click node_api_alarm_notify "https://github.com/openspug/spug/tree/3.0/spug_api/apps/alarm"
click node_api_account_setting "https://github.com/openspug/spug/tree/3.0/spug_api/apps/account"
click node_api_consumer "https://github.com/openspug/spug/blob/3.0/spug_api/consumer/consumers.py"
click node_api_libs "https://github.com/openspug/spug/tree/3.0/spug_api/libs"
click node_workers "https://github.com/openspug/spug/tree/3.0/spug_api/tools"
click node_repo_fs "https://github.com/openspug/spug/tree/3.0/spug_api/repos"

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_api_root,node_api_urls,node_api_settings,node_api_apps,node_api_host,node_api_exec,node_api_deploy,node_api_config,node_api_schedmon,node_api_alarm_notify,node_api_account_setting,node_api_libs toneBlue
class node_web_spa,node_web_routes,node_web_layout,node_web_http,node_web_pages toneAmber
class node_api_consumer,node_workers,node_repo_fs toneMint
class node_hosts,node_services toneRose
```

## Components

### Backend

Django control plane, domain apps, and runtime workers.

- [Django app](https://github.com/openspug/spug/tree/3.0/spug_api/spug): backend entrypoint · Main Django project wiring settings, URLs, WSGI, ASGI, and routing. · `spug_api/spug`
- [URL map](https://github.com/openspug/spug/blob/3.0/spug_api/spug/urls.py): HTTP routing · Top-level request routing into domain apps and APIs. · `spug_api/spug/urls.py`
- [Settings](https://github.com/openspug/spug/blob/3.0/spug_api/spug/settings.py): configuration · Global Django and deployment configuration. · `spug_api/spug/settings.py`
- [Domain apps](https://github.com/openspug/spug/tree/3.0/spug_api/apps): modular monolith · Django apps for host, exec, deploy, schedule, monitor, alarm, config, repository, file, account, setting, notify, home, app, and APIs. · `spug_api/apps`
- [Hosts](https://github.com/openspug/spug/tree/3.0/spug_api/apps/host): inventory domain · Host inventory, grouping, import/sync, and host detail operations. · `spug_api/apps/host`
- [Exec](https://github.com/openspug/spug/tree/3.0/spug_api/apps/exec): job domain · Batch command execution and file transfer workflows with streamed output. · `spug_api/apps/exec`
- [Deploy](https://github.com/openspug/spug/tree/3.0/spug_api/apps/deploy): release domain · Deployment requests, workflow coordination, and release state handling. · `spug_api/apps/deploy`
- [Config](https://github.com/openspug/spug/tree/3.0/spug_api/apps/config): configuration domain · Application, environment, and service configuration management with versioning and diffs. · `spug_api/apps/config`
- [Schedule/Monitor](https://github.com/openspug/spug/tree/3.0/spug_api/apps/schedule): background domains · Periodic scheduling and monitoring loops with dedicated executors and startup commands. · `spug_api/apps/schedule`
- [Alarm/Notify](https://github.com/openspug/spug/tree/3.0/spug_api/apps/alarm): alerting domain · Alarm rules and notification delivery hooks. · `spug_api/apps/alarm`
- [Identity/Settings](https://github.com/openspug/spug/tree/3.0/spug_api/apps/account): authz domain · Users, roles, permissions, security settings, login history, and integration settings. · `spug_api/apps/account`
- [Core libs](https://github.com/openspug/spug/tree/3.0/spug_api/libs): integration helpers · Shared SSH, git, LDAP, mail, push, channel, parser, and middleware helpers. · `spug_api/libs`

### Frontend

React SPA and shared UI layers.

- [SPA](https://github.com/openspug/spug/blob/3.0/spug_web/src/App.js): React admin app · Browser-based operations console for all major product domains. · `spug_web/src/App.js`
- [Routes](https://github.com/openspug/spug/blob/3.0/spug_web/src/routes.js): navigation map · Declares client-side navigation and page entry points. · `spug_web/src/routes.js`
- [Layout](https://github.com/openspug/spug/blob/3.0/spug_web/src/layout/index.js): shell UI · Shared shell for header, sidebar, notifications, and page framing. · `spug_web/src/layout/index.js`
- [HTTP client](https://github.com/openspug/spug/blob/3.0/spug_web/src/libs/http.js): API client · Central browser-to-backend request layer. · `spug_web/src/libs/http.js`
- [Feature pages](https://github.com/openspug/spug/tree/3.0/spug_web/src/pages): page modules · Domain-oriented page folders for host, exec, deploy, schedule, monitor, alarm, config, system, ssh, and home. · `spug_web/src/pages`

### Runtime

Background processes and real-time channels.

- [WebSocket consumer](https://github.com/openspug/spug/blob/3.0/spug_api/consumer/consumers.py): realtime channels · Terminal and output streaming handlers for browser-connected live updates. · `spug_api/consumer/consumers.py`
- [Workers](https://github.com/openspug/spug/tree/3.0/spug_api/tools): processes · Separate runtime processes for API, worker, scheduler, monitor, and WebSocket services. · `spug_api/tools`
- [Repo storage](https://github.com/openspug/spug/tree/3.0/spug_api/repos): filesystem staging · Local checkout, build, logs, and transfer storage used by repository and deployment flows. · `spug_api/repos`

### External systems

Managed hosts and third-party services the platform integrates with.

- **Managed hosts**: ssh targets · Remote machines operated through SSH rather than an installed agent.
- **External services**: providers · Redis, LDAP, email/push providers, and other integrated services.

## Connections

- SPA → Routes: navigates · Client-side route structure drives the SPA.
- SPA → Layout: uses · Pages render inside the shared application shell.
- SPA → HTTP client: calls API · All feature pages communicate with backend endpoints through the HTTP client.
- Routes → Feature pages: maps to · Navigation points into domain page modules.
- Layout → Feature pages: hosts · Page content is framed by common UI chrome.
- Feature pages → HTTP client: fetches data · Feature pages load and mutate backend state through the API layer.
- Django app → URL map: routes · Top-level Django URL configuration dispatches requests to apps.
- Django app → Settings: configures · Project entrypoint loads framework settings.
- URL map → Domain apps: dispatches to · Requests are routed into domain apps and API modules.
- Domain apps → Hosts: contains · Host inventory and grouping features.
- Domain apps → Exec: contains · Command execution and transfer features.
- Domain apps → Deploy: contains · Deployment workflow features.
- Domain apps → Config: contains · Configuration management features.
- Domain apps → Schedule/Monitor: contains · Scheduling and monitoring features.
- Domain apps → Alarm/Notify: contains · Alerting and notification features.
- Domain apps → Identity/Settings: contains · Identity, permissions, and system settings.
- Hosts → Core libs: uses · Host operations rely on shared SSH and helper code.
- Exec → WebSocket consumer: streams · Execution and transfer output is pushed over real-time channels.
- Exec → Core libs: uses · Batch execution and file transfer depend on SSH/channel helpers.
- Deploy → Repo storage: stages in · Deployment work uses local repository/build artifacts.
- Deploy → Core libs: uses · Release workflows rely on git and filesystem helpers.
- Config → Core libs: uses · Config rendering and comparison reuse shared helpers.
- Schedule/Monitor → Workers: runs as · Scheduling and monitoring are executed by dedicated background processes.
- WebSocket consumer → Workers: served by · WebSocket endpoints run as a separate service process.
- Identity/Settings → External services: auth/integrates · Authentication, login, and security settings integrate with external providers.
- Alarm/Notify → External services: notifies via · Alerts can be delivered through mail or push integrations.
- Exec → Managed hosts: executes on · Commands and transfers target managed hosts over SSH.
- Deploy → Managed hosts: deploys to · Release flows operate against remote hosts.
- Hosts → Managed hosts: tracks · Inventory records represent managed hosts.
