# Vibe Code Plan — Video Library App (Windows VPS Storage)

> A vibe-coded plan: optimized for fast iteration, learning, and a working prototype before a production build. Treat every section below as a **draft to refine**, not a contract.

---

## 1. Goal & Users

**One-line pitch:** A web app to upload, organize, watch, and share a private video library whose master files live on a Windows VPS.

**Who is it for?** (assumption — please confirm)
- **Primary:** You (and a small team) managing a private video catalog — courses, raw footage, recordings, deliverables, etc.
- **Secondary:** Invited viewers who get read-only access to specific videos or collections.

**What it is NOT (yet):**
- Not a public YouTube competitor.
- Not a multi-tenant SaaS.
- Not a DRM/copy-protection system.

**Stage:** Prototype → Internal MVP. Not production-grade until the items in §8 are addressed.

---

## 2. Core Use Cases (v1)

| # | Use case | Success looks like |
|---|----------|-------------------|
| 1 | Upload a video from my browser | File lands on the Windows VPS, appears in the library within seconds |
| 2 | Browse my library | Grid view with thumbnails, search, filter by tag/folder/date |
| 3 | Watch a video in the browser | Smooth playback with adaptive quality (HLS) |
| 4 | Edit metadata | Title, description, tags, thumbnail, visibility |
| 5 | Share a video | Generate a private link (optionally expiring / password-protected) |
| 6 | Manage storage | See VPS disk usage, delete or archive old videos |
| 7 | Admin: manage users | Invite, set roles (Admin / Editor / Viewer) |

**Stretch (v2+):** auto-transcription, AI tagging, chapters, comments, analytics per viewer, scheduled publishing, S3 cold-storage tier.

---

## 3. Functionality Breakdown

### 3.1 Upload & Ingest
- Drag-and-drop multi-file upload.
- **Resumable, chunked uploads** (tus.io protocol or UpChunk) — critical for large video files over flaky connections.
- Client-side validation (codec, size, duration).
- Background transcoding pipeline (FFmpeg on the VPS) → produces HLS renditions (480p / 720p / 1080p) + thumbnail + poster + sprite preview.
- Status states: `queued → uploading → processing → ready → failed`.

### 3.2 Library
- Grid + list view toggle.
- Search (title, tags, transcript later).
- Filters: folder, tag, status, duration, date.
- Sort: newest, oldest, longest, most viewed.
- Bulk actions: tag, move, delete, change visibility.

### 3.3 Player
- HLS.js for adaptive streaming.
- Speed control, captions, chapter markers, share timestamp.
- Signed playback URLs (short-lived) — no hot-linking.

### 3.4 Metadata
- Editable title / description (markdown).
- Tags (multi-select with autocomplete).
- Custom thumbnail upload or pick-from-frame.
- Visibility: private, unlisted (link), team, public.

### 3.5 Sharing
- Per-video share link with optional expiry & password.
- Embed snippet (iframe).
- Download permission toggle.

### 3.6 Admin Dashboard
- Storage usage gauge (used / total on the VPS volume).
- VPS health: CPU, RAM, disk I/O, transcode queue depth.
- Activity log (uploads, deletes, logins).
- User & role management.
- Transcoding presets editor.

### 3.7 Auth
- Email + password (Auth.js / NextAuth).
- Optional: SSO (Google) for v1.5.
- Sessions in DB, signed cookies.

---

## 4. Architecture (Vibe-Coded Sketch)

```
┌─────────────────┐         ┌────────────────────────────────┐
│  Browser (User) │ ◀────▶  │  Next.js (App Router) — Vercel │
│  shadcn/ui UI   │         │  • Server Actions / API routes │
└─────────────────┘         │  • NextAuth                    │
                            │  • Issues signed VPS URLs      │
                            └────────────┬───────────────────┘
                                         │ HTTPS (signed)
                                         ▼
                            ┌────────────────────────────────┐
                            │   Windows VPS                  │
                            │  • Node "edge agent" (Express) │
                            │      ├─ tus upload endpoint    │
                            │      ├─ HLS streaming endpoint │
                            │      └─ FFmpeg worker queue    │
                            │  • Storage: D:\videos\ ...     │
                            │  • IIS or Caddy reverse proxy  │
                            └────────────┬───────────────────┘
                                         │
                                         ▼
                            ┌────────────────────────────────┐
                            │ Postgres (Neon / Supabase)     │
                            │  videos, users, tags, shares,  │
                            │  transcode_jobs, audit_log     │
                            └────────────────────────────────┘
```

**Why split the app from the storage?**
- Next.js front-end is best on Vercel (cheap, fast, easy auth).
- The Windows VPS hosts the heavy bits: file storage, FFmpeg, HLS streaming.
- The VPS only trusts requests signed by the Next.js backend (HMAC-signed URLs with expiry).

### Tech stack (proposed)

| Layer | Choice | Reason |
|-------|--------|--------|
| Frontend | Next.js 15 (App Router) + TypeScript | Modern, server actions, fast |
| UI kit | **shadcn/ui** + Tailwind v4 | Accessible, themeable, copy-in components |
| Animation | Framer Motion + Tailwind transitions | Micro-animations on every interactive element |
| Icons | lucide-react | Pairs with shadcn |
| Auth | NextAuth (Auth.js) | Email/password + OAuth |
| DB | Postgres + Drizzle ORM | Type-safe, migrations |
| Upload protocol | **tus** (resumable) via `@tus/server` on the VPS | Survives flaky uploads, supports resume |
| Transcoding | FFmpeg + BullMQ-style queue (or Windows service) | Industry standard |
| Streaming | HLS via `hls.js` | Adaptive bitrate, plays everywhere |
| Storage | Windows VPS disk (NTFS) | Per your requirement |
| Reverse proxy on VPS | Caddy (Windows) or IIS | Auto-TLS, easy config |
| Deploy (frontend) | Vercel | Zero-config |

---

## 5. Data Model (first cut)

```
users          (id, email, password_hash, role, created_at)
videos         (id, owner_id, title, description, status, duration,
                size_bytes, source_path, hls_path, poster_path,
                visibility, created_at, updated_at)
tags           (id, name)
video_tags     (video_id, tag_id)
shares         (id, video_id, token, password_hash, expires_at, can_download)
transcode_jobs (id, video_id, preset, status, progress, error, started_at, finished_at)
audit_log      (id, actor_id, action, target_type, target_id, payload, created_at)
vps_metrics    (id, captured_at, cpu, mem, disk_used, disk_total, queue_depth)
```

---

## 6. Iteration Roadmap (vibe-coded, ship-tiny)

> Each milestone is a *thing you can run, click, and judge* — not a thesis.

- **M0 — Mockups (this step).** 5 HTML screens to lock the look & feel.
- **M1 — Static Next.js shell.** Same 5 screens but as real components (shadcn), no data.
- **M2 — Auth + DB.** Login works, you can create a user, empty library renders.
- **M3 — Upload to VPS.** A file uploaded in the browser actually lands on the VPS via tus.
- **M4 — Watch.** That same file plays back in the browser as HLS after transcoding.
- **M5 — Library polish.** Search, filters, tags, edit metadata, delete.
- **M6 — Sharing.** Signed share links, embed.
- **M7 — Admin.** VPS health widgets, user mgmt, audit log.
- **M8 — Hardening.** Rate limits, antivirus scan on upload, backups, monitoring.

Each milestone = ~½–2 days of vibe-coding with verification at the end.

---

## 7. Project Evaluation Rubric

How we'll judge whether the prototype is "good enough" before investing more.

| Dimension | Bar for MVP | How we measure |
|-----------|-------------|----------------|
| **Upload reliability** | A 5 GB file uploads end-to-end on a flaky home Wi-Fi | Test on throttled connection, kill & resume |
| **Playback quality** | Starts in <2 s, no stalls at 1080p on broadband | Manual + browser dev-tools network |
| **Time to publish** | Upload → playable URL in <2× video duration | Timestamp diff in DB |
| **VPS headroom** | Can run 1 transcode + serve 5 viewers @ 1080p without saturating CPU | `wmic`/PerfMon during load test |
| **UI feel** | Every interactive element has a state (hover, active, loading, success, error). Animations < 200 ms | Manual heuristic walkthrough |
| **Onboarding** | A new teammate can upload + share a video in <5 min without help | Hallway test |
| **Cost** | <$30/mo for prototype (Vercel hobby + existing VPS + Neon free) | Receipts |
| **Security baseline** | Auth required, signed URLs, no public buckets, password-protected shares work | Checklist below |

**Security baseline checklist (prototype level):**
- [ ] All routes auth-gated except marketing.
- [ ] Signed, short-lived URLs for video bytes.
- [ ] Rate-limit uploads & login.
- [ ] CSRF protection on mutating routes.
- [ ] No secrets in client bundle.
- [ ] HTTPS everywhere (Caddy/IIS on VPS, Vercel handles frontend).
- [ ] Antivirus scan (ClamAV / Windows Defender CLI) on uploaded files.
- [ ] Daily DB backup; weekly VPS volume snapshot.

---

## 8. Risks & Open Questions

**Risks**
1. **Single point of failure** — the Windows VPS. If it dies, no playback, no uploads. Mitigation: snapshots + a documented restore runbook.
2. **Bandwidth caps** on the VPS host — streaming HD video can chew 100s of GB/month. Confirm host's policy.
3. **Windows quirks** — FFmpeg + Node services need to run as a Windows Service (NSSM / sc.exe). More fiddly than Linux.
4. **Transcoding cost** — CPU-bound on a single VPS. If volume grows, may need a GPU box or external service (Mux, Cloudflare Stream).
5. **Legal/content** — if videos contain third-party content, copyright + takedown processes are not in scope yet.

**Open questions (please answer before M2)**
- [ ] How many concurrent users in the next 6 months? (1, 10, 100?)
- [ ] Max video size & total library size you expect?
- [ ] Public sharing required at launch, or internal only?
- [ ] Does the VPS already have a domain & TLS certificate?
- [ ] Should the front-end live on the VPS too (same origin) or on Vercel (split)?
- [ ] Any compliance requirements (GDPR, HIPAA, etc.)?

---

## 9. Definition of Done — Mockup Phase (this PR)

- [x] `VIBE_PLAN.md` committed.
- [x] `mockups/index.html` — landing/nav for the demo.
- [x] 5 standalone HTML mockups styled in shadcn-flavored Tailwind, with micro-animations on every interactive component.
- [x] Mockups openable directly in a browser, no build step.
- [ ] Reviewed with stakeholder, feedback captured as inline comments before M1.

---

*Source steering: `.kiro/steering/vibe-coding.md` — adapted from refoundai/lenny-skills.*