# ogarcia/sysdweb architecture

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

- Interactive diagram: https://gitdiagram.com/ogarcia/sysdweb
- Repository: https://github.com/ogarcia/sysdweb

## Overview

1. **What this repo is**
   - `sysdweb` is a small Python application that exposes **systemd service control** through both a **web UI** and a **REST API**.
   - It is intended to run locally or on a host where it can talk to the systemd daemon over its D-Bus interface.

2. **Top-level runtime shape**
   - `run.py` is the likely command-line entrypoint, while `sysdweb/main.py` appears to hold the main startup flow.
   - The app listens on a configurable host/port, defaulting to `127.0.0.1:10088`, so it behaves like a self-contained local admin service rather than a distributed backend.

3. **Configuration subsystem**
   - `sysdweb/config.py` is the boundary for reading runtime settings and the service registry.
   - `sysdweb.conf` defines named service sections; each section maps a human-friendly title to a systemd unit name, and those section keys become the service IDs used in API paths.

4. **HTTP server layer**
   - `sysdweb/server.py` is the request-routing layer that serves both HTML pages and API endpoints.
   - The API follows a fixed pattern: `/api/v1/<service>/<action>` with optional journal line limits, and the server is responsible for translating requests into service operations and serializing responses.

5. **systemd integration layer**
   - `sysdweb/systemd.py` is the core integration boundary to the host systemd environment.
   - It is where start/stop/restart/reload/status/journal operations are executed, and the README indicates it relies on system D-Bus communication and systemd development libraries.

6. **Data flow for control actions**
   - A request comes in through the HTTP server, the target service key is resolved from config, then the systemd layer executes the requested action.
   - For control actions, the response is simple and machine-oriented: `OK`/`Fail` for mutating operations, and state strings such as `active`, `inactive`, `failed`, or `not-found` for status.

7. **Journal retrieval path**
   - The `journal` action is a separate read path that returns tail lines from the service’s logs, with a default of 100 lines and optional override in the URL.
   - This means the app is not only a service controller, but also a lightweight service-log viewer for systemd units.

8. **Web UI layer**
   - `sysdweb/templates/views/index.tpl` and `journal.tpl` define the HTML views for the browser interface.
   - The browser UI is complemented by `sysdweb/templates/static/js/sysdweb.js` and `css/sysdweb.css`, implying client-side interactions for triggering actions and refreshing service/journal views without manual API use.

9. **Static asset boundary**
   - The `templates/static` tree contains the front-end assets only; the backend remains responsible for all actual systemd interaction.
   - This keeps the presentation layer thin: it renders views and calls the same server endpoints that external clients use.

10. **Deployment and operations**
   - `systemd/sysdweb-system.service` and `systemd/sysdweb-user.service` provide native systemd unit files for running sysdweb either as a system service or per-user service.
   - This matches the app’s local-admin nature: it is itself typically launched and managed by systemd, and then manages other systemd units.

11. **Packaging and distribution**
   - `pyproject.toml` plus `.github/workflows/python-publish.yml` indicate the project is packaged and published as a Python distribution.
   - The repository is structured for installation from source or PyPI, with CI automation focused on release publication.

12. **Architectural summary**
   - The key boundary is: **HTTP/UI layer on one side, systemd D-Bus control on the other**.
   - The config file connects the two by defining which named services are exposed, and the server exposes those services consistently through both browser pages and a stable REST API.

Main entry points: [`sysdweb/server.py`](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/server.py) (server), [`sysdweb/main.py`](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/main.py) (main), [`sysdweb/systemd.py`](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/systemd.py) (systemd), [`sysdweb/templates/views/index.tpl`](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/views/index.tpl) (index view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_runpy["run.py<br/>entrypoint<br/>[run.py]"]
  node_main["main<br/>startup<br/>[main.py]"]
  node_server["server<br/>http router<br/>[server.py]"]
end

subgraph group_core["Core"]
  node_config["config<br/>settings<br/>[config.py]"]
  node_conf["sysdweb.conf<br/>service registry<br/>[sysdweb.conf]"]
  node_systemd["systemd<br/>control layer<br/>[systemd.py]"]
end

subgraph group_ui["UI"]
  node_indexview["index view<br/>html template<br/>[index.tpl]"]
  node_journalview["journal view<br/>html template<br/>[journal.tpl]"]
  node_js["sysdweb.js<br/>client script<br/>[sysdweb.js]"]
  node_css["sysdweb.css<br/>style<br/>[sysdweb.css]"]
end

subgraph group_ops["Ops"]
  node_serviceunit["system service<br/>unit file"]
  node_userunit["user service<br/>unit file"]
  node_pyproject["pyproject<br/>package metadata<br/>[pyproject.toml]"]
  node_workflow["publish workflow<br/>ci release<br/>[python-publish.yml]"]
end

node_runpy -->|"starts"| node_main
node_main -->|"loads"| node_config
node_main -->|"binds"| node_server
node_config -->|"reads"| node_conf
node_server -->|"uses"| node_config
node_server -->|"controls"| node_systemd
node_server -->|"renders"| node_indexview
node_server -->|"renders"| node_journalview
node_indexview -->|"uses"| node_js
node_journalview -->|"uses"| node_js
node_indexview -->|"styles"| node_css
node_journalview -->|"styles"| node_css
node_js -->|"calls"| node_server
node_systemd -.->|"deployed by"| node_serviceunit
node_systemd -.->|"deployed by"| node_userunit
node_pyproject -.->|"published by"| node_workflow

click node_runpy "https://github.com/ogarcia/sysdweb/blob/master/run.py"
click node_main "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/main.py"
click node_server "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/server.py"
click node_config "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/config.py"
click node_conf "https://github.com/ogarcia/sysdweb/blob/master/sysdweb.conf"
click node_systemd "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/systemd.py"
click node_indexview "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/views/index.tpl"
click node_journalview "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/views/journal.tpl"
click node_js "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/static/js/sysdweb.js"
click node_css "https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/static/css/sysdweb.css"
click node_serviceunit "https://github.com/ogarcia/sysdweb/blob/master/systemd/sysdweb-system.service"
click node_userunit "https://github.com/ogarcia/sysdweb/blob/master/systemd/sysdweb-user.service"
click node_pyproject "https://github.com/ogarcia/sysdweb/blob/master/pyproject.toml"
click node_workflow "https://github.com/ogarcia/sysdweb/blob/master/.github/workflows/python-publish.yml"

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_runpy,node_main,node_server toneBlue
class node_config,node_conf,node_systemd toneAmber
class node_indexview,node_journalview,node_js,node_css toneMint
class node_serviceunit,node_userunit,node_pyproject,node_workflow toneRose
```

## Components

### Runtime

Application startup and request handling

- [run.py](https://github.com/ogarcia/sysdweb/blob/master/run.py): entrypoint · CLI launch script · `run.py`
- [main](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/main.py): startup · App startup flow · `sysdweb/main.py`
- [server](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/server.py): http router · Web UI and API routing · `sysdweb/server.py`

### Core

Configuration and systemd control

- [config](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/config.py): settings · Loads runtime settings and service registry · `sysdweb/config.py`
- [sysdweb.conf](https://github.com/ogarcia/sysdweb/blob/master/sysdweb.conf): service registry · Named service definitions · `sysdweb.conf`
- [systemd](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/systemd.py): control layer · systemd D-Bus integration · `sysdweb/systemd.py`

### UI

Browser views and static assets

- [index view](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/views/index.tpl): html template · Main service dashboard · `sysdweb/templates/views/index.tpl`
- [journal view](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/views/journal.tpl): html template · Service log page · `sysdweb/templates/views/journal.tpl`
- [sysdweb.js](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/static/js/sysdweb.js): client script · Browser-side interactions · `sysdweb/templates/static/js/sysdweb.js`
- [sysdweb.css](https://github.com/ogarcia/sysdweb/blob/master/sysdweb/templates/static/css/sysdweb.css): style · UI styling · `sysdweb/templates/static/css/sysdweb.css`

### Ops

Packaging and service units

- [system service](https://github.com/ogarcia/sysdweb/blob/master/systemd/sysdweb-system.service): unit file · System-wide service unit · `systemd/sysdweb-system.service`
- [user service](https://github.com/ogarcia/sysdweb/blob/master/systemd/sysdweb-user.service): unit file · Per-user service unit · `systemd/sysdweb-user.service`
- [pyproject](https://github.com/ogarcia/sysdweb/blob/master/pyproject.toml): package metadata · Build and distribution config · `pyproject.toml`
- [publish workflow](https://github.com/ogarcia/sysdweb/blob/master/.github/workflows/python-publish.yml): ci release · Package publishing automation · `.github/workflows/python-publish.yml`

## Connections

- run.py → main: starts · CLI entrypoint launches the app
- main → config: loads · Startup reads runtime configuration
- main → server: binds · Initializes the HTTP server
- config → sysdweb.conf: reads · Service registry comes from config file
- server → config: uses · Resolves configured service IDs
- server → systemd: controls · Routes actions to systemd operations
- server → index view: renders · Serves the main browser page
- server → journal view: renders · Serves the journal page
- index view → sysdweb.js: uses · UI interactions are driven by client script
- journal view → sysdweb.js: uses · Journal page reuses browser script
- index view → sysdweb.css: styles · Main view is styled by shared CSS
- journal view → sysdweb.css: styles · Journal view is styled by shared CSS
- sysdweb.js → server: calls · Browser actions hit the same endpoints
- systemd → system service: deployed by · System service packaging
- systemd → user service: deployed by · User service packaging
- pyproject → publish workflow: published by · Release automation packages the project