# Architecture Summary

## Overview

This stack uses **Traefik v3** as internet-facing ingress for application and operations UIs. Service routing is label-driven from Docker Compose files, with shared Docker networks (`traefik`, `monitor`) connecting reverse-proxied and telemetry services.

TLS is terminated at Traefik (ACME HTTP challenge), with hardening via middleware chains, Authelia forward-auth for selected routes, CrowdSec integration, and mTLS options for private-admin paths.

## 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]
    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 apps:** Nextcloud, Passbolt, Gitea, Gramps Web, SearXNG.
- **Monitoring/ops:** Prometheus, Grafana, InfluxDB, Node-RED, Uptime Kuma, Portainer, Gotify.
- **Support plane:** Docker Socket Proxy for controlled Docker API access.

## Relationship to Terraform inventory

Terraform in `infrastructure/terraform/` captures infrastructure inventory and reconciliation state for Proxmox VMs, physical host metadata, and selected Docker mirrors.

Use architecture docs together with:

- [docs/source-of-truth.md](source-of-truth.md)
- [docs/terraform-workflows.md](terraform-workflows.md)
- [docs/infrastructure-inventory.md](infrastructure-inventory.md)

## Notes on runtime vs declared state

Runtime scrape targets and health signals are useful observed-state inputs, but they do not replace declared config authority from Compose/Terraform sources.