Skip to content

Development

Repository layout

AI_Marketing_Studio/
├── web/                      # ★ the v2 app (Next.js 14) — studio, Director, renderer
│   ├── src/
│   │   ├── app/              # App Router: page.tsx (editor), (shell)/{email,svg,settings},
│   │   │   │                 # login/, and api/ route handlers
│   │   │   └── api/          # director/* · media/[...path] · assets · assets/upload
│   │   ├── components/       # StudioV2, DirectorPanel, ReviewPanel, DeliverPanel,
│   │   │   │                 # ChatPanel, TimelineV2, inspector/, intake/
│   │   ├── director/         # the AI engine: orchestrator, roles, runner, llm/, store/,
│   │   │   │                 # assemble, catalog, voiceover, docextract
│   │   ├── document/         # irStore.ts (Zustand IR + undo/redo), chatStore.ts
│   │   ├── lib/              # storage.ts (STORAGE_ROOT map), remotion bundle helpers
│   │   ├── legacy/           # ported v1 pages (EmailFlyer, SvgGen, Settings, Login)
│   │   └── middleware.ts     # auth gate (validates via Express /api/auth/me)
│   └── remotion/
│       ├── Root.tsx          # registers StudioDoc + every blueprint as a Composition
│       ├── index.ts          # render-bundler entry
│       ├── document/         # ir.ts, blueprint.ts, registry.ts, VideoDocument.tsx,
│       │   │                 # SceneShell.tsx, timing.ts, assets.tsx, blueprints/
│       └── templates/modules # 216 template modules (X.tsx + X.module.ts)
├── server/                   # Express API (auth, email, svg, settings, brand) — v1 kept
│   └── src/{routes,pipeline,middleware}  # paths.ts derives dirs from STORAGE_ROOT
├── packages/                 # @dexian/* workspace libs (back the Express features)
├── storage/                  # file-backed data (projects, media, renders) — dev
├── docs/                     # design docs + plans
├── Wikki/                    # this wiki (mkdocs-material)
├── Dockerfile · docker-compose.yml · docker-start.sh
└── .github/workflows/        # deploy-acr.yml

Local dev loop

npm install                 # root workspaces (server + packages/*)
cd web && npm install       # the Next.js app (separate node_modules)
cd ..
# put Azure keys + JWT_SECRET/ALLOWED_USERS in a repo-root .env
npm run dev                 # Express :3001 + Next.js :3000

npm run dev frees stale ports, then runs dev:server (builds @dexian/*, then ts-node-dev for Express) and dev:web (next dev with EXPRESS_ORIGIN=http://localhost:3001) concurrently. Open http://localhost:3000.

WSL note: npm isn't available in some WSL setups — web/node_modules may be a local copy and node/tsc run from Git Bash. See the team's WSL gotchas memo if a build step can't find npm.

Common tasks

Add a template module

  1. Create web/remotion/templates/modules/MyScene.tsx (the view) + MyScene.module.ts (Zod schema + metadata)
  2. Hand-edit the barrel templates/modules/index.ts (one import + one ALL_MODULES entry — no generator script)
  3. Add presets/MyScene.json with demo props (validated against the schema)
  4. cd web && npm run typecheck

Add a blueprint (whole-video starter)

  1. Create web/remotion/document/blueprints/myThing.ts, modeled on saasLaunch.ts
  2. Export a VideoBlueprint + a resolved ir
  3. Register it in blueprints/index.ts BLUEPRINTS[] — Root.tsx auto-maps it to a Composition

See Blueprints & Templates.

Add an app page

  1. Add a route under web/src/app/ (App Router). Authenticated pages go under (shell)/ or use AuthGuard.
  2. Add a nav entry in web/src/components/NavLinks.tsx
  3. If it needs a backend, add a handler under web/src/app/api/ (or proxy to Express via next.config rewrites)

Add a Director capability

The engine is web/src/director/. The two LLM roles (Analyst, Copywriter) sit behind roles.ts with llmRoleRunner and stubRoleRunner implementations; runner.ts picks based on Azure config. Keep new behavior working under the stub path so the system runs offline.

Work on the legacy Express features

Email/SVG/brand pipelines live in server/src/. Build the @dexian/* packages first (npm run build:workspace-libs). These are reached through the Next.js proxy in dev and prod.

Type checking

cd web && npm run typecheck       # tsc --noEmit for the Next.js app

Style & conventions

  • TypeScript strict mode across web/, server/, and packages/
  • The ResolvedIR is the single source of truth — mutate it through the irStore actions, never out of band
  • Template modules are pure, data-driven views validated by Zod — no side effects, no AI at render time
  • New AI behavior must degrade gracefully to the stub runner
  • Don't edit packages/templates/src/video/ — it's the retired v1 template system

Design docs

Significant changes get a doc under docs/ first. Relevant current ones:

  • migration-plan-design.md / v2-gaps-and-risks.md — the v1 → v2 merge and its open risks
  • storage-and-azure-mounts.md — the single-share storage model
  • director-agent-design.md — the Director engine
  • render-unification-plan.md — preview = render parity (the principle the v2 system inherits)

Editing this wiki

npm run wiki:dev      # live-reload mkdocs at http://localhost:8000
npm run wiki:build    # static build to Wikki/site/

Pages live under Wikki/docs/; nav is configured in Wikki/mkdocs.yml.