Sanitized mirror from private repository - 2026-04-06 02:30:35 UTC

docs/diagrams/README.md

@@ -0,0 +1,115 @@
+# 📊 Homelab Infrastructure Diagrams
+
+This directory contains visual documentation of the homelab infrastructure, including network topology, service architecture, and storage layouts. All diagrams use [Mermaid.js](https://mermaid.js.org/) for rendering.
+
+## 📁 Diagram Index
+
+| Diagram | Description | Format |
+|---------|-------------|--------|
+| [Network Topology](network-topology.md) | Physical and logical network layout across all locations | Mermaid + ASCII |
+| [Tailscale Mesh](tailscale-mesh.md) | VPN mesh network connecting all locations | Mermaid + ASCII |
+| [10GbE Backbone](10gbe-backbone.md) | High-speed network backbone in Concord | Mermaid + ASCII |
+| [Service Architecture](service-architecture.md) | How services interact, auth flows, CI/CD pipeline | Mermaid |
+| [Storage Topology](storage-topology.md) | NAS cluster, volumes, and backup flows | Mermaid + ASCII |
+| [Location Overview](location-overview.md) | Geographic distribution of infrastructure | Mermaid |
+
+### Service Architecture Sections
+- Media Stack (Arr suite, Plex, streaming)
+- Monitoring Stack (Prometheus, Grafana)
+- **Authentication Stack (Authentik + NPM)** ⭐ NEW
+- Communication Stack (Matrix, Mastodon, Mattermost)
+- **CI/CD Pipeline (Gitea Actions + Ansible)** ⭐ NEW
+- AI/ML Stack (Ollama, vLLM, Olares)
+- DCIM/IPAM (NetBox)
+
+## 🔐 Key Architecture Components
+
+### Authentication & Proxy Stack
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Internet → Cloudflare → NPM (matrix-ubuntu) → Authentik (Calypso)   │
+│                                ↓                                      │
+│                         Protected Services                           │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+| Component | Host | Port | Purpose |
+|-----------|------|------|---------|
+| **Nginx Proxy Manager** | matrix-ubuntu | :81/:443 | Reverse proxy, SSL termination |
+| **Authentik Server** | Calypso | :9000 | Identity provider, SSO |
+| **Authentik Outpost** | Calypso | :9444 | Forward auth proxy |
+| **Headscale** | Calypso | :8080 | Self-hosted Tailscale controller |
+| **WireGuard** | Atlantis | :51820 | VPN server |
+
+### Service Protection via Authentik
+
+| Domain | Service | Auth Type |
+|--------|---------|-----------|
+| sso.vish.gg | Authentik | - (IdP) |
+| git.vish.gg | Gitea | OAuth2/OIDC |
+| gf.vish.gg | Grafana | OAuth2/OIDC |
+| nb.vish.gg | NetBox | OAuth2/OIDC |
+| dash.vish.gg | Homarr | OAuth2/OIDC |
+| rx.vish.gg | Reactive Resume | OAuth2/OIDC |
+| immich | Immich | OAuth2/OIDC |
+| headscale.vish.gg/admin | Headplane | OAuth2/OIDC |
+| docs.vish.gg | Paperless-NGX | Forward Auth |
+| actual.vish.gg | Actual Budget | Forward Auth |
+
+## 🗺️ Quick Reference
+
+### Locations
+- **Concord, CA** (Primary) - Main infrastructure, 25Gbps fiber
+- **Concord, CA** (Backup ISP) - Failover connectivity, 2Gbps/500Mbps
+- **Tucson, AZ** - Remote NAS (Setillo)
+- **Honolulu, HI** - Travel/remote access point
+- **Seattle, WA** - Cloud VPS (Contabo)
+
+### Key Infrastructure
+- **3 Synology NAS** units (Atlantis, Calypso, Setillo)
+- **10GbE backbone** via TP-Link TL-SX1008
+- **Tailscale mesh** connecting all locations
+- **Proxmox** virtualization for VMs
+- **Authentik SSO** protecting 12+ services
+- **Nginx Proxy Manager** routing 30+ domains
+- **Olares** K8s node for local LLM inference
+
+### Service Counts by Host
+| Host | Services | Primary Role |
+|------|----------|--------------|
+| Atlantis | 59 | Media, downloads, DNS backup, dashboard |
+| Calypso | 61 | Auth, Gitea, arr-suite, headscale |
+| matrix-ubuntu | 12+ | NPM, Matrix, Mastodon, Mattermost |
+| Homelab VM | 38 | Monitoring, tools, DCIM, Ansible UI |
+| Concord NUC | 19 | Home Assistant, Plex, edge |
+| RPi 5 | 6 | Uptime Kuma, monitoring, DIUN |
+| **Total** | **~195** | **Across 5 Portainer endpoints + matrix-ubuntu** |
+
+## 🔄 Diagram Updates
+
+These diagrams should be updated when:
+- New hosts are added
+- Network topology changes
+- Services are added/removed
+- Storage configuration changes
+- Authentication flows change
+
+## 📝 Viewing Diagrams
+
+These diagrams render automatically on:
+- **Gitea** (git.vish.gg) - Native Mermaid support
+- **GitHub** - Native Mermaid support
+- **VS Code** - With Mermaid extension
+
+For local viewing:
+```bash
+# Install mermaid-cli
+npm install -g @mermaid-js/mermaid-cli
+
+# Generate PNG from markdown
+mmdc -i service-architecture.md -o output.png
+```
+
+---
+
+*Last updated: 2026-03-20*