core-architecture-patterns
Skill35 starsChanged 14 days agoMITView on GitHub
Use when adding a segment type, platform adapter, editor manager, core service, or descriptor effect (look/grade/motion/text/section-audio field), integrating a registered effect backend in packages/ffmpeg-video-composer, or when wiring new dependencies into the tsyringe container.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- authoring-video-templatesSkill
- cross-platform-ffmpegSkill
- monorepo-dev-workflowSkill
- ondevice-ffmpeg-engineSkill
- pr-creationSkill
- pr-evidenceSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Add the section schema variant in packages/ffmpeg-video-composer/src/schemas/section.schemas.ts (extend BaseSectionSchema, add to the …
- Very specific: line 24
Create editor/segments/<Name>Segment.ts following an existing segment (e.g.
- Very specific: line 26
Add a test under packages/ffmpeg-video-composer/tests/.
- Very specific: line 62
Use @singleton() for shared models/state, @injectable() for services.
- Distinctive: line 69
Keep platform capabilities behind adapters and select them at the appropriate entry point.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Core Architecture Patterns
Overview
packages/ffmpeg-video-composer is built from a few repeating patterns: adapters abstract the platform, the PlatformBridge selects them for Node while browser/native entry points register them directly, tsyringe DI wires everything, and a director → builder → segments → managers pipeline compiles a template. Follow these patterns; reuse existing pieces before adding new ones. Full design: docs/architecture.md.
The pipeline
TemplateDirector (packages/ffmpeg-video-composer/src/director/TemplateDirector.ts) orchestrates:
init → build each section → concat → apply music.
- Sections created by
SegmentFactory(editor/factories/SegmentFactory.ts) → rendered by*Segmentclasses (editor/segments/). - FFmpeg commands assembled by editor managers (
editor/managers/): asset, variable, map, filter, formatter. VideoEditorconcatenates;MusicComposermixes audio.
Adding a segment type
- Add the section schema variant in
packages/ffmpeg-video-composer/src/schemas/section.schemas.ts(extendBaseSectionSchema, add to theSectionSchemadiscriminated union);template.schemas.tsre-exports it. Keep the manual descriptor shape insrc/core/types.d.tsin sync. - Create
editor/segments/<Name>Segment.tsfollowing an existing segment (e.g.VideoSegment.ts); use@injectable(). - Register it in
editor/factories/SegmentFactory.ts(map the newtypeliteral → class). - Add a test under
packages/ffmpeg-video-composer/tests/.
An authoring effect section follows a different route: EffectReferenceSchema in schemas/effect-reference.schema.ts defines its JSON contract, and core/resolve-template-effects.ts resolves it into a project_video clip plus userVideoPaths before compilation. The core never launches Remotion. Extend the trusted Node backend/catalog in packages/leclap-mcp/src/effects/ for registered graphics, validate props/assets during preflight, and expose contracts through get_effect_schema; do not add a Remotion segment to SegmentFactory.
Adding a descriptor effect
A structured-sugar effect (a look/grade/motion/section-audio field — not a raw filters[] escape hatch) follows this recipe end to end, proven across Phases 1-4 (LUT looks, chroma key, overlay motion, grain, letterbox, stylized looks, shake/pulse, audioEffect):
- Schema field — add the field/variant in
packages/ffmpeg-video-composer/src/schemas/*.schemas.ts(effects-visual.schemas.tsfor grade/look/motion;reveal.schemas.tsandtext.schemas.tsfor text motion/blocks;section.schemas.tsfor section-level fields/options). Update the corresponding manual types insrc/core/descriptor-visual.d.ts,src/core/descriptor-text.d.ts,src/core/filter-types.d.ts, orsrc/core/types.d.ts;template.schemas.tsis the public re-export/type-inference facade. Every field keeps a.describe()— it feedsdocs/template-descriptor.schema.json. - Preset / lowering fn — a pure
*ToFiltersfunction or aLOOK_TABLE/MOTION_HANDLERSrow insrc/editor/presets/(looks.ts,motion.ts). LGPL discipline:eqrequires the existingeq→lutyuvcompatibility lowering (eqValueToLutyuv); avoid unsupportedgeq/boxblurand check the device filter allowlist. A section-audio effect instead extends the-afchain builder insrc/editor/utils/audio-fade.ts. - Registry entry — wire the compiler into
SUGAR_COMPILERSinsrc/editor/presets/registry.ts(orderedlayers → motion → grade → look → letterbox → caption → titleCard → lowerThird— pick anorderbetween the neighbours it must sit next to), aLOOK_TABLErow, or aMOTION_HANDLERSentry. - Tests — TDD: exact command-string/filter-array assertions first, in the matching suite (
tests/looks.test.ts, the motion or audio-fade tests). Then a real-compile fixture: JSON underpackages/ffmpeg-video-composer/tests/fixtures/+ an id added toeffects-fixtures.test.ts'sFIXTURESarray (validates against the schema AND smoke-compiles through the Node engine — rc 0). - LGPL audit — declare any newly emitted filter in
ENGINE_EMITTED_FILTERS(src/editor/utils/filter-compat.ts). It must exist in the--enable-filter=list inscripts/ffmpeg/common.shor have an explicit tested compatibility rule;tests/lgpl-filter-audit.test.tschecks those paths and the generated device filter list. Do not enable a GPL filter to satisfy the audit. - Regen —
pnpm --filter ffmpeg-video-composer generate:schema(writesdocs/template-descriptor.schema.json) andgenerate:capabilities, in the same commit as the schema change. - Builder exposure — when the feature is intended for the template editors, add a
FEATURE_CONTROLSentry inpackages/leclap-creative-kit/src/editor/control-metadata.ts. If the field is new on the creative-kit section model (not already flowing through an existing inferred type likeGrade/MotionEffect), also wiremodel.ts/build-descriptor-fragments.ts/to-editor-state.tsfor build/rehydrate round-tripping. Then the web panel (apps/leclap-web/src/presentation/components/admin/editor/*Panel.tsx) + Expo panel (apps/leclap-expo/src/features/templates/components/*Fields.tsx) + i18n keys in all five locales, in both apps. - Docs — add the field to
docs/template-configuration.mdin the same commit as the schema regen (this is the field reference authors read;authoring-video-templates/SKILL.mdlinks to it). - Device rebuild — a NEW FFmpeg filter (not just a descriptor field reusing filters already shipped) needs the on-device engines rebuilt before it works in the app:
scripts/ffmpeg/build-engine.sh androidthenios(sequential, never concurrent). The LGPL audit only proves the filter can run on the LGPL config — the currently-shipped.so/xcframework binaries don't have it until they're rebuilt.
Adding a platform adapter
- Implement the matching
Abstract*base inpackages/ffmpeg-video-composer/src/platform/<capability>/(e.g.AbstractFFmpeg,AbstractFilesystem,AbstractLogger). Name it<Thing><Platform>Adapter. - For Node, register/select it in
PlatformBridge.ts. Browser and native entry points register directly; do not import the Node bridge into those bundles. - Wire it into the container at the appropriate entry point:
index.ts(Node),browser.ts(browser/WASM), orreactnative.ts(native).
Dependency injection (tsyringe)
@injectable()
class VideoEditor {
constructor(@inject('ffmpegAdapter') private readonly ffmpeg: AbstractFFmpeg) {}
}
// at the Node entry point
container.registerInstance('ffmpegAdapter', await bridge.create('ffmpeg'));- Use
@singleton()for shared models/state,@injectable()for services. - Register by string token in
index.ts/browser.ts/reactnative.ts; resolve viacontaineror constructor injection. reflect-metadatamust be imported once at the entry point or all DI breaks at runtime.
Conventions
- PascalCase class + file name;
Abstract*bases;*Adapterimplementations;*Managerfor the editor layer. - Keep platform capabilities behind adapters and select them at the appropriate entry point. Runtime checks may belong in entry points or explicitly Node-only helpers; keep those imports out of browser/native shared paths.
- Validate with
pnpm --filter ffmpeg-video-composer exec tsc --noEmit, thenpnpm testandpnpm lint.
Common mistakes
- Adding a segment to the factory but forgetting the schema union (or vice versa) → validation/runtime mismatch.
- Importing a Node-only module from code that also runs in the browser bundle (
browser.tspath) — put it behind an adapter. - Forgetting to wire a new adapter in each supported entry point (and the Node bridge where applicable).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

