docs: complete project research

Files: - STACK.md - FEATURES.md - ARCHITECTURE.md - PITFALLS.md - SUMMARY.md Key findings: - Stack: FastAPI 0.135.1 + React 19 + Vite 7 + Tailwind v4, single-container deploy - Architecture: FastAPI serves React SPA via catch-all, file-based storage (Docker volume), LLMService with retry/backoff - Critical pitfall: All 9 pitfalls map to Phase 1 — Italian prompts, Canva field constants, UTF-8 BOM, root_path config, per-item bulk isolation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-07 14:06:44 +01:00
parent dd601a0d08
commit fe6cd4d516
5 changed files with 1667 additions and 0 deletions
--- a/.planning/research/FEATURES.md
+++ b/.planning/research/FEATURES.md
@@ -0,0 +1,226 @@
+# Feature Research
+
+**Domain:** Social media content automation / Instagram carousel bulk generator (B2B)
+**Researched:** 2026-03-07
+**Confidence:** MEDIUM-HIGH (ecosystem surveyed, product is novel niche — partial direct comparisons)
+
+---
+
+## Context
+
+PostGenerator is not a generic social media scheduler or a simple AI writer. It sits at the intersection of three product categories:
+
+1. **Bulk content generation tools** (PostNitro, aiCarousels, Templated) — generate individual carousels
+2. **Editorial calendar / content planning tools** (CoSchedule, StoryChief, SocialPilot) — plan and schedule
+3. **LLM prompt management systems** (Agenta, PromptHub, PromptLayer) — manage AI generation
+
+No direct competitor was found that combines all three with strategic frameworks (Schwartz levels, Persuasion Nurturing, narrative formats) and Canva Bulk Create CSV output. This is a **purpose-built tool**, so feature categorization is based on user expectation from adjacent tools plus the project's specific domain logic.
+
+---
+
+## Feature Landscape
+
+### Table Stakes (Users Expect These)
+
+Features that, if missing, make the tool feel broken or incomplete. These are non-negotiable for v1.
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| **Generate a 13-post editorial cycle** | Core value proposition — the entire reason the tool exists | HIGH | Orchestrates all strategic layers: Persuasion Nurturing distribution, Schwartz levels, narrative formats, niches. The central "one-click calendar" function. |
+| **Canva-compatible CSV export** | Without this, the tool has no usable output | MEDIUM | Header must exactly match Canva Bulk Create schema. Each row = one carousel. 8 slide columns per carousel. Metadata columns included for analysis. |
+| **LLM content generation per slide** | Users expect AI to produce actual copy, not just metadata | HIGH | Claude API integration. JSON-structured output per carousel with all 8 slides. Prompt must produce consistent slide structure. |
+| **Format selector (tipo_contenuto x schwartz → formato)** | Core strategic logic — wrong format selection breaks campaign coherence | MEDIUM | Mapping table: content type + awareness level → narrative format (PAS, AIDA, BAB, etc.). Can be rules-based initially, no ML needed. |
+| **Niche rotation (B2B verticals)** | Content must feel relevant to different target audiences | LOW | 50% generic PMI, 50% rotating through dentists/lawyers/ecommerce/local/agencies. Simple round-robin or weighted random. |
+| **Topic generation (auto + manual override)** | Users need starting points; experts need control | MEDIUM | LLM generates topic suggestions per niche/type; user can override before generation. Hybrid model prevents "blank page" paralysis. |
+| **Web UI (not CLI)** | Modern tool expectation; Michele explicitly chose Web UI | HIGH | FastAPI backend + React frontend. Minimum: calendar view, generate button, output review, CSV download. |
+| **Prompt editor (file-based, editable via UI)** | Content quality depends on prompt quality; prompts must be tweakable | MEDIUM | Prompts stored as files; UI renders and allows editing without code. One prompt per combination (tipo x formato). |
+| **Generation output review before export** | Users must see what was generated before committing to CSV | MEDIUM | Per-carousel preview: show all slide content, metadata tags, image keywords. Allow re-generation of individual carousels. |
+| **Campaign phase tagging** | Metadata in CSV must include attira/cattura/coinvolgi/converti phase | LOW | Assigned during cycle planning, not AI-generated. Rules-based mapping from content type. |
+| **Suggested publish dates** | Calendar output needs dates, even if publishing is manual | LOW | Auto-assign based on cycle start date + post index. Two carousels per week = 6-7 week cycle for 13 posts. |
+
+### Differentiators (Competitive Advantage)
+
+Features that no generic tool offers. This is where PostGenerator earns its existence.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| **Persuasion Nurturing cycle orchestration** | Ensures the 13-post mix is always strategically balanced (4 valore, 2 storytelling, 2 news, 3 riprova, 1 coinvolgimento, 1 promozione) | MEDIUM | The generator enforces mix rules, not the user. Output is never an ad-hoc list of posts — it's a coherent 2-week nurturing arc. |
+| **Schwartz awareness level assignment** | Each post targets the right audience mindset for that funnel stage | MEDIUM | L5→L1 mapping integrated into prompt selection. Most tools ignore where the audience is in their buyer journey. |
+| **7 narrative format library** | PAS, AIDA, BAB, Listicle, Storytelling/Eroe, Dato+Implicazione, Obiezione+Risposta — all optimized for carousel format | HIGH | Each format needs its own prompt structure because slide decomposition differs. PAS has 3-act structure; Listicle has variable item count. |
+| **8-slide carousel structure enforcement** | Structured 8-slide schema (Cover, Problema, Contesto, Sviluppo A/B/C, Sintesi, CTA) ensures design-ready output | MEDIUM | Claude must output content fitting exactly the 8-slide structure. CSV columns are pre-mapped to slide positions. Canva template slots match exactly. |
+| **B2B niche-aware copy** | Same topic, different framing for dentists vs. lawyers vs. ecommerce. Dramatically increases perceived relevance | MEDIUM | Niche injected into prompt context. Each niche has distinct pain points, vocabulary, and objections. |
+| **Swipe File for idea capture** | Quick capture of external inspiration (ads, posts, headlines) that can influence future topic generation | LOW | Simple CRUD for saving ideas, snippets, references. Optional tagging by format or niche. Feed into topic selection as context. |
+| **Image keyword generation per slide** | Every slide gets 1-2 search keywords for stock photo sourcing in Canva | LOW | Extracted by LLM during content generation. Optionally resolved to actual URLs via Unsplash API (when key available). |
+| **Copywriting rules enforcement** | Built-in guardrails: "cosa fare" not "come farlo", tono diretto-provocatorio, nessun gergo, focus su imprenditori italiani | MEDIUM | Encoded in system prompt and per-format templates. Not user-configurable (by design — this is the brand voice). |
+| **Single-post generation mode** | Generate one carousel on demand with full parameter control (tipo, formato, nicchia, livello Schwartz) | MEDIUM | Useful for ad-hoc content, testing, or filling gaps in an existing calendar. Reuses same generation engine as bulk mode. |
+| **Campaign naming and grouping** | Each 13-post cycle is a named campaign with its own output folder and CSV | LOW | Enables history browsing: "Campagna Marzo settimana 1", "Campagna Aprile dentisti". Simple folder/file naming convention. |
+
+### Anti-Features (Things to Deliberately NOT Build)
+
+Features that seem valuable but would undermine the product's purpose, add disproportionate complexity, or belong in Phase 2+ only.
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| **Direct Instagram publishing** | "Why download a CSV if I can post directly?" | Requires Instagram Business API + Meta App Review + OAuth. Adds compliance surface. Publishing quality control (visual review) is critical and belongs in Canva — that's the whole point. | Keep the Canva workflow. The CSV+Canva+manual-publish chain is deliberate, not a limitation. Document this clearly. |
+| **Automatic scheduling calendar** | Every content tool has a scheduler | Scheduling is a solved problem (Buffer, Later, Metricool). Building it duplicates commodity software. Also: Canva doesn't support scheduling carousels via its own API in all cases. | Suggest publish dates in CSV. Let user paste into their preferred scheduler. |
+| **Analytics / performance tracking** | "Show me which posts performed best" | Requires Instagram Insights API, engagement data storage, attribution logic. This is an entirely separate product domain. Premature before content engine is validated. | Out of scope per PROJECT.md. Phase 2 if content engine proves valuable. |
+| **Multi-user / team collaboration** | "Share with my VA" | Adds authentication, role management, permission systems, conflict resolution. High complexity for a personal tool. | Single-user by design. If team use is needed later, add basic HTTP auth first. |
+| **Real-time LLM streaming** | "Show text appearing as it's generated" | Adds websocket/SSE complexity to backend. For batch generation of 13 posts, streaming UX is confusing (13 parallel streams?). | Generate all, show loading state, display results. Simpler and actually better UX for batch workflows. |
+| **Automatic A/B testing of prompts** | "Which prompt version performs better?" | Requires performance data linkage back from Instagram (see Analytics above). Without actual engagement data, A/B testing is cosmetic. | Let user manually edit prompts and observe output quality. Add versioning if needed. |
+| **Brand voice training / fine-tuning** | "Make it sound more like me" | Fine-tuning Claude is not available via API. RAG-based voice imitation adds significant complexity. Claude with well-engineered prompts in Italian is already adequate. | Encode brand voice in system prompt. Offer prompt editor for adjustments. |
+| **Image generation (AI)** | "Generate images instead of keywords" | AI image generation (DALL-E, Midjourney) produces generic or uncanny results for B2B professional content. Adds cost and quality uncertainty. Canva has its own image tools. | Generate Unsplash keywords. Let Canva handle image sourcing with its built-in library. |
+| **Relational database** | "Use PostgreSQL for scalability" | No multi-user, no concurrent writes, no complex queries. File system is simpler, version-controllable, and inspectable. Premature optimization for a personal tool. | File system: prompts/ outputs/ data/ per PROJECT.md decision. Revisit only if scale demands it. |
+
+---
+
+## Feature Dependencies
+
+```
+[Calendar Generator]
+    ├──requires──> [Format Selector]
+    │                  └──requires──> [Persuasion Nurturing Rules]
+    │                  └──requires──> [Schwartz Level Mapping]
+    │                  └──requires──> [Narrative Format Library]
+    ├──requires──> [LLM Content Generation]
+    │                  └──requires──> [Prompt Editor / File Store]
+    │                  └──requires──> [Niche Context Injection]
+    ├──requires──> [CSV Builder]
+    │                  └──requires──> [Canva Header Schema]
+    │                  └──requires──> [Image Keyword Generator]
+    └──requires──> [Output Review UI]
+
+[Single Post Generator]
+    └──requires──> [LLM Content Generation]  (reuses same engine)
+    └──requires──> [Format Selector]         (reuses same logic)
+
+[Swipe File]
+    └──enhances──> [Topic Generation]        (swipe items can inform topic context)
+
+[Image Keyword Generator]
+    └──enhances──> [Unsplash API Fetch]      (optional, only if API key present)
+
+[Output Review UI]
+    └──requires──> [Generation History]      (per-campaign output storage)
+
+[Prompt Editor]
+    └──conflicts──> [Copywriting Rules Enforcement]
+    (user can break rules via prompt edits — document that editing overrides guardrails)
+```
+
+### Dependency Notes
+
+- **Calendar Generator requires Format Selector:** Without the mapping logic (tipo x schwartz → formato), the generator cannot assign narrative formats to each of the 13 posts in the cycle.
+- **LLM Content Generation requires Prompt Editor:** Prompts are the intelligence layer. If prompts are hardcoded and not editable, output quality cannot be improved without code changes.
+- **CSV Builder requires Canva Header Schema:** The CSV header must match Canva's template placeholders exactly. This schema is fixed upfront and determines the entire data model.
+- **Single Post Generator reuses Calendar engine:** Build once, expose in two modes. Do not create a separate code path for single-post — it creates drift.
+- **Swipe File enhances Topic Generation:** Swipe items can be passed as context to the LLM when generating topics, but the dependency is loose (topic gen works without swipe file).
+- **Image Keyword Generator enhances Unsplash Fetch:** Keywords are always generated. Unsplash fetch is an optional enrichment step gated on API key availability.
+
+---
+
+## MVP Definition
+
+### Launch With (v1)
+
+Minimum set to validate the core content engine. Everything below must work together for a usable output.
+
+- [ ] **Calendar Generator** — Produces 13-post cycle with correct Persuasion Nurturing distribution
+- [ ] **Format Selector** — Maps tipo_contenuto x schwartz_level → narrative_format deterministically
+- [ ] **LLM Content Generation** — Claude API generates all 8 slides per carousel as structured JSON
+- [ ] **Prompt File Store + Editor** — Prompts editable via UI without code deployment
+- [ ] **Image Keyword Generation** — At least 1-2 keywords per slide (no Unsplash fetch in v1)
+- [ ] **CSV Builder** — Output matches Canva Bulk Create header exactly, downloads as file
+- [ ] **Output Review UI** — Show generated carousels before export; allow regenerating individual posts
+- [ ] **Single Post Generator** — On-demand generation with parameter override (useful for testing)
+- [ ] **Swipe File** — Capture and retrieve inspiration items (simple CRUD, no LLM integration in v1)
+- [ ] **Campaign History** — Named output folders; browse and re-download past generations
+
+### Add After Validation (v1.x)
+
+Add once the content engine is proven and output quality is validated through actual use.
+
+- [ ] **Unsplash Integration** — Resolve image keywords to actual URLs when API key is present; trigger: Michele obtains Unsplash API key
+- [ ] **Swipe File → Topic Context** — Pass swipe items to LLM during topic generation; trigger: swipe file in regular use
+- [ ] **Campaign performance notes** — Free-text notes per campaign ("this cycle performed well for dentists"); trigger: after first real publishing cycle
+- [ ] **Bulk topic input** — Paste multiple topics, generate entire calendar per topic; trigger: workflow bottleneck identified
+
+### Future Consideration (v2+)
+
+Defer until product-market fit confirmed and use patterns established.
+
+- [ ] **Analytics linkage** — Import engagement data from Instagram Insights; defer: requires platform API + post-publishing data
+- [ ] **Multi-campaign comparison** — Compare content mixes across campaigns; defer: needs history depth
+- [ ] **Team / shared access** — Basic auth for sharing with VA or client; defer: personal tool for now
+- [ ] **LinkedIn adaptation** — Repurpose carousel content for LinkedIn carousel format; defer: different platform mechanics
+
+---
+
+## Feature Prioritization Matrix
+
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| Calendar Generator (13-post cycle) | HIGH | HIGH | P1 |
+| LLM Content Generation (8 slides/carousel) | HIGH | HIGH | P1 |
+| CSV Builder (Canva-compatible) | HIGH | MEDIUM | P1 |
+| Format Selector (tipo x schwartz → formato) | HIGH | LOW | P1 |
+| Prompt File Store + Editor | HIGH | MEDIUM | P1 |
+| Output Review UI | HIGH | MEDIUM | P1 |
+| Niche rotation (B2B verticals) | HIGH | LOW | P1 |
+| Image Keyword Generation | MEDIUM | LOW | P1 |
+| Single Post Generator | MEDIUM | LOW | P1 |
+| Swipe File (CRUD) | MEDIUM | LOW | P1 |
+| Campaign History / naming | MEDIUM | LOW | P1 |
+| Unsplash API fetch | MEDIUM | LOW | P2 |
+| Swipe File → Topic context injection | MEDIUM | MEDIUM | P2 |
+| Campaign performance notes | LOW | LOW | P2 |
+| Bulk topic input | LOW | MEDIUM | P3 |
+| Analytics linkage | HIGH | HIGH | P3 |
+
+**Priority key:**
+- P1: Must have for launch
+- P2: Should have, add when possible
+- P3: Nice to have, future consideration
+
+---
+
+## Competitor Feature Analysis
+
+No direct competitor found that matches PostGenerator's specific combination. Closest adjacent tools:
+
+| Feature | PostNitro | aiCarousels | StoryChief | PostGenerator (ours) |
+|---------|-----------|-------------|------------|----------------------|
+| Carousel generation | Yes (AI) | Yes (AI) | No | Yes (AI via Claude) |
+| Bulk generation (batch 13+) | No | No | Partial | Yes (core feature) |
+| Canva CSV export | No | No | No | Yes (primary output) |
+| Strategic framework (Schwartz/Nurturing) | No | No | No | Yes (differentiator) |
+| Editorial calendar | No | No | Yes | Yes (13-post cycle) |
+| Narrative format library | No | No | No | Yes (7 formats) |
+| Niche rotation | No | No | No | Yes (B2B verticals) |
+| Prompt editor | No | No | No | Yes (file-based) |
+| Multi-platform scheduling | Yes | Yes | Yes | No (deliberately) |
+| Direct publishing | Yes | No | Yes | No (deliberately) |
+| Analytics | Yes | No | Yes | No (deliberately) |
+| Team collaboration | Yes | Yes | Yes | No (single user by design) |
+
+**Conclusion:** PostGenerator wins on strategic depth and Canva-workflow integration. It loses (deliberately) on scheduling, publishing, and analytics. This is correct positioning for a personal B2B content engine — not a generic social media management platform.
+
+---
+
+## Sources
+
+- PostNitro feature analysis: https://postnitro.ai/ (WebFetch, 2026-03-07)
+- aiCarousels feature analysis: https://www.aicarousels.com/ (WebFetch, 2026-03-07)
+- Canva Bulk Create documentation: https://www.canva.com/help/bulk-create/ (WebSearch, 2026-03-07)
+- Canva Bulk Create CSV workflow: https://dreamina.capcut.com/resource/canva-bulk-create (WebSearch, 2026-03-07)
+- B2B content marketing automation trends: https://reliqus.com/b2b-content-marketing-automation-strategy-2025/ (WebSearch, 2026-03-07)
+- Social media content automation pitfalls: https://metricool.com/biggest-social-media-mistakes/ (WebSearch, 2026-03-07)
+- AI content pitfalls 2025: https://www.wisedigitalpartners.com/learn/blog/strategy/ai-content-creation-2025-promise-pitfalls-path (WebSearch, 2026-03-07)
+- LLM prompt management features: https://mirascope.com/blog/prompt-management-system (WebSearch, 2026-03-07)
+- Editorial calendar B2B tools: https://storychief.io/blog/best-content-calendar-tools (WebSearch, 2026-03-07)
+- Instagram carousel B2B strategy: https://alliedinsight.com/resources/b2b-instagram-2025-algorithm-guide/ (WebSearch, 2026-03-07)
+- PostGenerator PROJECT.md: .planning/PROJECT.md (primary source for domain logic)
+
+---
+
+*Feature research for: Instagram carousel automation / B2B content generation (PostGenerator)*
+*Researched: 2026-03-07*