# servicer-labs/servicer architecture

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

- Interactive diagram: https://gitdiagram.com/servicer-labs/servicer
- Repository: https://github.com/servicer-labs/servicer

## Overview

##### Project Type and Purpose
- This is a Rust-based Command Line Interface (CLI) tool called “servicer” for managing systemd services on Linux.
- Its primary job is to let users create, control, and monitor services by generating/editing .service files and invoking systemd commands.

##### File Structure
- Top-level:
- Cargo.toml / Cargo.lock: Rust project metadata and dependencies.
- README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE: documentation.
- snapcraft.yaml: packaging descriptor.
- .github/workflows/release.yml: CI/CD pipeline.
- src/main.rs: CLI entrypoint where arguments are parsed and dispatched.
- src/handlers/: one Rust file per CLI sub-command (create, start, stop, status, logs, edit, rename, delete, etc.).
- src/utils/: shared utility modules for path resolution, systemd interaction, process status, etc.

##### README for Additional Insights
- The tool never runs as a daemon—each command is a standalone process invoked via sudo.
- It relies on native systemd primitives (unit files, journald logs) and invokes systemctl (or D-Bus) under the hood.
- It supports service file templating, environment variables, interpreters, and auto-restart policies.

a. Main Components
- CLI Frontend (main.rs + argument parser)
- Command Handlers (src/handlers/*)
- Utility Layer (src/utils/*)
- Systemd API (systemctl CLI or D-Bus)
- File System (.service files under /etc/systemd/system/)
- Journald (system logging daemon)
- Operating System Kernel (process management)
b. Relationships & Data Flow
1. User types `ser <command> [args]` → CLI Frontend
2. Frontend selects appropriate handler module
3. Handler uses utility functions to:
– Read/write .service files (File System)
– Invoke systemd commands (systemctl or D-Bus)
– Query service status (process & resource usage)
4. systemd applies the operation, manages the service process
5. Journald captures log output from the service unit
6. CLI fetches logs via journalctl and prints to user
c. Architectural Patterns & Principles
- Modular command dispatch (one handler per action)
- Separation of concerns: CLI parsing vs. service logic vs. system interactions
- Stateless execution: each invocation reads state from disk/systemd and exits
- Leverage native OS primitives (no embedded daemon)
d. Key Technologies
- Rust (cargo, modules, structs)
- systemctl CLI or systemd D-Bus API
- journald / journalctl
- File I/O for .service files
- Snapcraft for packaging

##### Detail
- Handler as a sub-block under “Handlers.”
- Utils layer broken out into “Path Resolver,” “Service Actions,” “Process Status,” “Systemd Interaction.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    User["User Terminal"]:::external

    %% CLI Application
    subgraph "CLI Application"
        Frontend["CLI Frontend"]:::frontend
        CommandHandlers["Command Handlers"]:::handlers
        UtilsLayer["Utility Layer"]:::utils
    end

    %% Handlers Sub-components
    subgraph "Command Handlers"
        CreateService["Create Service Handler"]:::handler
        DeleteService["Delete Service Handler"]:::handler
        DisableService["Disable Service Handler"]:::handler
        EditService["Edit Service File Handler"]:::handler
        EnableService["Enable Service Handler"]:::handler
        PrintPaths["Print Paths Handler"]:::handler
        PrintServiceFile["Print Service File Handler"]:::handler
        ReloadService["Reload Service Handler"]:::handler
        RenameService["Rename Service Handler"]:::handler
        ShowLogs["Show Logs Handler"]:::handler
        ShowStatus["Show Status Handler"]:::handler
        StartService["Start Service Handler"]:::handler
        StopService["Stop Service Handler"]:::handler
    end

    %% Utils Sub-components
    subgraph "Utility Layer"
        PathResolver["Binary Path Resolver"]:::util
        ServiceActions["Service File Management"]:::util
        ProcessStatus["Service Status & Process Queries"]:::util
        SystemdInteraction["Systemd API Integration"]:::util
        ServiceNames["Service Name Handling & Validation"]:::util
    end

    %% External Systems and Storage
    FileSystem["/etc/systemd/system/ (.service files)"]:::storage
    SystemdDaemon["Systemd Daemon"]:::external
    Journald["Journald (Logs)"]:::external

    %% Side Components
    Snapcraft["Packaging Descriptor"]:::side
    GitHubActions["CI/CD Pipeline"]:::side
    CargoMeta["Project Metadata"]:::side
    Documentation["Documentation & Licensing"]:::side

    %% Connections
    User -->|"invoke CLI"| Frontend
    Frontend -->|"dispatch command"| CommandHandlers

    CommandHandlers -->|"resolve paths"| PathResolver
    CommandHandlers -->|"manage .service files"| ServiceActions
    CommandHandlers -->|"query status"| ProcessStatus
    CommandHandlers -->|"invoke systemd"| SystemdInteraction
    CommandHandlers -->|"validate names"| ServiceNames

    ServiceActions -->|"read/write files"| FileSystem
    SystemdInteraction -->|"call systemctl/D-Bus"| SystemdDaemon
    ProcessStatus -->|"proc stats"| SystemdDaemon
    ShowLogs -->|"journalctl"| Journald
    Journald -->|"return logs"| ShowLogs

    %% Side component links
    Frontend --> Snapcraft
    Frontend --> GitHubActions
    Frontend --> CargoMeta
    Frontend --> Documentation

    %% Click Events
    click Frontend "https://github.com/servicer-labs/servicer/blob/master/src/main.rs"
    click CommandHandlers "https://github.com/servicer-labs/servicer/tree/master/src/handlers/"
    click UtilsLayer "https://github.com/servicer-labs/servicer/tree/master/src/utils/"
    click SystemdInteraction "https://github.com/servicer-labs/servicer/blob/master/src/utils/systemd.rs"
    click ServiceActions "https://github.com/servicer-labs/servicer/blob/master/src/utils/service_actions.rs"
    click ProcessStatus "https://github.com/servicer-labs/servicer/blob/master/src/utils/process_status.rs"
    click PathResolver "https://github.com/servicer-labs/servicer/blob/master/src/utils/find_binary_path.rs"
    click ServiceNames "https://github.com/servicer-labs/servicer/blob/master/src/utils/service_names.rs"
    click ShowLogs "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_show_logs.rs"
    click ShowStatus "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_show_status.rs"
    click CreateService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_create_service.rs"
    click EditService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_edit_service_file.rs"
    click RenameService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_rename_service.rs"
    click DeleteService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_delete_service.rs"
    click ReloadService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_reload_service.rs"
    click EnableService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_enable_service.rs"
    click DisableService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_disable_service.rs"
    click StartService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_start_service.rs"
    click StopService "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_stop_service.rs"
    click PrintPaths "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_print_paths.rs"
    click PrintServiceFile "https://github.com/servicer-labs/servicer/blob/master/src/handlers/handle_print_service_file.rs"
    click Snapcraft "https://github.com/servicer-labs/servicer/blob/master/snapcraft.yaml"
    click GitHubActions "https://github.com/servicer-labs/servicer/blob/master/.github/workflows/release.yml"
    click CargoMeta "https://github.com/servicer-labs/servicer/blob/master/Cargo.toml"
    click Documentation "https://github.com/servicer-labs/servicer/blob/master/README.md"

    %% Styles
    classDef external fill:#d0f0c0,stroke:#2f6627,color:#000
    classDef frontend fill:#add8e6,stroke:#036, color:#000
    classDef handlers fill:#e0ffff,stroke:#017, color:#000
    classDef handler fill:#e0ffff,stroke:#017,color:#000
    classDef utils fill:#fffacd,stroke:#aa6, color:#000
    classDef util fill:#fffacd,stroke:#aa6, color:#000
    classDef storage fill:#ffa500,stroke:#a45, color:#000
    classDef side fill:#d3d3d3,stroke:#888, color:#000
```
