# 📊 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

## 🔐 Key Architecture Components

### Authentication & Proxy Stack
```
┌─────────────────────────────────────────────────────────────────────┐
│  Internet → Cloudflare → NPM (Atlantis) → Authentik (Calypso)       │
│                                ↓                                      │
│                         Protected Services                           │
└─────────────────────────────────────────────────────────────────────┘
```

| Component | Host | Port | Purpose |
|-----------|------|------|---------|
| **Nginx Proxy Manager** | Atlantis | :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 |
| docs.vish.gg | Paperless-NGX | Forward Auth |
| photos.vish.gg | Immich | Forward Auth |
| actual.vish.gg | Actual Budget | Forward Auth |
| ff.vish.gg | Firefly III | 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 8+ services
- **Nginx Proxy Manager** routing 20+ domains

### Service Counts by Host
| Host | Services | Primary Role |
|------|----------|--------------|
| Atlantis | 53 | Media, monitoring, proxy |
| Calypso | 24 | Auth, Gitea, Paperless |
| Homelab VM | 33 | Experiments, tools |
| Concord NUC | 11 | Edge, Home Assistant |
| Other hosts | 43 | Various |
| **Total** | **164** | |

## 🔄 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-02-05*