# tentens-tech/process-wrapper architecture

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

- Interactive diagram: https://gitdiagram.com/tentens-tech/process-wrapper
- Repository: https://github.com/tentens-tech/process-wrapper

## Overview

##### Project Type and Purpose
- This is a Go-based CLI/sidecar binary designed to run inside a container pod.
- It manages multiple child processes, handles their lifecycle and health checks, exposes liveness/readiness/metrics HTTP endpoints, and integrates with Kubernetes (kubelet), Prometheus, Elasticsearch, a metrics-server, Envoy, Google preemption metadata, and an optional shared-lock service.

a. Config Loader (pkg/config)
b. Process Manager & Probes (pkg/process)
- Child Process Spawner
- Health-Check Plugins (HTTP, TCP, exec, file, env, SQL, floating-PID, heartbeat)
- Stdout/Stderr Interceptor & Logfmt Formatter
- PostStart Hooks
c. Signal Handler (pkg/signals)
d. Lease Manager (pkg/lease)
- Shared-lock client/server, Etcd integration
e. Metrics & Stats (pkg/metrics, pkg/stat)
- Prometheus metrics endpoint
- UDP metrics-server client
- Elasticsearch event publisher
f. HTTP API Server (main.go + net/http)
- /liveness and /readiness endpoints
- /metrics and /prommerge endpoints
g. CLI Entry Point (main.go)

##### Architectural Patterns & Design Principles
- Monolithic binary with clear internal layering (config → core → HTTP/metrics)
- Plugin-style probes for extensibility
- Separation of concerns: config, process, signals, metrics, lease
- Use of standard Go concurrency primitives (goroutines, channels) for lifecycle control
- Sidecar pattern for container orchestration

##### Essential Elements Checklist
- Clear component labels
- Notes on key configurations (ENV variables, YAML config)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Kubelet(["Kubernetes Kubelet"]):::external
    Prometheus(["Prometheus Scraper"]):::external
    MetricsServer(["Metrics-Server (UDP)"]):::external
    Elasticsearch(["Elasticsearch"]):::external
    Envoy(["Envoy Admin API"]):::external
    GoogleMeta(["Google Metadata Service"]):::external
    SharedLockService(["Shared-Lock Service / etcd"]):::external
    ChildProc(["Child Processes"]):::external

    %% Process-Wrapper Monolith
    subgraph "Process-Wrapper" 
        direction TB
        ConfigLoader["Config Loader"]:::config
        SignalHandler["Signal Handler"]:::signal
        LeaseManager["Lease Manager"]:::lease
        ProcessManager["Process Manager & Probes"]:::process
        MetricsHTTP["Metrics & HTTP API"]:::api
        CLIEntry["CLI Entry Point"]:::cli
    end

    %% Config Flow
    ConfigFile(["Config File"]):::configGray
    ConfigFile -->|"file I/O"| ConfigLoader

    %% Initialization
    CLIEntry -->|"init modules"| ConfigLoader
    CLIEntry -->|"init modules"| SignalHandler
    CLIEntry -->|"init modules"| LeaseManager
    CLIEntry -->|"init modules"| ProcessManager
    CLIEntry -->|"init modules"| MetricsHTTP

    %% Process Management
    ProcessManager -->|"spawn"| ChildProc
    ProcessManager <-->|"health-check (HTTP/TCP/...)"| ChildProc

    %% Signal Handling
    SignalHandler -->|"SIGTERM etc."| ProcessManager
    GoogleMeta -->|"preemption event"| SignalHandler
    SignalHandler -->|"drain URL (HTTP)"| Envoy

    %% HTTP API Endpoints
    MetricsHTTP -->|"HTTP /liveness & /readiness"| Kubelet
    MetricsHTTP -->|"HTTP /metrics"| Prometheus
    MetricsHTTP -->|"HTTP /prommerge"| Prometheus

    %% Metrics & Stats
    MetricsHTTP -->|"UDP metrics"| MetricsServer
    MetricsHTTP -->|"HTTP/JSON events"| Elasticsearch

    %% Lease Management
    LeaseManager <-->|"gRPC/etcd"| SharedLockService

    %% Click Events for Component Mapping
    click ConfigLoader "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/config/config.go"
    click ConfigLoader "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/config/file.go"
    click ConfigLoader "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/config/json_env.go"
    click ConfigLoader "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/config/string.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/process.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/container_state.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/duration.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/process_stats.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/health.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/hook.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_http.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_tcp.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_exec.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_file.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_env.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_mysql.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_amqp.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_floating_pid.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_heartbeat.go"
    click ProcessManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/process/probe_lock.go"
    click SignalHandler "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/signals/signals.go"
    click LeaseManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/lease/handlers/lease.go"
    click LeaseManager "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/lease/lock/lock.go"
    click MetricsHTTP "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/metrics/metrics.go"
    click MetricsHTTP "https://github.com/tentens-tech/process-wrapper/blob/main/pkg/stat/stat.go"
    click CLIEntry "https://github.com/tentens-tech/process-wrapper/blob/main/main.go"

    %% Styles
    classDef config fill:#f9f,stroke:#333,stroke-width:1px
    classDef signal fill:#cfc,stroke:#333,stroke-width:1px
    classDef lease fill:#cff,stroke:#333,stroke-width:1px
    classDef process fill:#cfc,stroke:#333,stroke-width:1px
    classDef api fill:#ccf,stroke:#333,stroke-width:1px
    classDef cli fill:#eee,stroke:#333,stroke-width:1px
    classDef external fill:#fff,stroke-dasharray: 5 5,stroke:#666,stroke-width:1px
    classDef configGray fill:#ddd,stroke:#333,stroke-width:1px
```
