marketing-app/docs/superpowers/plans/2026-03-15-post-composition-redesign.md

Post Composition Redesign — Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Transform Posts from flat entities into composition orchestrators that assemble Caption + Copy (Translations) + Designs (Artefacts) + Video into a publishable unit with auto-computed readiness.

Architecture: Add caption and stage fields to Posts table. New /api/posts/:id/composition endpoint aggregates linked Translations + Artefacts with approval statuses. PostDetailPanel is rewritten as a composition workspace (single scroll, no tabs). Platform→format mapping is a client-side constant.

Tech Stack: Express.js, NocoDB, React, Tailwind CSS

Spec: docs/superpowers/specs/2026-03-15-post-composition-redesign.md

---

File Structure

Server:

• Modify: server/server.js — add caption/stage to Posts TEXT_COLUMNS, new composition endpoint, update POST/PATCH handlers
• Create: server/post-composition.js — helper to compute composition, readiness, and stage auto-advance

Client — New:

• Create: client/src/components/PostCompositionPanel.jsx — the new composition workspace (replaces PostDetailPanel usage)
• Create: client/src/components/PostCompositionCaption.jsx — caption section
• Create: client/src/components/PostCompositionCopy.jsx — linked translations section
• Create: client/src/components/PostCompositionDesigns.jsx — linked design artefacts section
• Create: client/src/components/PostCompositionVideo.jsx — linked video artefact section
• Create: client/src/components/PostCompositionFormats.jsx — platform format checklist
• Create: client/src/components/PostCompositionReadiness.jsx — readiness summary + sign-off
• Create: client/src/utils/platformFormats.js — PLATFORM_FORMATS constant

Client — Modify:

• Modify: client/src/pages/PostProduction.jsx — use PostCompositionPanel instead of PostDetailPanel
• Modify: client/src/pages/CampaignDetail.jsx — same
• Modify: client/src/i18n/en.json / ar.json — new i18n keys

Client — Keep (unchanged):

• PostDetailVersions.jsx, PostDetailPlatforms.jsx, PostDetailApproval.jsx, PostDetailAttachments.jsx — kept for backward compat, old PostDetailPanel still importable

---

Chunk 1: Server — Schema + Composition Endpoint

Task 1: Add caption and stage to Posts schema

Files:

• Modify: server/server.js — TEXT_COLUMNS for Posts (~line 520)

• Step 1: Add new columns to TEXT_COLUMNS

Add to the Posts array in TEXT_COLUMNS:

{ name: 'caption', uidt: 'LongText' },
{ name: 'stage', uidt: 'SingleLineText' },

• Step 2: Update POST /api/posts to accept caption and stage

In the POST handler, add caption and stage to the create payload:

caption: caption || '',
stage: stage || 'copy',

• Step 3: Update PATCH /api/posts/:id to accept caption

Add caption to the allowed update fields.

• Step 4: Commit

git add server/server.js
git commit -m "feat: add caption and stage fields to Posts schema"

Task 2: Create post-composition helper

Files:

• Create: server/post-composition.js

• Step 1: Create the helper module

// server/post-composition.js
const nocodb = require('./nocodb');

// Compute full composition for a post
async function getPostComposition(postId) {
  const post = await nocodb.get('Posts', postId);
  if (!post) return null;

  // Linked translations (copy)
  const allTranslations = await nocodb.list('Translations', {
    where: `(post_id,eq,${postId})`,
    limit: 100,
  });
  const copy = allTranslations.map(t => ({
    id: t.Id,
    language: t.language,
    status: t.status || 'draft',
    is_original: t.is_original,
    title: t.title,
  }));

  // Linked artefacts (designs + video)
  const allArtefacts = await nocodb.list('Artefacts', {
    where: `(post_id,eq,${postId})`,
    limit: 100,
  });
  const designs = allArtefacts
    .filter(a => (a.type || 'design') === 'design')
    .map(a => ({
      id: a.Id,
      title: a.title,
      status: a.status || 'draft',
      thumbnail_url: a.thumbnail_url || null,
    }));
  const videoArtefact = allArtefacts.find(a => a.type === 'video');
  const video = videoArtefact ? {
    id: videoArtefact.Id,
    title: videoArtefact.title,
    status: videoArtefact.status || 'draft',
    thumbnail_url: videoArtefact.thumbnail_url || null,
  } : null;

  // Platforms and formats
  let platforms = [];
  try { platforms = JSON.parse(post.platforms || '[]'); } catch { platforms = post.platform ? [post.platform] : []; }

  // Readiness
  const waitingOn = [];
  const copyNotApproved = copy.filter(c => c.status !== 'approved');
  if (copyNotApproved.length > 0) waitingOn.push(...copyNotApproved.map(c => `Copy (${c.language})`));
  const designsNotApproved = designs.filter(d => d.status !== 'approved');
  if (designsNotApproved.length > 0) waitingOn.push(...designsNotApproved.map(d => `Design: ${d.title}`));
  if (video && video.status !== 'approved') waitingOn.push('Video');

  const piecesReady = copy.length > 0 && waitingOn.length === 0;

  return {
    caption: post.caption || '',
    copy,
    designs,
    video,
    platforms,
    pieces_ready: piecesReady,
    waiting_on: waitingOn,
  };
}

// Auto-compute stage from linked pieces
function computeStage(composition) {
  const { copy, designs, video, pieces_ready } = composition;
  if (pieces_ready) return 'post';
  if (designs.length > 0 || video) return 'design';
  if (copy.length > 1 || copy.some(c => !c.is_original)) return 'translate';
  return 'copy';
}

module.exports = { getPostComposition, computeStage };

• Step 2: Commit

git add server/post-composition.js
git commit -m "feat: add post composition helper (readiness, stage auto-compute)"

Task 3: Add composition API endpoint

Files:

• Modify: server/server.js — add GET /api/posts/:id/composition

• Step 1: Add the endpoint

After the existing GET /api/posts/:id route, add:

app.get('/api/posts/:id/composition', requireAuth, async (req, res) => {
  try {
    const { getPostComposition } = require('./post-composition');
    const composition = await getPostComposition(req.params.id);
    if (!composition) return res.status(404).json({ error: 'Post not found' });
    res.json(composition);
  } catch (err) {
    console.error('Composition error:', err);
    res.status(500).json({ error: 'Failed to load composition' });
  }
});

• Step 2: Auto-update stage on PATCH /api/posts/:id

In the existing PATCH handler, after saving, re-compute and update stage:

const { getPostComposition, computeStage } = require('./post-composition');
const composition = await getPostComposition(req.params.id);
if (composition) {
  const newStage = computeStage(composition);
  await nocodb.update('Posts', Number(req.params.id), { stage: newStage });
}

• Step 3: Also auto-update post stage when Translation or Artefact status changes

In PATCH /api/translations/:id and PATCH /api/artefacts/:id — if the record has a post_id, re-compute the post's stage after saving.

• Step 4: Commit

git add server/server.js
git commit -m "feat: add /posts/:id/composition endpoint + stage auto-update"

---

Chunk 2: Client — Platform Formats + Composition Sub-Components

Task 4: Create platform formats constant

Files:

• Create: client/src/utils/platformFormats.js

• Step 1: Create the file

export const PLATFORM_FORMATS = {
  instagram: [
    { key: 'ig_feed', label: 'Feed (1:1)', ratio: '1:1' },
    { key: 'ig_story', label: 'Story (9:16)', ratio: '9:16' },
    { key: 'ig_reel', label: 'Reel (9:16)', ratio: '9:16' },
  ],
  tiktok: [
    { key: 'tt_video', label: 'TikTok (9:16)', ratio: '9:16' },
  ],
  youtube: [
    { key: 'yt_video', label: 'YouTube (16:9)', ratio: '16:9' },
    { key: 'yt_short', label: 'Short (9:16)', ratio: '9:16' },
    { key: 'yt_thumb', label: 'Thumbnail (16:9)', ratio: '16:9' },
  ],
  facebook: [
    { key: 'fb_post', label: 'Post (1:1)', ratio: '1:1' },
    { key: 'fb_story', label: 'Story (9:16)', ratio: '9:16' },
  ],
  twitter: [
    { key: 'tw_post', label: 'Post (16:9)', ratio: '16:9' },
  ],
  linkedin: [
    { key: 'li_post', label: 'Post (1:1)', ratio: '1:1' },
  ],
  snapchat: [
    { key: 'sc_snap', label: 'Snap (9:16)', ratio: '9:16' },
  ],
}

export function getFormatsForPlatforms(platforms = []) {
  const formats = []
  const seen = new Set()
  for (const p of platforms) {
    for (const f of (PLATFORM_FORMATS[p] || [])) {
      if (!seen.has(f.key)) { seen.add(f.key); formats.push(f) }
    }
  }
  return formats
}

• Step 2: Commit

git add client/src/utils/platformFormats.js
git commit -m "feat: add platform format mapping constant"

Task 5: Create composition sub-components

Files:

• Create: client/src/components/PostCompositionCaption.jsx
• Create: client/src/components/PostCompositionCopy.jsx
• Create: client/src/components/PostCompositionDesigns.jsx
• Create: client/src/components/PostCompositionVideo.jsx
• Create: client/src/components/PostCompositionFormats.jsx
• Create: client/src/components/PostCompositionReadiness.jsx

Each is a small focused component (~40-80 lines) rendering one section of the composition workspace.

• Step 1: Caption section

PostCompositionCaption.jsx — textarea for the social media caption. Props: caption, onChange, disabled.

• Step 2: Copy section

PostCompositionCopy.jsx — shows linked translations as language pills with status icons. Props: copy (array from composition), onLink (opens translation picker), onCreate (creates new translation for this post). Each pill is clickable to open the TranslationDetailPanel.

• Step 3: Designs section

PostCompositionDesigns.jsx — shows linked design artefacts as thumbnail cards with status badges. Props: designs (array), onLink, onCreate, onOpen (opens ArtefactDetailPanel). Shows "+ Add Design" button.

• Step 4: Video section

PostCompositionVideo.jsx — shows linked video artefact (0 or 1) as a card. Props: video (object or null), onLink, onCreate, onOpen.

• Step 5: Formats checklist

PostCompositionFormats.jsx — reads platforms from the post, computes needed formats via getFormatsForPlatforms(), renders as a checkbox list. This is informational only — checkboxes are manual (designer checks off what they've produced). No database storage for checked state (tracked visually only).

• Step 6: Readiness summary

PostCompositionReadiness.jsx — shows bullet list of what's ready and what's blocking. Props: piecesReady, waitingOn (array of strings), onSignOff (callback for approve/schedule button). Sign-off button disabled until piecesReady is true.

• Step 7: Commit

git add client/src/components/PostComposition*.jsx
git commit -m "feat: add composition sub-components (caption, copy, designs, video, formats, readiness)"

---

Chunk 3: Client — Main Composition Panel + Page Integration

Task 6: Create PostCompositionPanel

Files:

• Create: client/src/components/PostCompositionPanel.jsx

• Step 1: Build the panel

This is a SlidePanel-based component (like existing detail panels) but with a composition layout instead of tabs:

Header (title input, status, brand, campaign, platforms, assigned_to, close/save/delete)
─────────
Scrollable body:
  PostCompositionCaption
  PostCompositionCopy
  PostCompositionDesigns
  PostCompositionVideo
  PostCompositionFormats
  PostCompositionReadiness
  CommentsSection

Key behavior:

• On mount: fetches composition via GET /api/posts/:id/composition

• Caption changes are saved with the post (dirty tracking + save button)

• Copy/Design/Video sections have "Link existing" and "Create new" actions

• "Link existing" opens a small picker modal (list of unlinked translations/artefacts)

• "Create new" calls the create API with post_id pre-set, then refreshes composition

• Readiness section shows sign-off button (sets post status to approved)

• Each section is a collapsible card (use CollapsibleSection component)

• Step 2: Add i18n keys

Add to en.json and ar.json:

• post.caption, post.captionPlaceholder, post.copy, post.copyInDesign, post.designs, post.video, post.formatChecklist, post.formatsNeeded, post.readiness, post.allPiecesReady, post.waitingOn, post.signOff, post.approveAndSchedule, post.linkExisting, post.createNew, post.addDesign, post.addVideo, post.linkTranslation, post.noCopyLinked, post.noDesignsLinked, post.noVideoLinked

• Step 3: Commit

git add client/src/components/PostCompositionPanel.jsx client/src/i18n/en.json client/src/i18n/ar.json
git commit -m "feat: add PostCompositionPanel — composition workspace"

Task 7: Wire up PostCompositionPanel in pages

Files:

• Modify: client/src/pages/PostProduction.jsx

• Modify: client/src/pages/CampaignDetail.jsx

• Step 1: Update PostProduction.jsx

Replace PostDetailPanel import and usage with PostCompositionPanel. The panel receives the same props (post, onClose, onSave, onDelete, brands, teamMembers, campaigns) plus the new composition data fetching happens inside the panel.

• Step 2: Update CampaignDetail.jsx

Same — replace PostDetailPanel with PostCompositionPanel for post detail views.

• Step 3: Commit

git add client/src/pages/PostProduction.jsx client/src/pages/CampaignDetail.jsx
git commit -m "feat: wire PostCompositionPanel into PostProduction and CampaignDetail"

Task 8: Final verification

• Step 1: Build check

cd client && npx vite build --logLevel error

• Step 2: Manual test checklist

1. Open a post → composition panel shows caption, copy, designs, video, formats, readiness
2. Edit caption → save → caption persists
3. Link an existing translation → appears in copy section with status
4. Link an existing artefact → appears in designs section with thumbnail
5. Create new design artefact from panel → auto-linked to post
6. Select platforms → format checklist updates
7. Approve all pieces → readiness shows "All pieces ready"
8. Sign off → post status changes to approved
9. Stage auto-advances as pieces are linked

• Step 3: Commit any fixes