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,68 @@
+# Environment Variables
+
+Complete reference for all environment variables used by the backend and frontend.
+
+---
+
+## Backend (`backend/.env`)
+
+Copy `backend/.env.example` to `backend/.env` and fill in all required values before starting the API or worker. See [[01 - Local Setup]] for the full setup sequence.
+
+| Variable | Required | Description |
+|---|---|---|
+| `DATABASE_URL` | Yes | PostgreSQL connection string. Format: `postgresql://user:pass@localhost:5432/dbname` |
+| `REDIS_URL` | Yes | Redis connection string. Format: `redis://:password@localhost:6379` |
+| `JWT_SECRET` | Yes | Secret for signing access tokens. Use a long random string. |
+| `JWT_REFRESH_SECRET` | Yes | Secret for signing refresh tokens. Must differ from `JWT_SECRET`. |
+| `GOOGLE_CLIENT_ID` | Yes | Google OAuth app client ID |
+| `GOOGLE_CLIENT_SECRET` | Yes | Google OAuth app client secret |
+| `GOOGLE_CALLBACK_URL` | Yes | OAuth redirect URL. Local: `http://localhost:3001/api/v1/auth/google/callback` |
+| `TOKEN_ENCRYPTION_KEY` | Yes | Exactly 32 characters. AES-256 key for encrypting YouTube OAuth tokens in the DB. **If this changes, all channel connections break.** |
+| `FRONTEND_URL` | Yes | Frontend origin for OAuth redirect. Local: `http://localhost:3000` |
+| `PORT` | No | API port. Default: `3001` |
+| `NODE_ENV` | No | `development` or `production` |
+| `CONFLICT_DETECTION_ENABLED` | No | Global kill switch for the scheduled remote-conflict sweep. Default: `false`. Only takes effect on the worker process; the API doesn't read it. Per-team opt-in still required via `Team.conflictDetectionEnabled`. See [[05 - Queue System]]. |
+| `CONFLICT_DETECTION_CRON` | No | Cron pattern (BullMQ format) for the sweep. Default: `0 3 * * *` (daily at 03:00 UTC). Only read when `CONFLICT_DETECTION_ENABLED=true`. |
+
+### Example `backend/.env`
+
+```env
+DATABASE_URL=postgresql://studioflow:yourpassword@localhost:5432/studioflow
+REDIS_URL=redis://:yourpassword@localhost:6379
+JWT_SECRET=a-very-long-random-string-for-access-tokens
+JWT_REFRESH_SECRET=a-different-very-long-random-string-for-refresh-tokens
+GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=GOCSPX-yourGoogleSecret
+GOOGLE_CALLBACK_URL=http://localhost:3001/api/v1/auth/google/callback
+TOKEN_ENCRYPTION_KEY=exactly32characterslongkeyhere!!
+FRONTEND_URL=http://localhost:3000
+PORT=3001
+NODE_ENV=development
+CONFLICT_DETECTION_ENABLED=false
+CONFLICT_DETECTION_CRON=0 3 * * *
+```
+
+---
+
+## Frontend (`frontend/.env.local`)
+
+Create `frontend/.env.local` manually (it is not committed to git and has no `.example` counterpart).
+
+| Variable | Required | Description |
+|---|---|---|
+| `NEXT_PUBLIC_API_URL` | Yes | Backend API base URL. Local: `http://localhost:3001/api/v1` |
+
+### Example `frontend/.env.local`
+
+```env
+NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1
+```
+
+---
+
+## Security Notes
+
+- Never commit `.env` or `.env.local` files to git — both are already listed in `.gitignore`
+- `TOKEN_ENCRYPTION_KEY` must remain stable for the entire lifetime of the database. Rotating it invalidates all stored YouTube OAuth tokens, requiring every channel to be re-authenticated. See [[04 - Gotchas]] for more detail.
+- Use distinct values for `JWT_SECRET` and `JWT_REFRESH_SECRET` — reusing the same secret across both token types weakens the separation between access and refresh token validation
+- In production, use a secrets manager or CI/CD secret injection rather than plain `.env` files