Technical Data Models

Internal data model specifications for the ViralSync platform. This section is useful for understanding how the API maps to underlying storage.

---

The Unified Job Model (jobs)

All long-running tasks share a single jobs table.

Field	Type	Description
id	string (uuid)	Unique job ID. Exposed as jobId in the API.
tenant_id	string	Workspace/brand identifier.
user_id	string	ID of the user who created the job.
kind	enum	agent | workflow | publish | render
type	string	Specific job subtype (e.g., render.movie, render.scene, render.assemble).
status	enum	queued | running | waiting | done | failed | cancelled
priority	enum	low | normal | high
parent_job_id	string | null	Parent job ID for child jobs. null for top-level jobs.
provider	string	Executing runtime: modal, cloudrun, batch, local.
progress	float	0.0–1.0. Exposed as progress in the API.
current_phase	string	Current phase label (e.g., rendering, assembling).
input_ref	string	R2 key or inline JSON for job input payload.
output_ref	string | null	R2 key or URL for the job output. Becomes outputUrl in the API.
error	text | null	Error message if status = "failed".
created_at	timestamp	Job creation time (UTC).
updated_at	timestamp	Last status update time (UTC).

---

Render-specific models

render_plans

The Render Plan is a compiled, immutable representation of the submitted movie JSON. Stored in Cloudflare R2 at path render-plans/{jobId}/plan.json.

{
  "id": "rp_abc123",
  "version": "1.0",
  "project_id": "proj_abc123",
  "parent_job_id": "job_a1b2c3d4e5f6",
  "spec": {
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "scenes": [
      {
        "id": "scene_1",
        "duration": 5.0,
        "bgColor": "#1a1a2e",
        "layers": [ /* ... */ ]
      }
    ]
  },
  "hash": "sha256:e3b0c44298fc1c149afb..."
}

The hash is a deterministic hash of the full spec content. Used for scene-level caching: if a scene's hash matches a previous render, the intermediate clip is reused.

render_scene_jobs (child job metadata)

Additional metadata attached to render.scene jobs:

Field	Type	Description
scene_index	integer	Zero-based position of the scene in the movie.
scene_id	string	The id field from the scene object in the movie JSON.
output_r2_key	string	R2 storage path for the rendered scene intermediate: intermediates/{jobId}/scene_{index}.mp4.
duration_seconds	float	Duration of this scene in seconds.
cached	boolean	Whether this scene was served from cache (skipped rendering).

---

Render usage tracking (render_usage)

Tracks render minute consumption per user per billing period for quota enforcement.

Field	Type	Description
user_id	string	The user account.
billing_period	string	Format: YYYY-MM (e.g., "2026-04"). Resets on the 1st of each month.
render_minutes_consumed	float	Total output video minutes consumed this period.
render_minutes_limit	float | null	Plan limit. null = unlimited (Enterprise).
daily_render_minutes	jsonb	Per-day breakdown: { "2026-04-02": 2.5, "2026-04-03": 1.1 }. Used for Free-plan daily cap enforcement.
last_updated_at	timestamp	Last write (set when a job completes).

How render minutes are recorded: When a render job transitions to done, the system reads mediaData.duration (seconds) from the job output, divides by 60, and adds to render_minutes_consumed for the current billing_period.

---

Subscription model (subscriptions)

Links users to their active plan.

Field	Type	Description
user_id	string	The user account.
plan	enum	free | pro | business | enterprise
status	enum	active | trialing | past_due | cancelled
billing_interval	enum	monthly | annual
current_period_start	timestamp	Start of current billing cycle.
current_period_end	timestamp	End of current billing cycle.
stripe_subscription_id	string | null	Stripe subscription reference (null for free plan).
created_at	timestamp	Subscription creation time.

---

Workflow models (job_executions)

Execution records for workflow automations.

Field	Type	Description
workflow_id	string	ID of the associated workflow definition.
queue_name	string	Worker queue: default, high-priority.
attempts	integer	Number of execution attempts (incremented on retry).
payload	jsonb	Input data passed to the workflow.
error	text | null	Last error message if the execution failed.
created_at	timestamp	When this execution was queued.
completed_at	timestamp | null	When this execution finished (success or failure).