Beavous

Product truth, built into every campaign.

Beavous turns one approved ecommerce product into four purposeful concepts, sixteen clean ratios, approved-claim copy, text variants, a portrait reel, QA evidence, Genblaze lineage, and a verified Backblaze B2 campaign package.

• Production: https://beavous.com
• Judge guide: https://beavous.com/judge
• Demo video: 2:33 production walkthrough
• Hackathon: Backblaze Generative Media Challenge

The production judge organization contains both a labelled deterministic recovery showcase and a real paid Gemini campaign. The paid run completed 43/43 durable steps for the owned Field Bottle: four Gemini Flash Image masters, Gemini QA on every master and ratio, sixteen clean ratios, sixteen text variants, approved-claim copy, a 10.005-second Gemini Omni portrait reel with audio, 38 verified Genblaze manifests, and a fetched-byte-verified 40-file ZIP in private B2. Generation is enabled with daily spend/concurrency guards; premium image and video remain separately disabled.

Live and source

• Web: https://beavous.com
• Public judge guide: https://beavous.com/judge
• Owned import fixture: https://beavous.com/demo/field-bottle
• Repository: https://github.com/AmirmLotfy/beavous
• Release truth: docs/release/FINAL_AUDIT.md

beavous.com is the only documented production host. Its Vercel nameservers, TLS, canonical metadata, Supabase Auth callbacks, and API origin policy are release-verified. Domain checks are documented in docs/deployment/DOMAIN_SETUP.md.

System architecture

flowchart LR
  U["Browser"] --> W["Vercel / Next.js"]
  W --> A["Supabase Auth"]
  W --> API["Cloud Run public API"]
  W <--> R["Supabase private Realtime"]
  API --> DB["Supabase Postgres + RLS"]
  API --> Q["Cloud Tasks"]
  Q --> WK["Cloud Run private worker"]
  WK --> G["Genblaze pipelines"]
  G --> M["Gemini / Omni / Veo adapters"]
  G --> B["Private Backblaze B2"]
  B --> V["Manifest + fetched-byte verification"]
  V --> DB

Loading

The API and worker share one pinned container image but use separate app factories, identities, ingress, concurrency, and scaling. Supabase Storage is intentionally unused. See docs/architecture/system.md for the detailed data and trust boundaries.

Repository map

• apps/web — marketing, auth, responsive tenant workspace, Realtime recovery, and browser tests
• apps/api — public API, private task handlers, provider adapters, orchestration, media security
• packages/contracts — FastAPI OpenAPI JSON and generated TypeScript declarations
• supabase — ordered migrations and pgTAP constraint/RLS/budget tests
• infrastructure — Cloud Run, Cloud Tasks, B2 CORS, and Vercel configuration
• scripts — OpenAPI generation, judge/showcase seeds, and production smoke
• docs/release — evidence and release verdict
• docs/devpost — submission copy, guide, shot list, limitations, and checklist

Prerequisites

• Node.js 22.13.1
• pnpm 11.17.0
• uv 0.9.26
• Python 3.12.x
• FFmpeg 8.x
• Supabase CLI 2.90.0 for the pinned release workflow
• Google Cloud and Vercel CLIs only for deployment

Docker is optional for ordinary development. It is required for a local Supabase reset; this repository can instead run pgTAP against an explicitly linked remote test project.

Local setup

corepack enable
pnpm install --frozen-lockfile
uv sync --project apps/api --frozen
cp .env.example .env.local
pnpm dev

In a second terminal:

pnpm api:dev

The web app is available at http://localhost:3000 and the API at http://localhost:8080. When Supabase public variables are absent, /app renders a clearly labelled local preview. Once Supabase is configured, /app always requires a valid session; there is no production preview bypass.

Environment contract

Copy names from .env.example; never commit values.

Runtime	Required for non-generative operation
Web	NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_API_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
API/worker	SUPABASE_URL, SUPABASE_SECRET_KEY, SUPABASE_DB_URL, Cloud Tasks settings
Live media	Worker-only GEMINI_API_KEY, B2 endpoint/region/key/buckets, verified-capability flags, and GENERATION_ENABLED=true only after proof

Cloud Run uses its service account and does not use GOOGLE_APPLICATION_CREDENTIALS. Production generation, premium image, and premium video switches default to false.

Quality and security gates

pnpm contracts:generate
pnpm check
pnpm test:e2e
pnpm audit --audit-level high

uv export --project apps/api --format requirements-txt --no-dev --no-hashes \
  --no-emit-project --output-file /tmp/beavous-api-requirements.txt
uvx --python 3.12 pip-audit --no-deps --disable-pip \
  -r /tmp/beavous-api-requirements.txt

supabase db lint --linked --schema public,app_private,app_audit \
  --level warning --fail-on error

pnpm check covers formatting, ESLint, strict TypeScript, Vitest, Ruff, strict mypy, pytest, both builds, and API startup/import behavior. Playwright covers Chromium-sized desktop and WebKit mobile layouts, material axe violations, keyboard focus, guarded workflow states, and horizontal overflow. Real provider/B2 calls are opt-in and never run in ordinary CI.

Pillow 12.3.0 is a deliberate security override over Genblaze Core 0.3.8's stale <12 metadata. The complete provider/media suite guards the compatibility boundary.

Database workflow

supabase link --project-ref umcjccsfmnqykknjxvwg
supabase db push --linked --dry-run
supabase db push --linked

Run the pgTAP files against a disposable or explicitly approved database. They open a transaction and roll it back:

psql "$SUPABASE_DB_URL" -X -v ON_ERROR_STOP=1 -f supabase/tests/constraints.sql
psql "$SUPABASE_DB_URL" -X -v ON_ERROR_STOP=1 -f supabase/tests/rls.sql
psql "$SUPABASE_DB_URL" -X -v ON_ERROR_STOP=1 -f supabase/tests/budget.sql
psql "$SUPABASE_DB_URL" -X -v ON_ERROR_STOP=1 -f supabase/tests/realtime.sql

Deployment

The current production topology is Vercel plus two Cloud Run services in europe-west3, Cloud Tasks in the same region, and a dedicated Supabase project in eu-central-1.

gcloud builds submit apps/api \
  --project beavous --region europe-west3 \
  --tag europe-west3-docker.pkg.dev/beavous/beavous/api:0.2.23

export BEAVOUS_IMAGE=europe-west3-docker.pkg.dev/beavous/beavous/api:0.2.23
export SUPABASE_URL=https://umcjccsfmnqykknjxvwg.supabase.co
export SITE_URL=https://beavous.com
./infrastructure/gcp/deploy-worker.sh
./infrastructure/gcp/deploy-api.sh

vercel --prod
./scripts/smoke/production.sh \
  https://beavous-api-rz3cyj7xhq-ey.a.run.app \
  https://beavous.com

Production explicitly deploys with GENERATION_ENABLED=true only after the model catalog, live text/image/video calls, B2 sink, manifest verification, budget recovery, and complete paid campaign passed. Premium image and premium video stay off unless separately approved.

Judge account

The judge identity is a normal non-admin tenant owner. Its password exists only in restricted Secret Manager and the private Devpost testing field.

SUPABASE_URL=... SUPABASE_SECRET_KEY=... JUDGE_EMAIL=... JUDGE_PASSWORD=... \
  node scripts/seed/judge.mjs

The account seed is idempotent. The deterministic showcase seed runs real Genblaze pipelines through the private B2 sink, verifies each manifest and fetched object, and only then persists the campaign records:

SUPABASE_DB_URL=... B2_ENDPOINT_URL=... B2_REGION=... B2_KEY_ID=... \
B2_APPLICATION_KEY=... B2_MEDIA_BUCKET=... B2_KEY_PREFIX=beavous/production \
  uv run --project apps/api python scripts/seed/showcase.py

See docs/release/SHOWCASE_VERIFICATION.md for the credential-free proof.

Models and providers

Work	Default	Fallback
Truth, planning, QA	gemini-3.6-flash	gemini-3.5-flash-lite
Preview image	gemini-3.1-flash-lite-image	gemini-3.1-flash-image
Master/ratio image	gemini-3.1-flash-image	gemini-3-pro-image
Fast reel	gemini-omni-flash-preview	veo-3.1-fast-generate-preview
Premium reel	veo-3.1-generate-preview	none
Overlays/thumbnails/ZIP	deterministic provider	none

All listed IDs passed models.get on 2026-07-29. The deployed key completed live gemini-3.6-flash, gemini-3.1-flash-image, and gemini-omni-flash-preview calls. The complete campaign used Flash Image for four masters, Flash/Flash-Lite for planning, copy, and QA, and Omni for the reel. Premium fallbacks are catalog-verified but intentionally feature-flagged off. See docs/devpost/MODELS_AND_PROVIDERS.md.

How B2 and Genblaze are central

Every generative or deterministic media operation is a named Genblaze pipeline with stable tenant, application-run, attempt, and Genblaze-run identifiers. Corrections use from_result so Genblaze's parent lineage is preserved.

Private B2 is the deployed authoritative store for sources, normalized references, prompts, intermediates, failures, corrected/final outputs, evaluations, thumbnails, manifests, verifications, and ZIPs. The database stores durable object keys and hashes, never signed URLs. Final assets require canonical manifest verification plus a second hash of bytes fetched from B2. This proves integrity, not authorship.

The complete paid production campaign proves the combined path: real Gemini masters and Omni video run through project-local Genblaze providers, strict ObjectStorageSink persistence in private B2, 38/38 canonical manifest verifications, and 38/38 independently fetched media hashes. The video passes signed GET, range 206, FFprobe, and full FFmpeg decode. The deterministic package is a 40-file ZIP whose fetched SHA-256 matches the asset record. A separate labelled showcase preserves a genuine from_result parent-linked correction for the judge walkthrough.

Known limitations and release status

• The paid complete campaign passed, but its four masters did not require corrective regeneration. Parent-linked correction evidence remains available in a separate real historical run and the explicitly labelled deterministic judge showcase.
• A public B2 showcase bucket is blocked by Backblaze's payment-history requirement; the private canonical bucket is unaffected.
• Preview model entitlement, capacity, latency, and pricing remain account-dependent.
• Product fidelity/claim QA is model-assisted; human approval is authoritative.
• Automated browser coverage uses desktop Chrome and an iPhone-sized WebKit profile; a physical iPhone/Android device pass remains manual.
• Devpost submission remains the user's manual final action. Judges use the credential-free, server-backed live entry on /login; credentials never enter public source or browser code. Creative workflows are writable under shared daily campaign, spend, and concurrency guards; identity settings and account deletion remain protected.

See docs/devpost/KNOWN_LIMITATIONS.md for the submission-facing version.

License and security

Beavous is MIT licensed. Report vulnerabilities privately as described in SECURITY.md. Full Git history and working-tree Gitleaks scans are required before every release.