Skip to content

System

Architecture

Process layout, persistence, and where state lives.

Architecture

Veyra is three cooperating pieces: the Next.js studio, the Python beat service, and PostgreSQL (via Prisma). Binary assets (audio, ref plates, renders) stay on disk; the database holds structured planner and project state.

Topology

┌────────────────────────────┐         ┌────────────────────────────┐
│ Next.js (port 3000)         │  HTTP  │ Beat service (port 8011)   │
│  React 19 / Next 16+       │  REST  │  FastAPI / Uvicorn         │
│  App Router, RSC where used│  ◄──►  │  beat_this, Demucs, etc.  │
│  Prisma (Postgres)         │        │  faster-whisper (lyrics)  │
└──────────────┬─────────────┘        └────────────────────────────┘
               │ Prisma
               ▼
        ┌──────────────┐
        │  PostgreSQL  │   project rows, per-step tables, messages
        └──────────────┘
               │
               │ file paths + URLs in DB; bytes on disk
               ▼
   ┌────────────────────────────┐
   │ public/projects/<id>/        │   mix, refs, generated stills / mp4
   │ beat-service/.cache/         │   model + stem caches
   │ src/data/filming_styles.json │  shipped style catalogue (read-only)
   └────────────────────────────┘

dev.sh starts Next + the beat service. Start Postgres with docker compose up -d (or your own instance) and run npx prisma migrate dev when the schema changes.

Why this shape

  • Postgres + Prisma — planner sessions, steps, and chat are relational and normalized (see prisma/schema.prisma). That replaces an older “JSON files only” experiment; the in-app Data Model doc describes the contract at the TypeScript layer (src/types/planner-session.ts).
  • Beat service is a separate process — PyTorch import and model load are slow; isolating them keeps the Node dev server snappy and leaves models warm in one OS process.
  • Server-side I/O — heavy work (Gemini, fs under public/projects/, beat-service calls) lives in src/app/api/**/route.ts and src/lib/. Client components hold UI state only.

App router layout

  • src/app/layout.tsx — root HTML, theme cookie, ThemeProvider, globals.
  • src/app/page.tsx — redirects / → /video-plan/inputs.
  • src/app/(studio)/layout.tsx — StudioNav + main column for studio routes.
  • src/app/(studio)/** — Dashboard, Video Plan (/video-plan/[[...segments]]), Timeline, etc.
  • src/app/(studio)/docs/** — Markdown docs viewer (files under docs/).
  • src/app/api/** — REST handlers; planner mutations are mostly under /api/planner/....

The (studio) group keeps a consistent chrome for studio pages while /docs uses its own layout.

See also