Publish sanitized current homelab architecture

README.md

@@ -0,0 +1,88 @@
+# Homelab Showcase
+
+A public-safe overview of a real multi-host homelab built around segmented networking, self-hosted applications, resilient storage, local AI, offline services, and low-power edge nodes.
+
+> This repository is intentionally **not** the operational source of truth. Exact addresses, domains, account names, device identifiers, locations, mount paths, credentials, and raw controller exports are omitted or replaced with examples.
+
+## What this lab is designed to do
+
+- Keep household services useful during an internet outage
+- Separate trusted devices, servers, IoT, cameras, guests, and lab workloads
+- Centralize applications without making one server responsible for every failure domain
+- Keep bulk storage close to media ingestion and backup workflows
+- Route local AI work to the most appropriate always-on or high-performance host
+- Publish selected services through authenticated tunnels instead of broad inbound exposure
+- Preserve recovery options with encrypted secrets, snapshots, versioned sync, and documented rollback steps
+
+## Current architecture
+
+| Node | Platform | Primary role |
+|---|---|---|
+| **Application host** | TrueNAS SCALE | Primary application, database, identity, observability, media, and shared AI host |
+| **Storage host** | Storage-focused Linux server | Bulk storage, media-ingestion pipeline, synchronization hub, remote-support relay, and selected CPU services |
+| **Resilience host** | Ubuntu Server | Offline knowledge, resilient local tools, home automation VM, game orchestration, and secondary AI/DNS services |
+| **GPU workstation** | CachyOS workstation | Operator workstation and opportunistic high-performance GPU compute |
+| **Edge node** | Low-power Linux node | Weather dispatch and mesh-radio edge services |
+
+See [Architecture](docs/architecture.md) for the data flow and [Services](docs/services.md) for the current service placement.
+
+## Design highlights
+
+- **Segmented UniFi network:** management, trusted clients, servers, IoT, cameras, guests, and quarantine are separate policy lanes.
+- **Authenticated ingress:** selected applications use a tunnel gateway, an internal reverse proxy, and SSO. Most services have no direct internet-facing listener.
+- **Three-node DNS design:** one authoritative configuration source synchronizes to two backup resolvers; public fallback DNS is treated separately from private-zone continuity.
+- **Shared databases:** PostgreSQL, MariaDB, and Redis provide a managed data layer for compatible application stacks.
+- **Split storage and compute:** application compute is concentrated on the primary host while large media/photo datasets stay on the storage server.
+- **Tiered local AI:** an always-on light tier handles routine work; the GPU workstation is optional capacity rather than a hard dependency.
+- **Offline-first node:** documentation, educational content, notes, utilities, and selected models remain available locally.
+- **Encrypted operations:** runtime secrets live outside application repositories and are encrypted before entering version control.
+
+## Repository map
+
+```text
+docs/
+  architecture.md   High-level topology and request flows
+  networking.md     Segmentation and access-control model
+  operations.md     Deployment, verification, backup, and rollback patterns
+  security.md       Public/private boundary and secret-handling rules
+  services.md       Current service placement by host
+examples/
+  compose/           Sanitized Compose and environment examples
+scripts/
+  check-public-safety.py
+```
+
+## Reusable patterns
+
+- [Sanitized Compose example](examples/compose/docker-compose.yml)
+- [Environment template](examples/compose/.env.example)
+- [Public-safety scanner](scripts/check-public-safety.py)
+- [Operational practices](docs/operations.md)
+- [Security model](docs/security.md)
+
+## Public-safety policy
+
+Every commit is checked for:
+
+- private or management addresses
+- MAC addresses and device identifiers
+- internal domains and personal filesystem paths
+- private-key material, tokens, passwords, and authorization headers
+- real `.env` files and key-bearing file types
+
+Gitleaks also scans the complete Git history in CI. See [Security](docs/security.md).
+
+## Scope
+
+This repository demonstrates architecture and operating patterns. It deliberately excludes:
+
+- deployable production secrets
+- exact network coordinates
+- raw exports, backups, logs, and incident artifacts
+- household or personal records
+- device serial numbers and persistent client identifiers
+- live tunnel, VPN, DNS, or identity-provider configuration
+
+## License
+
+MIT — see [LICENSE](LICENSE).