Architecture

Architecture

Trove is a push-based inventory and health catalogue.

The system has three main parts:

1. agents that collect local platform state
2. a central server that accepts reports and stores them
3. dashboard/API/background workers that read from the stored catalog

There is no server-to-agent control channel.

High-level flow

Docker / Kubernetes / Proxmox / local systemd
        |
        | read-only collection
        v
Trove agent
        |
        | POST /api/v1/report
        | Authorization: Bearer trove_...
        v
Trove server
        |
        | ApplyReport transaction
        v
SQLite
        |
        +--> dashboard and read APIs
        +--> activity feed
        +--> alert engine
        +--> email digest
        +--> freshness checks
        +--> staleness loop

Agents produce full-state snapshots. The server does not ingest deltas. This makes reports idempotent and safe to retry.

If a report is lost, the next report replaces the server view with the current truth for that host.

Push model

The push model is one of Trove's most important design decisions.

The server never needs credentials for Docker, Kubernetes, Proxmox, or remote hosts. Each agent carries only the read-only credentials it needs for the platform it observes.

Benefits:

• works behind NAT
• works across homelab networks without inbound holes
• keeps platform credentials local to the agent environment
• avoids a central management plane with broad control rights
• makes agent compromise less useful because the server cannot send commands back

Server responsibilities

The server is responsible for:

• authenticating report pushes by bearer token
• validating the report structure
• applying the report to SQLite in one transaction
• recording state, health, and agent events
• serving read-only dashboard APIs
• serving the embedded web dashboard
• deriving stale/offline agent state
• resolving image freshness through registry digests
• sending instant alerts
• sending scheduled email digests
• pruning old events and removed services

The server package holds HTTP wiring and background loops. SQL lives in internal/store.

Agent responsibilities

Agents are responsible for:

• reading platform state with read-only APIs
• mapping platform-specific objects into Trove's common model
• pushing full snapshots on an interval
• reporting their platform, version, and interval

Agents do not decide whether something is stale. Staleness is derived by the server from last_seen_at and the reported interval.

Full-state reporting

A report describes one host snapshot:

{
  "agent": {
    "name": "docker-nuc01",
    "platform": "docker",
    "version": "0.13.0",
    "interval_seconds": 30
  },
  "host": {
    "hostname": "nuc01",
    "meta": {
      "docker.version": "...",
      "docker.api_version": "..."
    }
  },
  "services": []
}

A multi-host platform, such as Proxmox, sends one report per discovered host. The reports share the same agent identity.

The server correlates services by:

• authenticated agent
• host name
• service external_id

Background loops

trove-server runs several background loops beside the HTTP server.

Loop	Default cadence	Purpose
Staleness	10 seconds	Marks agents stale/offline and flags their services as stale.
Freshness	5 minutes	Checks registry digests for images due a refresh.
Maintenance	hourly	Prunes old events and old removed-service rows.
Alert engine	30 seconds	Reads events and sends configured instant alerts.
Digest	1 minute check	Sends scheduled email digests when due.

Each loop is supervised in the server entrypoint so a panic in one loop does not intentionally take down the HTTP server.

Read-only boundary

Trove is read-only in two places:

1. Agent platform access is read-only.
2. Server APIs are read-only except authenticated report ingest and local CLI administration.

The one write path from the network is:

POST /api/v1/report

That endpoint requires a valid Trove agent bearer token.

Data ownership

SQLite is the source of truth for the current catalog and event history.

The schema is intentionally small:

• agents
• hosts
• services
• events
• image_checks
• alert_state
• alert_channel_deliveries
• meta

See Data-Model for the schema details.