# bullygen/podmon architecture

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

- Interactive diagram: https://gitdiagram.com/bullygen/podmon
- Repository: https://github.com/bullygen/podmon

## Overview

Podmon is a LAN web dashboard for monitoring all containers belonging to the current rootless Podman user. The browser loads the dashboard and periodically requests host and container snapshots; the FastAPI service serves those cached results rather than polling Podman per request. A background collector refreshes container details, resource statistics, processes, and logs, then derives process-candidate and activity hints. The README documents search, container lifecycle details, logs, and optional host metrics. The sampled source shows the collector and parsing logic; dashboard markup and deployment wiring were not sampled.

Main entry points: [`service/app/main.py`](https://github.com/bullygen/podmon/blob/main/service/app/main.py) (Background collector), [`service/static/app.js`](https://github.com/bullygen/podmon/blob/main/service/static/app.js) (Dashboard UI), [`service/app/templates/index.html`](https://github.com/bullygen/podmon/blob/main/service/app/templates/index.html) (Dashboard page), [`service/app/host_metrics.py`](https://github.com/bullygen/podmon/blob/main/service/app/host_metrics.py) (Host metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
  node_page["Dashboard page<br/>[index.html]"]
end

subgraph group_service["Web service"]
  node_api["HTTP API<br/>[main.py]"]
  node_snapshot["Cached snapshot<br/>[main.py]"]
  node_logcache["Log cache<br/>[main.py]"]
end

subgraph group_collection["Collection and analysis"]
  node_collector["Background collector<br/>[main.py]"]
  node_host_metrics["Host metrics<br/>[host_metrics.py]"]
  node_models["Stats and process parsing<br/>[models.py]"]
  node_assessment["Process assessment<br/>[process_status.py]"]
end

subgraph group_integrations["Data sources"]
  node_podman_client["Podman client<br/>[podman_client.py]"]
end

node_browser(("LAN browser"))
node_podman(("Rootless Podman"))
node_host_files[("Read-only host files")]

node_browser -->|"opens dashboard"| node_page
node_page -->|"loads script"| node_dashboard
node_browser -->|"requests snapshots"| node_api
node_api -->|"reads cached data"| node_snapshot
node_api -->|"reads cached logs"| node_logcache
node_dashboard -->|"fetches updates"| node_api
node_collector -->|"writes snapshot"| node_snapshot
node_collector -->|"updates logs"| node_logcache
node_collector -->|"collects host data"| node_host_metrics
node_host_metrics -.->|"reads metrics"| node_host_files
node_collector -->|"requests container data"| node_podman_client
node_podman_client -->|"calls Unix socket API"| node_podman
node_collector -->|"parses stats and processes"| node_models
node_collector -->|"assesses activity"| node_assessment

click node_dashboard "https://github.com/bullygen/podmon/blob/main/service/static/app.js"
click node_page "https://github.com/bullygen/podmon/blob/main/service/app/templates/index.html"
click node_api "https://github.com/bullygen/podmon/blob/main/service/app/main.py"
click node_snapshot "https://github.com/bullygen/podmon/blob/main/service/app/main.py"
click node_logcache "https://github.com/bullygen/podmon/blob/main/service/app/main.py"
click node_collector "https://github.com/bullygen/podmon/blob/main/service/app/main.py"
click node_podman_client "https://github.com/bullygen/podmon/blob/main/service/app/podman_client.py"
click node_host_metrics "https://github.com/bullygen/podmon/blob/main/service/app/host_metrics.py"
click node_models "https://github.com/bullygen/podmon/blob/main/service/app/models.py"
click node_assessment "https://github.com/bullygen/podmon/blob/main/service/app/process_status.py"

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_dashboard,node_page,node_browser toneBlue
class node_api,node_snapshot,node_logcache,node_host_files toneAmber
class node_collector,node_host_metrics,node_models,node_assessment toneMint
class node_podman_client toneRose
class node_podman toneIndigo
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/bullygen/podmon/blob/main/service/static/app.js): `service/static/app.js`
- [Dashboard page](https://github.com/bullygen/podmon/blob/main/service/app/templates/index.html): `service/app/templates/index.html`

### Web service

- [HTTP API](https://github.com/bullygen/podmon/blob/main/service/app/main.py): `service/app/main.py`
- [Cached snapshot](https://github.com/bullygen/podmon/blob/main/service/app/main.py): `service/app/main.py`
- [Log cache](https://github.com/bullygen/podmon/blob/main/service/app/main.py): `service/app/main.py`

### Collection and analysis

- [Background collector](https://github.com/bullygen/podmon/blob/main/service/app/main.py): `service/app/main.py`
- [Host metrics](https://github.com/bullygen/podmon/blob/main/service/app/host_metrics.py): `service/app/host_metrics.py`
- [Stats and process parsing](https://github.com/bullygen/podmon/blob/main/service/app/models.py): `service/app/models.py`
- [Process assessment](https://github.com/bullygen/podmon/blob/main/service/app/process_status.py): `service/app/process_status.py`

### Data sources

- [Podman client](https://github.com/bullygen/podmon/blob/main/service/app/podman_client.py): `service/app/podman_client.py`

### Other components

- **LAN browser**
- **Rootless Podman**
- **Read-only host files**

## Connections

- LAN browser → Dashboard page: opens dashboard
- Dashboard page → Dashboard UI: loads script
- LAN browser → HTTP API: requests snapshots
- HTTP API → Cached snapshot: reads cached data
- HTTP API → Log cache: reads cached logs
- Dashboard UI → HTTP API: fetches updates
- Background collector → Cached snapshot: writes snapshot
- Background collector → Log cache: updates logs
- Background collector → Host metrics: collects host data
- Host metrics → Read-only host files: reads metrics
- Background collector → Podman client: requests container data
- Podman client → Rootless Podman: calls Unix socket API
- Background collector → Stats and process parsing: parses stats and processes
- Background collector → Process assessment: assesses activity