# Architecture Summary

## Overview

This stack uses **Traefik v3** as the internet-facing ingress for application and operations UIs. Service routing is primarily label-driven from Docker Compose files, with a shared `traefik` bridge network for reverse-proxied traffic and a `monitor` network for internal telemetry components.

TLS is terminated at Traefik using ACME HTTP challenge (`myresolver`), with additional hardening via:

- a default middleware chain (security headers, CrowdSec bouncer, error pages),
- Authelia forward-auth middleware on selected routes,
- mTLS TLS options (`mtls-private-admin`) on private-admin endpoints.

## Network / Request Flow

```mermaid
flowchart LR
  C[Internet Client] -->|80/443| T[Traefik Ingress]
  T -->|HTTP->HTTPS redirect| T
  T -->|ACME HTTP challenge| LE[Let's Encrypt ACME]

  subgraph TraefikNet["Docker network: traefik (172.21.0.0 slash 16)"]
    A[Authelia]
    CS[CrowdSec LAPI]
    EP[Error Pages]

    NC[Nextcloud]
    PB[Passbolt]
    GT[Gitea]
    GW[Gramps Web]
    SX[SearXNG]

    GF[Grafana]
    PR[Prometheus]
    NR[Node-RED]
    PT[Portainer]
    UK[Uptime Kuma]
    IF[InfluxDB]
    GO[Gotify]
  end

  T -->|forwardAuth for selected services| A
  T -->|plugin decisions| CS
  T -->|4xx/5xx middleware| EP

  T --> NC
  T --> PB
  T --> GT
  T --> GW
  T --> SX

  T --> GF
  T --> PR
  T --> NR
  T --> PT
  T --> UK
  T --> IF
  T --> GO

  subgraph MonitorNet[Docker network: monitor]
    NE[Node Exporter]
    TE[Telegraf]
    DE[Docker Update Exporter]
    PE[Pi-hole Exporter]
    DSP[Docker Socket Proxy]
  end

  PR --> NE
  PR --> TE
  PR --> DE
  PR --> PE
  PR --> UK
  PR -->|remote scrape| RH[Remote Hosts]
  TE --> DSP
  NR --> DSP
  PT --> DSP
  T --> DSP
```

## Key Components

- **Ingress & security plane:** Traefik, Authelia, CrowdSec, Error Pages.
- **User-facing applications:** Nextcloud, Passbolt, Gitea, Gramps Web (Family Tree), SearXNG.
- **Monitoring/ops:** Prometheus, Grafana, InfluxDB, Node-RED, Uptime Kuma, Portainer, Gotify.
- **Support plane:** Docker Socket Proxy (shared Docker API gateway for Traefik/automation/ops tools).

## Remote Hosts Observed

Prometheus scrape targets indicate additional infrastructure outside the local Compose deployment, including hostnames for:

- `raspberrypi.tail13f623.ts.net`
- `pve.sweet.home`
- `pbs.sweet.home`
- `pihole`
- `server`
- `nix-cache`
- `kuma.lan.ddnsgeek.com`

## Runtime Inventory Input

Prometheus runtime inventory snapshots are exported with `scripts/export_prometheus_inventory.py` and committed under `docs/runtime/`. The latest human-readable summary is in [docs/prometheus-inventory.md](prometheus-inventory.md).

These artifacts are an observed-runtime input for architecture diagrams/docs and should be combined with repository configuration, not treated as sole source of truth.

## Assumptions / Unknowns

The repository provides enough detail to infer **container-level architecture**, but not full **Proxmox host/VM topology**.

Unknowns (left intentionally as placeholders):

- **Proxmox physical hosts:** _unknown from repo contents._
- **VM/LXC inventory and placement:** _unknown from repo contents._
- **Which services run on which Proxmox node(s):** _unknown from repo contents._
- **Inter-host VLAN/subnet layout beyond Docker bridges:** _unknown from repo contents._

If you want, this section can be replaced with a concrete Proxmox topology once you add an inventory source (e.g., Terraform, Ansible inventory, or a diagram export).

## Runtime visibility from Prometheus

<!-- BEGIN GENERATED PROMETHEUS SECTION -->

Prometheus inventory provides **observed runtime coverage** of scrape targets. It complements (but does not replace) declared architecture in Compose files and static docs.

- Inventory timestamp: `2026-04-13T06:36:45Z`
- Observed jobs: `8`
- Observed instances: `19`
- Observed services (label-derived): `1`

### Observed monitoring view

| job | targets | unhealthy |
| --- | --- | --- |
| container-updates | 2 | 0 |
| kuma | 2 | 0 |
| node | 7 | 0 |
| pihole | 1 | 0 |
| prometheus | 1 | 0 |
| proxmox-storage | 2 | 0 |
| telegraf | 2 | 0 |
| traefik | 2 | 0 |

### Data sources

- `docs/runtime/prometheus-inventory.json` (normalized runtime export)
- Prometheus scrape metadata (`targets` + label sets)
- Existing repository architecture docs for declared topology

### Notes from inventory

- The `up` query indicates scrape success from Prometheus perspective only.
- Use static repository architecture docs and deployment configs with this runtime export for complete diagrams.

<!-- END GENERATED PROMETHEUS SECTION -->