architecture-contract

Documents load-bearing design invariants and weak points of the Marine Video Portal codebase.

Updated Jul 3, 2026
One-click install
npx skills add https://github.com/MarineTeam/fable-video --skill architecture-contract-marineteam
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: architecture-contract
Source: https://github.com/MarineTeam/fable-video/tree/main/.claude/skills/architecture-contract
Command: npx skills add https://github.com/MarineTeam/fable-video --skill architecture-contract-marineteam

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When modifying auth, admin routes, sharing, playback, or the Redis/bunny.net data layer of the Marine Video Portal, developers risk breaking hidden invariants (normalized email identity, fail-closed approval, signed embed URLs, cache invalidation) that are not obvious from the code alone. This Skill provides the design-time mental model explaining why the system is shaped the way it is before any change is designed. ## Core Features & Use Cases - Numbered invariants: Each invariant states what must hold, why, where it is enforced (file and line references), and a grep/sed command to re-verify it against the current codebase. - Known weak points: Documents accepted risks and deliberate asymmetries (e.g., approval fails closed while rate limiting fails open) so they are not accidentally "fixed". - Skill routing table: A "when NOT to use this skill" section directs users to sibling skills like change-control, security-response, or debugging-playbook for other task types. - Use Case: Before adding a new bunny.net mutation, consult invariant (f) to learn that every mutation must call invalidateVideoListCache, then verify with grep that the call-site count matches expectations. ## Quick Start Load the architecture-contract skill before designing any change to auth, admin routes, sharing, video playback, or Redis keys in the Marine Video Portal.

Frequently Asked Questions about architecture-contract

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I safely change auth or admin routes in the Marine Video Portal?

Read the architecture contract first: every /api/admin/* route must independently call requireCapability, identity comparisons must use normalizeEmail, and approval must fail closed on Redis errors. Each invariant lists enforcement points and grep commands to verify your change preserves them.

Why does the app never serve direct bunny.net CDN video URLs?

Direct CDN file URLs would be permanent, unauthenticated bypasses of every access check. Playback uses only signed, time-limited embed URLs minted per request by signEmbedUrl with a 3-hour expiry, scoped to a single video.

When should I use the architecture-contract skill versus change-control?

Use architecture-contract when you need to understand why the system is built a certain way before designing a change. Use change-control for the mechanics of which gates, tests, and PR steps to run before merging.

Why does rate limiting fail open while viewer approval fails closed?

The asymmetry is deliberate: failing approval open would leak the private video library during a Redis outage, while failing rate limiting closed would lock out every real user over an unrelated infra hiccup. Neither direction should ever be flipped.

What must I do when adding a new bunny.net video mutation?

Every bunny.net mutation must call invalidateVideoListCache immediately after its API call, because listAllVideos caches the library for 4 seconds per warm serverless instance. Forgetting invalidation leaves deleted or changed videos visible for up to 4 seconds.