# 📐 Architecture Overview

> [!NOTE]
> The stable, directional laws governing how traffic moves through the fleet — eight distinct traffic categories (ingress, east-west, secrets, DNS, observability, notifications, CI/CD, management), each with its own routing authority and its own failure behavior.

## Dependency graph

```mermaid
flowchart TD
    Internet(["Internet"]) --> Edge["Edge Firewall<br/>NAT · public reverse proxy · NTP · DHCP"]
    Edge --> LAN["LAN"]

    LAN --> DNS["Internal DNS"]
    LAN --> Vault["Vault"]
    DNS --> Vault

    Vault --> Apps["App Host<br/>~40 stacks"]
    LAN --> FileServer["File Server"]
    DNS --> FileServer
    Vault --> Automation["Automation Host"]
    LAN --> Automation

    Apps --> InternalProxy["Internal reverse-proxy zone"]
    Apps --> SSO["SSO"]

    Automation --> Gitea["Git hosting<br/>internal + public mirror"]

    Vault --> EdgeProxy["User-facing reverse proxy<br/>mTLS"]
    DNS --> EdgeProxy
    Apps -.proxied by.-> EdgeProxy
    SSO -.auth gate via.-> EdgeProxy

    Apps -.reports to.-> Monitoring["Monitoring"]
    Automation -.reports to.-> Monitoring
    FileServer -.reports to.-> Monitoring
    EdgeProxy -.reports to.-> Monitoring
    Vault -.reports to.-> Monitoring
    DNS -.reports to.-> Monitoring

    Apps -.reports to.-> Wazuh["Security Monitoring"]
    Automation -.reports to.-> Wazuh
    FileServer -.reports to.-> Wazuh
    EdgeProxy -.reports to.-> Wazuh
    Vault -.reports to.-> Wazuh
    DNS -.reports to.-> Wazuh
```

## Four trust boundaries, not two

```mermaid
flowchart LR
    WAN["WAN"] -->|public application boundary| EdgeFW["Edge Firewall / public proxy"]
    Browser["LAN browsers"] -->|mTLS + SSO| UserProxy["User-facing proxy"]
    Service["App-to-app"] -->|IP-allowlist + SSO| InternalProxy["Internal proxy"]
    Infra["LAN infra-to-infra"] -->|explicit per-flow rules| HostFW["Host firewall rules"]
```

Backend services trust proxy headers, not raw client IP, on every path.

## Two structurally independent traffic planes

| Plane | Path |
|---|---|
| **Ingress — public** | Client → edge firewall/proxy → backend |
| **Ingress — LAN-facing** | Client → user-facing proxy (mTLS) → backend |
| **East-west — app-to-app** | Service → internal proxy zone → service |
| **East-west — infra-to-infra** | Service → firewall rule → service, direct, no proxy |

> [!IMPORTANT]
> **Observability sits outside every request path on purpose.** Logs and metrics push asynchronously to monitoring infrastructure; nothing in that pipeline is inline with application traffic, and application services don't depend on monitoring availability. If monitoring goes down, collection stops — nothing else does.

## Two real architecture changes, not a static design

> [!IMPORTANT]
> This shape isn't how the fleet started — it's evolved twice, deliberately. The public-facing reverse proxy used to run as its own dedicated VM; it was consolidated directly onto the edge firewall as a package instead, removing an entire host from the public-ingress path without losing any functionality — one less thing that can fail, one less thing to patch and monitor independently. And the internal service-to-service model used to be a flat, unauthenticated mesh network; it was fully replaced by the two-zone split in [`docs/dns-naming.md`](dns-naming.md), trading a simpler-but-weaker model for one with a real trust boundary between browser-facing and app-to-app traffic. Both changes reduced the attack surface at the cost of more moving parts to reason about — a tradeoff made deliberately, not stumbled into.

## What this map deliberately excludes

Not a firewall rule listing, not a port inventory, not a service configuration reference — those live in their own docs ([`docs/firewall-and-network.md`](firewall-and-network.md) and elsewhere). This is strictly the stable, directional shape of how trust and traffic actually move.

---
Related: [`docs/firewall-and-network.md`](firewall-and-network.md), [`docs/dns-naming.md`](dns-naming.md)