StudioFlow Backend

🗺 What is this?

StudioFlow is an internal YouTube metadata management platform. The backend handles all business logic: structured description rendering, bulk metadata updates, YouTube API sync with quota management, metadata linting, and import/export.

The codebase is a single NestJS monorepo with two independent entry points — an HTTP API server and an asynchronous BullMQ worker — sharing all modules and services.

🔧 Tech Stack

📁 File Structure

Every folder under src/ has a single, clearly scoped responsibility.

🚀 Entry Points

src/main.ts — HTTP Server

Bootstraps the full NestJS application with all feature modules registered.

• Global ValidationPipe with whitelist: true and transform: true — strips unknown fields, auto-converts types
• Global prefix /api/v1 on all routes
• Swagger UI available at /api/docs (OpenAPI 3)
• CORS configured for FRONTEND_URL (default: http://localhost:3000)
• Cookie parser for refresh token httpOnly cookies

src/worker.ts — BullMQ Worker

Creates an ApplicationContext (no HTTP server) using WorkerModule. Only loads the modules that contain job processors — no controllers are registered.

src/app.module.ts vs worker.module.ts

⚙ Shared Layer

These modules have no HTTP controllers. They are pure service classes used by feature modules and worker processors alike.

PrismaService (shared/prisma/)

Extends PrismaClient directly. Implements OnModuleInit and OnModuleDestroy to call $connect() and $disconnect(). Registered as a @Global() module so it never needs to be re-imported.

@Injectable()
export class PrismaService extends PrismaClient
  implements OnModuleInit, OnModuleDestroy {

  async onModuleInit()    { await this.$connect(); }
  async onModuleDestroy() { await this.$disconnect(); }
}

AuditService (shared/audit/)

Single method log(actorId, entityType, entityId, action, before?, after?). Called by every service that mutates data. Writes to the AuditLog table with full before/after JSON snapshots.

QuotaService (shared/quota/) — see next section

RenderEngineService (shared/render-engine/) — see next section

🖨 Render Engine

The render engine is pure TypeScript with zero I/O. It takes all data as input and returns a string. It lives in shared/render-engine/ so both the API (for previews) and the worker (for bulk renders) can use it identically.

render-engine.service.ts — Pipeline

Input: RenderInput containing the VideoConfig fields, an array of resolved DescriptionBlock objects, and an array of Collaborator objects.

Output: { rendered: string, hash: string }

Block type handling

hash.ts — SHA-256 metadata hash

hashMetadata({ title, description, tags, categoryId }) produces a SHA-256 hex string over JSON.stringify(data). This hash is stored as lastSyncedHash on the Video and renderHash on VideoConfig. Before any YouTube sync the worker compares the current hash against the stored one — if identical, zero API units are consumed.

export function hashMetadata(data: {
  title: string; description: string;
  tags: string[]; categoryId?: string | null;
}): string {
  return createHash('sha256')
    .update(JSON.stringify(data))
    .digest('hex');
}

📊 Quota Service

YouTube Data API v3 resets at midnight Pacific Time. The quota service enforces a 9,000-unit daily cap (10% reserve below the 10,000 limit).

Tranche scheduling

When a Bulk Job would exceed the day's remaining quota, the YouTube Sync processor calls job.moveToDelayed(msUntilQuotaReset()) to defer those jobs to the next Pacific midnight automatically — no manual intervention needed.

🔐 Auth Module

Authentication uses Google OAuth 2.0 for identity + YouTube token acquisition, then issues short-lived JWTs for API access.

OAuth Flow

Key files

Token storage security

YouTube access and refresh tokens are encrypted with AES-256-CBC before being written to the database. The encryption key comes from TOKEN_ENCRYPTION_KEY env var, derived via scryptSync.

🛡 Roles & Guards

Four roles with a priority hierarchy. The RolesGuard checks that the user's priority meets the minimum required for the endpoint.

Sensitive endpoints requiring EDITOR+

• POST /videos/bulk-apply
• POST /videos/:id/sync
• POST /imports/csv/commit and /imports/json/commit
• POST /bulk-jobs/:id/rollback

ADMIN-only

• DELETE /saved-views/:id (global views)

▶ Videos Module

Central module. All video list/filter/bulk operations live here.

Full-text search

The search query param builds a Prisma OR condition across title (case-insensitive LIKE) and tags (array contains). No full-text index is required for moderate data volumes.

Supported bulk action types

• SET_PRIVACY — change privacyStatus for all matched videos
• SET_TEMPLATE — assign a template
• ADD_TAGS / REMOVE_TAGS — array manipulation
• SEARCH_REPLACE_TITLE — string replace in title

☰ Blocks Module

Description blocks are the atomic content units. They are versioned — every update creates an immutable BlockVersion snapshot before applying changes.

Version snapshot logic

// On every PATCH:
1. Load current block
2. INSERT BlockVersion { contentSnapshot: { ...currentBlock }, version: block.version }
3. UPDATE block SET { ...dto, version: version + 1 }
4. AuditService.log()

◫ Templates Module

Templates define a named, reusable block sequence. They also carry default variable values and rule definitions (e.g., required links). Like blocks, templates are versioned.

Template schema fields (JSONB)

• defaultBlocks — ordered array of block IDs
• rules — e.g. { "requiredLinks": ["https://..."] } — used by lint rules
• variables — default values for {placeholder} tokens

🎛 Video Configs Module

A VideoConfig is the reconstruction key for a video's description. It stores which blocks are active, in what order, with what variable values and which collaborators — not the final text. The final text is always reconstructable from this config.

Config fields

• blockOrder — string[] — ordered block IDs
• blockOverrides — { [blockId]: { content?, active? } } — per-video overrides
• variableValues — { [key]: value } — fills {placeholder} tokens
• collaboratorIds — string[] — IDs used for collaborator block expansion
• autoRender?: boolean — if true, queues a render job immediately on save

◉ Collaborators Module

Collaborators are entities, not free text. They are referenced by ID in the VideoConfig and resolved at render time into their actual handle, name, and links.

Placeholder tokens in blocks

• {collab_name} → Rhea Vale
• {@youtube_handle} → @RheaPlays
• {twitch_link} → https://twitch.tv/rheavale

✦ Linting Module

Ten pluggable lint rules. Each is a class implementing LintRule. New rules can be added without touching existing code.

LintRule interface

interface LintRule {
  code: string;
  severity: LintSeverity; // INFO | WARNING | ERROR
  check(video: any): LintIssue | null;
}

All 10 rules

LintingService.lintVideo(videoId)

1. Load video with config + template + collaborators
2. Load campaign blocks for expiry check
3. Run all 10 rules → collect non-null LintIssue results
4. DELETE existing unresolved LintResults for this video
5. INSERT new LintResult rows
6. Compute overall lintStatus: ERROR > WARNING > OK
7. UPDATE video.lintStatus

⇅ Bulk Jobs Module

Bulk jobs follow a dry-run → confirm → execute → rollback lifecycle.

Lifecycle

Each BulkJob has one BulkJobItem per affected video. The item stores the before snapshot and after snapshot so rollback is a simple record-by-record restore.

⊿ Saved Views Module

Saved views are reusable filter presets stored as JSON. They can be applied to the video table, used as a scope for exports, or fed into bulk jobs as a video selector.

4 default views (seeded on startup)

• All sponsor videos — tags contain "sponsor"
• Needs chapters — lintStatus WARNING
• Missing CTA — lintStatus WARNING
• Published this month — publishedAt ≥ first day of current month (dynamic placeholder resolved at execute time)

📅 Calendar Module

Returns calendar-shaped entries for scheduled and published videos. Frontend can use these to render month/week/agenda views.

Each calendar entry shape: { videoId, title, date, templateName, collaborators[], lintStatus, channelId, privacyStatus }

↑↓ Import / Export

CSV Import

Supports these columns: youtube_video_id, title, tags, category_id, privacy_status, scheduled_at, template_name, collaborators.

Each row is validated with a Zod schema. Errors are returned as [{ row, field, message }]. An ImportJob record is created at preview time to track the state.

JSON Import/Export

Full workspace format covers all entity types:

{
  "version": "1.0",
  "exportedAt": "2026-04-27T...",
  "videos": [...],
  "videoConfigs": [...],
  "blocks": [...],
  "templates": [...],
  "collaborators": [...],
  "savedViews": [...]
}

Import upserts all entities by ID, so re-importing a backup is idempotent.

CSV Export

Accepts { videoIds?, savedViewId? }. If neither is provided, exports all videos. Returns a streamed text/csv response with a Content-Disposition: attachment header.

🔴 YouTube Sync Module

Wraps the googleapis YouTube Data API v3 client. The YouTubeApiClient handles OAuth token decryption and the YouTubeSyncService adds quota accounting and conflict detection.

YouTubeApiClient

• getVideoMetadata(youtubeVideoId) — videos.list, part: snippet + status, cost: 1 unit
• updateVideoMetadata(id, meta) — videos.update, part: snippet + status, cost: 50 units

YouTubeSyncService.detectConflict(videoId)

Fetches the current YouTube snippet, hashes it, and compares with lastSyncedHash. If they differ, sets video.remoteConflict = true — which will be caught by the REMOTE_CONFLICT lint rule on the next lint run.

YouTube Sync Worker (processor)

1. Load video + config from DB
2. Render description with RenderEngineService
3. Hash new metadata → compare with lastSyncedHash
   → identical? SKIP (0 units spent)
4. quota.canSpend(50)?
   → no? moveToDelayed(msUntilQuotaReset())
5. ytSync.pushUpdate(video, meta)
6. quota.spend(50, 'videos.update', videoId)
7. UPDATE video.lastSyncedHash + lastSyncedAt

⟳ BullMQ Queues & Processors

Default job options (bulk-metadata)

{
  attempts: 3,
  backoff: { type: 'exponential', delay: 2000 },
  removeOnComplete: { age: 7 * 24 * 60 * 60 }, // keep 7 days
  removeOnFail: false                              // keep failed jobs for analysis
}

Chained jobs: Render → Lint

When the render processor finishes, it immediately enqueues a lint job so the lint status is always fresh after any render. This means a PUT /video-configs/:videoId with autoRender: true triggers: save config → render job → lint job.

💹 Quota & Audit Log API

Quota endpoint

Audit log endpoints

Every mutation that goes through a service method calls AuditService.log() with a full before/after JSON snapshot. This gives a complete change history for any entity.

🔑 Environment Variables

⚡ Getting Started

1. Install dependencies

cd backend
npm install

2. Set up environment

cp .env.example .env
# Fill in all required values in .env

3. Generate Prisma client

npx prisma generate

4. Run migrations (requires running PostgreSQL)

npx prisma migrate dev --name init

5. Start the API server

npm run start:dev
# → http://localhost:3001/api/v1
# → http://localhost:3001/api/docs  (Swagger UI)
# → http://localhost:3001/health    (Docker healthcheck)

6. Start the worker (separate terminal)

npm run start:worker

Via Docker Compose

# First-time migration:
docker compose --profile tools run --rm migrate

# Start all services:
docker compose up -d

MVP Phase summary