solar/docs/CAMPAIGN_POST_CONTENT_FLOW_PLAN.md

Campaign, Post & Content Flow – Plan for a Complete X/SaaS Presence

Context: New X (and optionally Instagram) account for the Solar Production Forecasting SaaS (degelas.be). Goal: make the campaign → post → content flow as complete as possible, and identify where custom or advanced agents per stage would add value. This is a plan before adjustments (no code changes yet).

---

1. End-to-end flow (current vs ideal)

1.1 Pipeline today

Stage	What exists	Owner / automation
1. Strategy / planning	Campaigns = date window + optional max_posts. No themes, pillars, or editorial calendar.	Human only.
2. Content creation	Fixed content templates (feature teaser, product overview) + product/feature catalog. Preview in PR UI. Optional expand-and-create from schedule + template.	Human picks template + feature; no variation or AI.
3. Scheduling	Schedule templates (days_of_week, time_slots_utc, platform_slots). Expand returns slots; expand-and-create fills campaign with generated posts.	Human picks campaign + schedule template; backend expands.
4. Validation	Backend enforces X 280, Instagram 2200, max N posts per platform per day (global + campaign override).	Backend (automatic on create/update).
5. Persistence	Scheduled posts in DB (pending → posted/failed/cancelled). CRUD + bulk create.	Backend + PR UI.
6. Publishing	Scheduler job (e.g. every minute) → due posts → do_browser_post → degelas-chrome (CDP). Status updated to posted/failed.	Automated (no agent logic).
7. Measurement	None. No stored post URL, no impressions/likes/clicks, no link to campaign or template.	—

So today: human-driven strategy and content, automated schedule expansion and publishing, no feedback loop.

1.2 Ideal “complete” flow for a new X account

• Strategy: Thematic calendar (e.g. solar basics → prices → EV → battery) and/or content pillars aligned to product features; campaigns tied to themes.
• Content: Multiple variants (tone, CTA, feature rotation), optional live data (today’s kWh, cheap hours), optional AI suggestions; thread/carousel planning if needed.
• Scheduling: Best-time awareness (or at least timezone/audience), mix of platforms and times per campaign, optional “draft → approve → schedule”.
• Validation: Same as now; optional pre-flight check (e.g. “this week already has 5 X posts”).
• Persistence: Same; optional draft status or “on hold” without deleting.
• Publishing: Same + retries/notifications; optionally store post URL when available (for later analytics).
• Measurement: Store post URL; optionally pull X/Instagram metrics (impressions, engagement) and attribute to campaign/template for iteration.

---

2. Stage-by-stage and where agents fit

Stage 1: Strategy / planning

Purpose: Decide what to talk about and when (thematic calendar, campaign windows, pillars).

Need	Current	Possible “agent” / automation
Thematic calendar (e.g. Q2: solar + prices, Q3: EV)	No	Strategy agent: Input = product context + feature list + optional goals (e.g. “focus on EV this quarter”). Output = suggested campaign names + date windows + suggested feature mix per week. Can be rule-based (rotate features) or LLM (“suggest a 4-week calendar for a new X account”).
Content pillars	Implicit (features)	Explicit pillars in product context (e.g. “Solar”, “Prices”, “EV & battery”) and map features → pillar. Strategy agent can suggest “2 posts pillar A, 1 post pillar B per week”.
Campaign ↔ theme link	Campaign has name, dates, max_posts only	Optional theme_id or content_pillar on campaign; strategy agent suggests campaigns from themes.

Agent scope: One Strategy / planning agent that consumes product context + (optional) goals and outputs suggested campaigns and/or a high-level calendar. Can be rules first (e.g. “one campaign per month, rotate features”) then enhanced with LLM for richer suggestions.

---

Implemented (Strategy): POST /generate/suggest-campaigns returns AgentResult with data.campaigns (name, start_date, end_date, suggested_feature_ids). Rules-based; PR Campaigns page: "Suggest next 3 months".

---

Stage 2: Content creation

Purpose: Produce post copy (and optionally assets) that is on-brand, within limits, and optionally data-driven.

Need	Current	Possible “agent” / automation
Variety	Few fixed templates; same structure	Content agent: (A) Template + variation: more templates + rotate features/CTAs; (B) AI: given slot (platform, feature, campaign theme), generate 1–3 variants; (C) Hybrid: template as structure, AI for one line or tone.
Live data	No	Live-data hook: Before render, call e.g. GET /metrics or GET /prices/pattern for “today’s estimate: X kWh” or “cheap hours this week: …”. One content template (or AI prompt) that includes {{today_kwh}} or {{cheap_hours}}. Can be a small “context enrichment” step before template or AI.
Tone / audience	Same for all	Optional “tone” or “audience” in campaign or slot (e.g. professional vs friendly); content agent (template rules or AI) picks wording.
Threads / carousels	No	Future: “thread plan” (N tweets) or “carousel” plan; content agent produces N copy blocks; publish flow may need multi-step post.
Approval / draft	No	Optional status “draft” for scheduled posts (or separate draft store); content agent produces draft, human edits, then “approve → schedule”.

Agent scope: One Content agent that, given (campaign/slot, feature, platform, optional theme/tone), produces one or more copy variants. Implementation can be: (1) template-only with more templates and feature rotation; (2) optional AI endpoint (e.g. POST /generate/suggest-posts) with product context as system prompt; (3) live-data enrichment for selected templates.

Implemented (Live data): Preview accepts include_live_data: true and optional location_id; async enrich_context_live_data() sets today_kwh from stored daily metrics (default BE location). PR Generate page: "Include live data" checkbox. Template "Solar today (X)" uses {{today_kwh}}.

---

Stage 3: Scheduling

Purpose: Decide when each post goes out (slots per platform, per day, within limits).

Need	Current	Possible “agent” / automation
Slot list	Schedule templates + expand; campaign window	Done. Optional: Schedule agent suggests “best” template or times (e.g. 09:00, 12:00, 18:00 UTC) from simple rules or external “best time to post” data.
Platform mix	In schedule template (platform_slots)	Done. Optional: per-campaign override (e.g. “X only” for first month).
Cap per day	Global + campaign override	Done.
Timezone / audience	UTC only	Optional: “audience TZ” or “post in local 09:00 Brussels” → convert to UTC in schedule template or expand.

Agent scope: Schedule agent is optional: given campaign window and optional constraints (e.g. “X only”, “max 2 per day”), suggest or validate a schedule template and optionally adjust time_slots_utc. Can be rule-based (no LLM).

---

Stage 4: Validation

Purpose: Ensure every post respects platform rules and policy before persist.

Need	Current	Possible “agent” / automation
Length, posts/day	Enforced on create/update	Done.
Pre-flight check	No	Optional: “dry run” for a campaign (expand + validate without creating); or UI warning “You already have 5 X posts on 2025-03-15”.
Policy / safety	No	Optional: blocklist words or link check; simple validator before create.

Agent scope: Validation is mostly rules; optional Validation step (pre-flight or pre-create) that runs the same rules and returns warnings/errors. No “creative” agent needed.

---

Stage 5: Persistence & publishing

Purpose: Store scheduled posts and send them to X/Instagram at the right time.

Need	Current	Possible “agent” / automation
Store posts	CRUD + bulk	Done.
Publish	Scheduler + degelas-chrome	Done.
Post URL	Not stored	Enhancement: When degelas-chrome (or browser flow) can return the created post URL, store it on ScheduledPost (e.g. posted_url). Enables measurement.
Retry / failure	Status failed, error_message	Optional: Publish agent or job – retry failed posts (e.g. exponential backoff, max 3); notify (email/Slack) on repeated failure.
Hold / pause	Cancel or delete	Optional: campaign or global “pause scheduling” so job skips due posts until resumed (or use status “paused”).

Agent scope: Publish agent = current job + optional retry logic and notification. No LLM; operational only.

---

Stage 6: Measurement & iteration

Purpose: Know what worked and feed it back into strategy and content.

Need	Current	Possible “agent” / automation
Post URL	Not stored	Stored in Stage 5.
Impressions, likes, clicks	No	Analytics agent (future): For each posted row with posted_url, call X API (or scraping if no API) to get metrics; store in DB (e.g. post_insights table: post_id, impressions, likes, retweets, clicks, fetched_at).
Attribution	No	Link insights to campaign_id and (if stored) content_template_id or feature_id. Reports: “best performing campaign”, “best template/feature”.
Feedback to strategy	No	Use “top posts” / “underperforming” to suggest more of X or less of Y in next strategy run (manual today; later a Strategy agent could take “last month performance” as input).

Agent scope: Analytics agent (periodic job): fetch metrics for posts with posted_url, store and optionally expose in PR UI. Later: simple “performance by campaign/template” and optional input to Strategy agent.

---

3. Proposed agents (summary)

Agent	Stage	Input	Output	Priority for “complete”
Strategy / planning	1	Product context, features, optional goals/quarter	Suggested campaigns, date windows, theme/pillar mix	Medium (nice to have for new account)
Content	2	Slot/campaign, feature, platform, optional theme/tone, optional live data	1+ copy variants (template or AI)	High (variety + optional AI + live data)
Schedule	3	Campaign window, constraints	Suggested/validated schedule template or slots	Low (current expand is enough to start)
Validation	4	Pending posts or “dry run” payload	Warnings/errors (length, caps, optional safety)	Low (existing validation is enough)
Publish	5	Due posts	Post + store URL, retry, notify	Medium (store URL + retry/notify)
Analytics	6	Posted posts with URL	Stored metrics; reports by campaign/template	Medium (after URL storage)

Recommended order for “as complete as possible” without overbuilding:

1. Content: More templates + feature rotation, optional live-data hooks, optional AI suggest endpoint. (Biggest impact on “feels complete” for a new account.)
2. Publish: Store posted_url when available; optional retry + notify. (Enables measurement and reliability.)
3. Analytics: Store and display basic metrics per post/campaign when URL is available. (Closes the loop.)
4. Strategy: Thematic calendar + optional Strategy agent (rules or LLM) for suggested campaigns. (Makes planning scalable.)
5. Schedule / Validation: Only if you need “best time” or pre-flight UX; otherwise current behaviour is enough.

---

4. Data model and API (minimal for plan)

• Campaign: Already has name, start_date, end_date, max_posts override. Optional later: theme_id, content_pillar, tone.
• ScheduledPost: Already has platform, text, scheduled_at, status, posted_at, error_message. Add (when feasible): posted_url (nullable).
• Post insights (new, later): e.g. post_id, impressions, likes, retweets, clicks, fetched_at (or use existing analytics stack if you have one).
• Content templates / schedule templates: Already in code; can stay or move to DB if you need per-account or many templates.

No schema change required for “plan only”; posted_url and insights are the first concrete additions when you implement.

---

5. Plan before adjustments (checklist)

• Decide scope: X only at launch, or X + Instagram from day one?
• Strategy: Start with manual campaigns + existing schedule templates, or invest in thematic calendar + Strategy agent (rules first)?
• Content: Add more templates + feature rotation only, or also (a) live-data hooks and (b) AI suggest endpoint?
• Publish: Confirm with degelas-chrome/browser flow whether post URL can be returned; if yes, add posted_url and retry/notify.
• Measurement: Add analytics agent (and optional post_insights table) once URLs are stored, or rely on X Analytics UI only for now?
• Agents: Implement in order: Content (templates + variation + optional AI) → Publish (URL + retry) → Analytics → Strategy (optional).

This plan keeps the current flow (campaign → content → schedule → validate → persist → publish) and makes it complete by adding: clearer strategy layer, richer content (variation + live data + optional AI), URL storage and optional retry/notify, and measurement so you can iterate. Custom “agents” are introduced only where they add clear value (Content, optional Strategy, optional Schedule, Publish logic, Analytics).