# release-argus/argus architecture

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

- Interactive diagram: https://gitdiagram.com/release-argus/argus
- Repository: https://github.com/release-argus/argus

## Overview

Argus monitors configured software sources for version changes, tracks latest and deployed versions, and can notify recipients or invoke webhooks and commands. Its main user-facing workflow is configuring services, reviewing approvals in the web UI, and responding to detected changes. The Go runtime also provides authentication/RBAC, persistence, WebSockets, and Prometheus metrics. The graph combines documented capabilities with relationships visible in the supplied excerpts and SOURCE INDEX; unsampled implementation details are omitted or shown only where documented.

Main entry points: [`service/status/status.go`](https://github.com/release-argus/argus/blob/master/service/status/status.go) (Service tracking), [`cmd/argus/main.go`](https://github.com/release-argus/argus/blob/master/cmd/argus/main.go) (Application runtime), [`service/latest_version/servicemap.go`](https://github.com/release-argus/argus/blob/master/service/latest_version/servicemap.go) (Latest version lookup), [`web/api/v1/http-api-service.go`](https://github.com/release-argus/argus/blob/master/web/api/v1/http-api-service.go) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and configuration"]
  node_main["Application runtime<br/>[main.go]"]
  node_config["Configuration<br/>[settings.go]"]
  node_database[("SQLite persistence<br/>[handlers.go]")]
  node_log["Logging<br/>[log.go]"]
end

subgraph group_monitor["Release monitoring"]
  node_tracking["Service tracking<br/>[status.go]"]
  node_latest["Latest version lookup<br/>[servicemap.go]"]
  node_github["GitHub releases<br/>[query.go]"]
  node_forgejo["Forgejo releases<br/>[query.go]"]
  node_websource["Custom URL lookup<br/>[query.go]"]
  node_deployed["Deployed version lookup<br/>[servicemap.go]"]
  node_manual["Manual version<br/>[query.go]"]
  node_webdeployed["URL version<br/>[query.go]"]
end

subgraph group_actions["Change actions"]
  node_actions["Change handling<br/>[handlers.go]"]
  node_notifications["Notifications<br/>[verify.go]"]
  node_webhooks["Webhooks<br/>[send.go]"]
  node_commands["Commands<br/>[init.go]"]
end

subgraph group_web["Web application"]
  node_webserver["Web server<br/>[web.go]"]
  node_api["HTTP API"]
  node_ui["React interface<br/>[App.tsx]"]
  node_websocket["WebSocket updates"]
  node_metrics["Prometheus metrics<br/>[prometheus.go]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication and RBAC<br/>[auth.go]"]
  node_sessions["Session management<br/>[session.go]"]
end

node_operator(("Operator"))
node_release_sources(("Release sources"))
node_recipients(("Notification recipients"))

node_operator -->|"configures and reviews"| node_ui
node_main -->|"loads"| node_config
node_main -->|"initializes"| node_database
node_main -->|"starts"| node_webserver
node_main -->|"starts tracking"| node_tracking
node_tracking -.->|"queries"| node_latest
node_latest -->|"dispatches"| node_github
node_latest -->|"dispatches"| node_forgejo
node_latest -->|"dispatches"| node_websource
node_github -->|"requests releases"| node_release_sources
node_forgejo -->|"requests releases"| node_release_sources
node_websource -->|"requests URL"| node_release_sources
node_tracking -.->|"tracks deployed version"| node_deployed
node_deployed -->|"dispatches"| node_manual
node_deployed -->|"dispatches"| node_webdeployed
node_manual -.->|"persists changes"| node_database
node_tracking -->|"records status"| node_database
node_tracking -->|"provides status"| node_metrics
node_actions -->|"sends"| node_notifications
node_actions -->|"sends"| node_webhooks
node_actions -->|"executes"| node_commands
node_notifications -->|"notifies"| node_recipients
node_webhooks -->|"posts changes"| node_recipients
node_webserver -->|"routes requests"| node_api
node_api -.->|"serves interface"| node_ui
node_api -.->|"authorizes"| node_auth
node_auth -->|"manages sessions"| node_sessions
node_ui -.->|"calls"| node_api
node_websocket -.->|"pushes updates"| node_ui
node_metrics -.->|"exposes metrics"| node_operator

click node_main "https://github.com/release-argus/argus/blob/master/cmd/argus/main.go"
click node_config "https://github.com/release-argus/argus/blob/master/config/settings.go"
click node_database "https://github.com/release-argus/argus/blob/master/db/handlers.go"
click node_log "https://github.com/release-argus/argus/blob/master/internal/logx/log.go"
click node_tracking "https://github.com/release-argus/argus/blob/master/service/status/status.go"
click node_latest "https://github.com/release-argus/argus/blob/master/service/latest_version/servicemap.go"
click node_github "https://github.com/release-argus/argus/blob/master/service/latest_version/types/github/query.go"
click node_forgejo "https://github.com/release-argus/argus/blob/master/service/latest_version/types/forgejo/query.go"
click node_websource "https://github.com/release-argus/argus/blob/master/service/latest_version/types/web/query.go"
click node_deployed "https://github.com/release-argus/argus/blob/master/service/deployed_version/servicemap.go"
click node_manual "https://github.com/release-argus/argus/blob/master/service/deployed_version/types/manual/query.go"
click node_webdeployed "https://github.com/release-argus/argus/blob/master/service/deployed_version/types/web/query.go"
click node_actions "https://github.com/release-argus/argus/blob/master/service/handlers.go"
click node_notifications "https://github.com/release-argus/argus/blob/master/notify/shoutrrr/verify.go"
click node_webhooks "https://github.com/release-argus/argus/blob/master/webhook/send.go"
click node_commands "https://github.com/release-argus/argus/blob/master/command/init.go"
click node_webserver "https://github.com/release-argus/argus/blob/master/web/web.go"
click node_api "https://github.com/release-argus/argus/blob/master/web/api/v1/http-api-service.go"
click node_ui "https://github.com/release-argus/argus/blob/master/web/ui/react-app/src/App.tsx"
click node_websocket "https://github.com/release-argus/argus/blob/master/web/api/v1/websocket-client.go"
click node_metrics "https://github.com/release-argus/argus/blob/master/web/metric/prometheus.go"
click node_auth "https://github.com/release-argus/argus/blob/master/auth/auth.go"
click node_sessions "https://github.com/release-argus/argus/blob/master/auth/session/session.go"

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_main,node_config,node_database,node_log toneBlue
class node_tracking,node_latest,node_github,node_forgejo,node_websource,node_deployed,node_manual,node_webdeployed toneAmber
class node_actions,node_notifications,node_webhooks,node_commands toneMint
class node_webserver,node_api,node_ui,node_websocket,node_metrics toneRose
class node_auth,node_sessions,node_operator,node_release_sources,node_recipients toneIndigo
```

## Components

### Runtime and configuration

- [Application runtime](https://github.com/release-argus/argus/blob/master/cmd/argus/main.go): `cmd/argus/main.go`
- [Configuration](https://github.com/release-argus/argus/blob/master/config/settings.go): `config/settings.go`
- [SQLite persistence](https://github.com/release-argus/argus/blob/master/db/handlers.go): `db/handlers.go`
- [Logging](https://github.com/release-argus/argus/blob/master/internal/logx/log.go): `internal/logx/log.go`

### Release monitoring

- [Service tracking](https://github.com/release-argus/argus/blob/master/service/status/status.go): `service/status/status.go`
- [Latest version lookup](https://github.com/release-argus/argus/blob/master/service/latest_version/servicemap.go): `service/latest_version/servicemap.go`
- [GitHub releases](https://github.com/release-argus/argus/blob/master/service/latest_version/types/github/query.go): `service/latest_version/types/github/query.go`
- [Forgejo releases](https://github.com/release-argus/argus/blob/master/service/latest_version/types/forgejo/query.go): `service/latest_version/types/forgejo/query.go`
- [Custom URL lookup](https://github.com/release-argus/argus/blob/master/service/latest_version/types/web/query.go): `service/latest_version/types/web/query.go`
- [Deployed version lookup](https://github.com/release-argus/argus/blob/master/service/deployed_version/servicemap.go): `service/deployed_version/servicemap.go`
- [Manual version](https://github.com/release-argus/argus/blob/master/service/deployed_version/types/manual/query.go): `service/deployed_version/types/manual/query.go`
- [URL version](https://github.com/release-argus/argus/blob/master/service/deployed_version/types/web/query.go): `service/deployed_version/types/web/query.go`

### Change actions

- [Change handling](https://github.com/release-argus/argus/blob/master/service/handlers.go): `service/handlers.go`
- [Notifications](https://github.com/release-argus/argus/blob/master/notify/shoutrrr/verify.go): `notify/shoutrrr/verify.go`
- [Webhooks](https://github.com/release-argus/argus/blob/master/webhook/send.go): `webhook/send.go`
- [Commands](https://github.com/release-argus/argus/blob/master/command/init.go): `command/init.go`

### Web application

- [Web server](https://github.com/release-argus/argus/blob/master/web/web.go): `web/web.go`
- [HTTP API](https://github.com/release-argus/argus/blob/master/web/api/v1/http-api-service.go): `web/api/v1/http-api-service.go`
- [React interface](https://github.com/release-argus/argus/blob/master/web/ui/react-app/src/App.tsx): `web/ui/react-app/src/App.tsx`
- [WebSocket updates](https://github.com/release-argus/argus/blob/master/web/api/v1/websocket-client.go): `web/api/v1/websocket-client.go`
- [Prometheus metrics](https://github.com/release-argus/argus/blob/master/web/metric/prometheus.go): `web/metric/prometheus.go`

### Identity and access

- [Authentication and RBAC](https://github.com/release-argus/argus/blob/master/auth/auth.go): `auth/auth.go`
- [Session management](https://github.com/release-argus/argus/blob/master/auth/session/session.go): `auth/session/session.go`

### Other components

- **Operator**
- **Release sources**
- **Notification recipients**

## Connections

- Operator → React interface: configures and reviews (evidence: `README.md`)
- Application runtime → Configuration: loads (evidence: `cmd/argus/main.go`)
- Application runtime → SQLite persistence: initializes (evidence: `cmd/argus/main.go`)
- Application runtime → Web server: starts (evidence: `cmd/argus/main.go`)
- Application runtime → Service tracking: starts tracking (evidence: `cmd/argus/main.go`)
- Service tracking → Latest version lookup: queries
- Latest version lookup → GitHub releases: dispatches (evidence: `service/latest_version/servicemap.go`)
- Latest version lookup → Forgejo releases: dispatches (evidence: `service/latest_version/servicemap.go`)
- Latest version lookup → Custom URL lookup: dispatches (evidence: `service/latest_version/servicemap.go`)
- GitHub releases → Release sources: requests releases (evidence: `service/latest_version/types/github/query.go`)
- Forgejo releases → Release sources: requests releases (evidence: `service/latest_version/types/forgejo/query.go`)
- Custom URL lookup → Release sources: requests URL (evidence: `service/latest_version/types/web/query.go`)
- Service tracking → Deployed version lookup: tracks deployed version
- Deployed version lookup → Manual version: dispatches (evidence: `service/deployed_version/servicemap.go`)
- Deployed version lookup → URL version: dispatches (evidence: `service/deployed_version/servicemap.go`)
- Manual version → SQLite persistence: persists changes
- Service tracking → SQLite persistence: records status (evidence: `service/status/status.go`)
- Service tracking → Prometheus metrics: provides status (evidence: `service/status/status.go`)
- Change handling → Notifications: sends (evidence: `service/handlers.go`)
- Change handling → Webhooks: sends (evidence: `service/handlers.go`)
- Change handling → Commands: executes (evidence: `service/handlers.go`)
- Notifications → Notification recipients: notifies (evidence: `README.md`)
- Webhooks → Notification recipients: posts changes (evidence: `README.md`)
- Web server → HTTP API: routes requests (evidence: `web/web.go`)
- HTTP API → React interface: serves interface
- HTTP API → Authentication and RBAC: authorizes
- Authentication and RBAC → Session management: manages sessions (evidence: `auth/auth.go`)
- React interface → HTTP API: calls
- WebSocket updates → React interface: pushes updates
- Prometheus metrics → Operator: exposes metrics
