Tubematic — Technical Documentation

Tubematic turns a topic into a finished YouTube Short: it researches topics, writes a script, voices it, generates imagery, animates it in code, renders an mp4, has an AI watch the result for defects, and stops at three points where a human has to say yes.

Every scene is a React component an AI agent writes for that specific video, compiled and rendered by Remotion. The output is real code, which is why you can read exactly what produced any frame.

This folder is the complete technical documentation. It assumes no prior knowledge of the project and is written for developers who intend to build on it.

---

Start here

1 · Overview	What it is, what it produces, the design decisions that shape everything else, and a glossary. Read this first.
2 · Architecture	Containers, processes, how they talk, where files live, the repository map, and the failure model
3 · Getting Started	Prerequisites, install, installing an agent, your first video, verifying an install, uninstalling
4 · The Pipeline	The state machine in full — every status, every transition, the human checkpoints, and the revision loop

Reference

Look things up here.

5 · Database	Every table and column, the migration model, and how to add one
6 · Settings	All 41 keys, and how credentials are stored, masked and verified
7 · HTTP API	Every Flask route — parameters, responses, status codes, and known quirks
8 · MCP Server	All 38 agent tools, validate_job's checks, and the scene-work claim

Subsystems

9 · The Agent Layer	Skills, slash commands, installing an agent and how videos are assigned to one
10 · Scripting and Voice	Script segments, length budget, pronunciation and pause markup, timeline.json, script profiles
11 · The Remotion Project	The frame model, compositions, dynamic scene dispatch, scene-config.json, the installed component library
12 · Scene Authoring	How a scene gets written — the two visual registers, the PHOTO / HYBRID / DIAGRAM / STICK taxonomy, cadence, the revision path, adding a component
13 · Rendering and Review	The render worker, timeouts and retries, Gemini video review, the text-layout audit
14 · Publishing	Publishing to YouTube, Instagram, TikTok and Facebook, and polling analytics back
15 · The Dashboard	The Next.js app — pages, components, the proxy and stream routes, the action model
21 · The Worker	The always-on loop that renders, settles posts, runs Auto Pilot and the timed sweeps — every pass, its order and how often it runs
22 · The Poller	poll.py, the cron-started supervisor that runs agent sessions — the loop, the three lanes, one stage per session, timeouts and orphans

Operations and development

16 · Infrastructure	Compose services, volumes, images, cron, and day-to-day operating commands
17 · Development	Where verification belongs, release tooling, the CI/CD workflow shape, conventions, and contributing
Tests	Every test suite — what each file guards, how to run it, and the traps each one encodes
18 · Troubleshooting	Symptoms and where the cause usually is
19 · Releases and Upgrades	What a release consists of, versioning policy, image tags, backups and rollback, and upgrade instructions for both install routes
20 · Release Notes	What changed in each published release. The single source for release notes — the release workflow publishes the matching section as the GitHub Release body

---

Reading routes

Just want to run it. Overview → Getting Started → The Pipeline for what the statuses mean.

Want to change how videos look. Overview → The Remotion Project → Scene Authoring. This is the main extension surface.

Want to change how the AI behaves. The Pipeline → The Agent Layer → MCP Server. Most behaviour lives in markdown skills, not code.

Integrating something external. Architecture → HTTP API → Database.

Something is broken. Troubleshooting.

---

Conventions in these docs

• Code is cited by symbol — pipeline.py::patch_video — never by line number, so a citation cannot rot when a file is edited above it.
• Diagrams are inline ```mermaid fences, rendered natively by GitHub. There is no build step.
• No test counts, suite totals, or dated claims. Run the suite.
• Where a design decision looks wrong or over-engineered, the reason is stated. Those notes are the most valuable part of this documentation and the easiest to accidentally undo.

These documents are public and must never carry stale information. Any change that adds or alters a tool, route, settings key, status, schema column, component or skill rule is not finished until the relevant page reflects it — and until the neighbouring claims it invalidated have been re-checked. See Development — Keeping the docs true.