---
description: Keyboard Vagabond project overview and core infrastructure context
globs: []
alwaysApply: true
---

# Keyboard Vagabond - Project Overview

## System Overview
This is a **Talos-based Kubernetes cluster** designed to host **fediverse applications** for <200 MAU (Monthly Active Users):
- **Mastodon** (Twitter-like microblogging) ✅ OPERATIONAL
- **Pixelfed** (Instagram-like photo sharing) ✅ OPERATIONAL  
- **PieFed** (Reddit-like forum) ✅ OPERATIONAL
- **BookWyrm** (Social reading platform) ✅ OPERATIONAL
- **Matrix** (Chat/messaging) - Future deployment

## Architecture Summary ✅ OPERATIONAL
- **Three ARM64 Nodes**: n1, n2, n3 (all control plane nodes with VIP 10.132.0.5)
- **Zero Trust Security**: Cloudflare tunnels + Tailscale mesh VPN
- **Storage**: Longhorn distributed with S3 backup to Backblaze B2
- **Database**: PostgreSQL HA cluster with CloudNativePG operator
- **Cache**: Redis HA cluster with HAProxy (redis-ha-haproxy.redis-system.svc.cluster.local)
- **Monitoring**: OpenTelemetry + OpenObserve (O2)
- **Registry**: Harbor container registry
- **CDN**: Per-application Cloudflare CDN with dedicated S3 buckets

## Project Structure
```
keyboard-vagabond/
├── .cursor/rules/              # Cursor rules (this directory)
├── docs/                       # Operational documentation and guides
├── manifests/                  # Kubernetes manifests
│   ├── infrastructure/         # Core infrastructure components
│   ├── applications/           # Fediverse applications  
│   └── cluster/flux-system/    # GitOps configuration
├── build/                      # Custom container builds
├── machineconfigs/            # Talos node configurations
└── tools/                     # Development utilities
```

## Rule Organization
The `.cursor/rules/` directory contains specialized rules:
- **00-project-overview.mdc** (this file) - Always applied project context
- **infrastructure.mdc**: Auto-attached when working in `manifests/infrastructure/`
- **applications.mdc**: Auto-attached when working in `manifests/applications/`
- **security.mdc**: SOPS and Zero Trust patterns (auto-attached for YAML files)
- **development.mdc**: Development patterns and operational guidelines
- **troubleshooting-history.mdc**: Historical issues, migrations, and lessons learned
- **templates/**: Common configuration templates (*.yaml files)

## Key Operational Facts
- **Domain**: `keyboardvagabond.com`
- **API Endpoint**: `api.keyboardvagabond.com:6443` (Tailscale-only access)
- **Control Plane VIP**: `10.132.0.5:6443` (nodes elect primary, VIP provides HA)
- **Zero Trust**: All external services via Cloudflare tunnels (no port exposure)
- **Network**: NetCup Cloud vLAN 1004963 (10.132.0.0/24)
- **Security**: Enterprise-grade with SOPS encryption, mesh VPN, host firewall
- **Status**: Fully operational, production-ready cluster