From c8a6d904995e3683ba06b226cdaf86a4bf4545ea Mon Sep 17 00:00:00 2001
From: xpltd_admin <admin@xpltd.co>
Date: Fri, 3 Apr 2026 22:38:06 -0600
Subject: [PATCH] Create Home wiki page with project overview, glossary, and
 navigation

---
 Home.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 Home.md

diff --git a/Home.md b/Home.md
new file mode 100644
index 0000000..f9221a6
--- /dev/null
+++ b/Home.md
@@ -0,0 +1,83 @@
+# Tubearr
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/tubearr` |
+| **Page** | `Home` |
+| **Audience** | developers, agents, newcomers |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## What is Tubearr?
+
+Tubearr is a self-hosted content archival and monitoring application in the *arr family style (Sonarr, Radarr, Lidarr). It automatically monitors YouTube channels and SoundCloud artists for new content, downloads media using configurable quality profiles, and organizes files into a structured library. Think of it as an automated media librarian that watches your favorite creators and grabs their content before it disappears.
+
+## Current Status
+
+**Actively developed.** Version 0.1.0. Core monitoring, downloading, and queue management features are functional. The application runs in production on the xpltd infrastructure.
+
+## Key URLs
+
+| Resource | URL |
+|----------|-----|
+| **Application** | `https://tubearr.xpltd.co` |
+| **Repository** | `https://git.xpltd.co/xpltdco/tubearr` |
+| **Health Check** | `https://tubearr.xpltd.co/ping` |
+
+## Core Features
+
+- **Channel Monitoring** — Add YouTube channels or SoundCloud artists; Tubearr periodically scans for new content
+- **Smart Queue** — Concurrent download queue with retry logic, priority ordering, and rate limiting
+- **Format Profiles** — Configurable quality presets (resolution, codec, bitrate, subtitles, SponsorBlock)
+- **Multi-Platform** — YouTube, SoundCloud, and any URL supported by yt-dlp
+- **Real-Time Progress** — WebSocket-based live download progress in the browser UI
+- **Notifications** — Discord, email, Pushover, and Telegram alerts on grab/download/failure events
+- **Back-Catalog Import** — Bulk import existing media files into the library
+- **REST API** — Full API with key-based authentication for external integrations
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Backend | Node.js 22, TypeScript, Fastify 5 |
+| Frontend | React 19, React Router 7, TanStack Query |
+| Database | SQLite (LibSQL) with Drizzle ORM |
+| Downloader | yt-dlp + ffmpeg |
+| Build Tool | Vite |
+| Testing | Vitest |
+| Deployment | Docker (multi-stage build) |
+
+## Wiki Pages
+
+| Page | Description |
+|------|-------------|
+| [Architecture](Architecture) | System design, tech stack, directory structure, design decisions |
+| [Getting Started](Getting-Started) | Local dev setup, prerequisites, first run |
+| [Data Model](Data-Model) | Database schema, tables, relationships, migrations |
+| [API Reference](API-Reference) | Complete HTTP endpoint inventory with examples |
+| [Deployment](Deployment) | Docker setup, volumes, nginx config, health checks |
+| [Configuration](Configuration) | All environment variables and config knobs |
+| [Development Guide](Development-Guide) | Code patterns, testing, CI/CD, contribution workflow |
+| [Agent Context](Agent-Context) | Structured metadata for LLM agents working on this codebase |
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| **Channel** | A monitored content source — a YouTube channel, SoundCloud artist, or generic URL |
+| **Content Item** | A single piece of downloadable media (video, audio, or livestream) |
+| **Format Profile** | A reusable quality preset defining resolution, codec, subtitles, and post-processing options |
+| **Queue Item** | A content item that has been enqueued for download, with status tracking and retry logic |
+| **Monitoring Mode** | Controls what content Tubearr grabs: `all`, `future` (new only), `existing` (backlog only), or `none` |
+| **Platform Source** | An adapter for a specific content platform (YouTube, SoundCloud, Generic) |
+| **yt-dlp** | The command-line tool that handles actual media downloading from 1000+ platforms |
+| **SponsorBlock** | Community-sourced sponsor segment data; Tubearr can auto-remove sponsor segments during download |
+| ***arr family** | A category of self-hosted media management apps (Sonarr for TV, Radarr for movies, Lidarr for music) |
+
+## Infrastructure Context
+
+For newcomers to the xpltd infrastructure:
+- **ub01** (10.0.0.10) — The primary server where all Docker services run
+- **nginx01** (10.0.0.9) — Reverse proxy handling TLS termination for all `*.xpltd.co` subdomains
+- **AdGuard Home** — Internal DNS with rewrite rules pointing `*.xpltd.co` to nginx01
+- **Cloudflare** — External DNS with CNAME to dyndns.xpltd.co for public access
\ No newline at end of file