---
name: flypic-ugc-reference-pipeline
description: Wire Character Manager references into flypic's visual workflow builder and image-generation pipeline for UGC ads
---
# Flypic UGC Reference Pipeline
## When to use
- Adding UGC-ad workflows, character-consistent variations, or reference-stack features to flypic (`/home/bigceo/Desktop/Development/flypic/`).
- A task asks to connect character/location/style references to flypic's workflow builder or `/api/generate`.
- Generating multiple character-consistent ad variations from one script.
## How to apply
1. **Reuse, don't reinvent.** The reference system already exists — read these first: `types/characters.ts` (helpers `toPromptRef`, `getPrimaryImageUrl`, `getAllCharacterImageUrls`), `hooks/useCharacters.ts`, `components/CharacterSelector.tsx`, `components/CharacterReferenceModal.tsx`, `lib/nano-banana-pro.ts`, and `app/admin/visualWorkflowActions.ts` (the `WorkflowNode` type).
2. **Bridge layer in `src/lib/ugc/`.** Add a `character-workflow-bridge.ts` that resolves character IDs → `{ promptRef, imageUrls, refs, missingIds }`, isomorphic (resolve from a passed-in list, else fall back to `/api/characters`). Emit `@mention` tokens via a shared `slugifyMention()`.
3. **Templates as data.** Put prompt/scene structures in `src/data/` (e.g. `ugcPromptTemplates.ts`) with `id/name/description/sceneStructure[]` and a `getById()` accessor. Add workflow templates in `workflowBuilderTemplates.ts` using ONLY existing node types (`text-input`, `ai-text`, `image-set`, `ai-image`, `telegram`); register the new category in `getTemplateCategories()`.
4. **Extend the category union additively.** Widen `WorkflowTemplate.category` with the new value (e.g. `'ugc-ad'`) — existing consumers read it loosely, so this is non-breaking.
5. **Generation route stays backward compatible.** In `src/app/api/generate/route.ts`, accept `referenceImages` as `string[]` OR structured `{ characterId, imageUrl, role, description }[]` (or a mix); add a `normalizeReferenceImages()` that flattens & de-dupes to URLs. Downstream `ai-generation.ts` already forwards `referenceImages` to the model — don't touch it.
6. **Variation generator** in `src/lib/ugc/`: deterministically cycle hook/angle/background axes, inject the consistency block + reference image URLs, return `{ prompt, refImages, variationDescription }[]`.
7. Typecheck with `tsc`; ignore the pre-existing unrelated error in `admin/guided-tours/generate/route.ts`.
## Rules
- Never scaffold new components when CharacterSelector/CharacterReferenceModal/useCharacters/useAssets already cover the UX — mirror their patterns instead.
- Never invent new workflow node types; compose from existing ones.
- Always keep `/api/generate` backward compatible — accept legacy `string[]` alongside structured refs.
- Always reuse the helpers in `types/characters.ts` for prompt refs and image-URL extraction.