Initial commit: YouTube Studio Flow (backend, frontend, infrastructure, docs)

2026-08-11 12:27:44 +02:00
commit d5af006443
304 changed files with 74604 additions and 0 deletions
@@ -0,0 +1,94 @@
+# Local Setup
+
+Step-by-step guide to running YouTube Studio Flow on a local machine for development.
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** — required by both backend and frontend
+- **Docker** — used to run Postgres and Redis locally
+- **Git** — for cloning the repository
+
+---
+
+## Step 1 — Start Infrastructure
+
+Start Postgres and Redis using Docker Compose:
+
+```bash
+cd infrastructure
+docker compose up -d postgres redis
+```
+
+> **Important:** Redis must run with `--maxmemory-policy noeviction`. BullMQ silently drops jobs if Redis uses `allkeys-lru` eviction. This policy is already pre-configured in `infrastructure/docker-compose.yml`. Do not change it. See [[04 - Gotchas]] for more detail.
+
+---
+
+## Step 2 — Backend Setup
+
+In a terminal, set up and start the NestJS API:
+
+```bash
+cd backend
+npm install
+cp .env.example .env
+# Fill in all required values in .env — see [[02 - Environment Variables]]
+npx prisma generate
+npx prisma migrate deploy
+npm run start:dev
+```
+
+The API is now running on **http://localhost:3001**.
+
+---
+
+## Step 3 — Queue Worker
+
+Open a **second terminal** and start the BullMQ queue processor:
+
+```bash
+cd backend
+npx ts-node src/worker.ts
+```
+
+The worker runs from the same codebase as the API but through a separate entry point (`src/worker.ts` → `WorkerModule`). It handles all background jobs: YouTube sync, description rendering, linting, bulk operations, and CSV imports.
+
+---
+
+## Step 4 — Frontend Setup
+
+Open a **third terminal** and start the Next.js frontend:
+
+```bash
+cd frontend
+npm install
+# Create frontend/.env.local with the following content:
+# NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1
+npm run dev
+```
+
+The app is now running on **http://localhost:3000**.
+
+---
+
+## Verify the Setup
+
+1. Navigate to **http://localhost:3000**
+2. Click **"Sign in with Google"**
+3. Complete the Google OAuth flow
+4. You should be redirected to the **Overview** page
+
+If the redirect fails, check that `GOOGLE_CALLBACK_URL` and `FRONTEND_URL` are set correctly in `backend/.env`. See [[02 - Environment Variables]].
+
+---
+
+## Notes
+
+- All three processes must run simultaneously for full functionality:
+  - `npm run start:dev` — HTTP API on :3001
+  - `npx ts-node src/worker.ts` — BullMQ job processor
+  - `npm run dev` — Next.js frontend on :3000
+- Database migrations run automatically with `npx prisma migrate deploy`
+- After any schema change: stop the backend → `npx prisma generate` → `npx prisma migrate deploy` → restart both the API and worker
+- For non-obvious behaviors and known traps, see [[04 - Gotchas]]