# Keyboard Vagabond Network Diagrams

This directory contains network architecture diagrams for the Keyboard Vagabond Kubernetes cluster.

## Files

### `network-architecture.mmd`
**Mermaid diagram** showing the complete network architecture including:
- Cloudflare Zero Trust tunnels and CDN infrastructure
- Tailscale mesh VPN for administrative access
- NetCup Cloud VLAN setup with node topology
- Backblaze B2 storage integration
- Application and infrastructure pod distribution

## How to View/Edit Mermaid Diagrams

### Option 1: GitHub (Automatic Rendering)
- GitHub automatically renders `.mmd` files in the web interface
- Simply view the file on GitHub to see the rendered diagram

### Option 2: Mermaid Live Editor
1. Go to [mermaid.live](https://mermaid.live)
2. Copy the contents of the `.mmd` file
3. Paste into the editor to view/edit

### Option 3: VS Code Extensions
Install one of these VS Code extensions:
- **Mermaid Markdown Syntax Highlighting** by bpruitt-goddard
- **Mermaid Preview** by vstirbu
- **Markdown Preview Mermaid Support** by bierner

### Option 4: Local Mermaid CLI
```bash
# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# Generate PNG/SVG from diagram
mmdc -i network-architecture.mmd -o network-architecture.png
mmdc -i network-architecture.mmd -o network-architecture.svg
```

### Option 5: Integration in Documentation
Add to Markdown files using:
```markdown
```mermaid
graph TB
    // Paste diagram content here
```
```

## Architecture Overview

The current network architecture implements a **zero-trust security model** with:

### 🔒 Security Layers
1. **Cloudflare Zero Trust**: All public application access via secure tunnels
2. **Tailscale Mesh VPN**: Administrative access to Kubernetes/Talos APIs
3. **Cilium Host Firewall**: Node-level security with CGNAT-only access to APIs

### 🌐 Public Access Paths
- **Applications**: `https://*.keyboardvagabond.com` → Cloudflare Zero Trust → Internal services
- **CDN Assets**: `https://{pm,pfm,mm}.keyboardvagabond.com` → Cloudflare CDN → Backblaze B2

### 🔧 Administrative Access
- **kubectl**: Tailscale client (`<TAILSCALE_CLIENT_IP>`) → Tailscale mesh → Internal API (`<NODE_1_IP>:6443`)
- **talosctl**: Tailscale client → Tailscale mesh → Talos APIs on both nodes

### 🛡️ Security Achievements
- ✅ Zero external ports exposed directly to internet
- ✅ All administrative access via authenticated mesh VPN
- ✅ All public access via authenticated Zero Trust tunnels
- ✅ Host firewall blocking world access to critical APIs
- ✅ Dedicated CDN endpoints per application with $0 egress costs

## Maintenance

When architecture changes occur, update the diagram by:
1. Editing the `.mmd` file with new components/connections
2. Testing the rendering in Mermaid Live Editor
3. Updating this README if new concepts are introduced
4. Committing both the diagram and documentation updates