Michele/leopost
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete domain research

Browse Source 
Research dimensions:
- STACK.md: Technology stack recommendations (Next.js 15, Supabase, Vercel AI SDK, BullMQ)
- FEATURES.md: Feature landscape analysis (table stakes vs differentiators)
- ARCHITECTURE.md: System architecture design (headless, multi-tenant, job queue)
- PITFALLS.md: Common mistakes to avoid (rate limits, AI slop, cost control)
- SUMMARY.md: Synthesized findings with roadmap implications

Key findings:
- Stack: Next.js 15 + Supabase Cloud + Vercel AI SDK (multi-provider)
- Architecture: Modular monolith → microservices, headless pattern
- Critical pitfall: API rate limits (Meta reduced by 96%), AI cost explosion

Phase recommendations:
1. Core Scheduling Foundation (6-8 weeks)
2. Reliability & Differentiation (4-6 weeks)
3. Advanced Innovation (8-12 weeks)
4. Scale & Polish (ongoing)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Michele
2026-01-31 02:08:10 +01:00
parent a2f5dc2b97
commit dc3ea1cf58
5 changed files with 3228 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1080
.planning/research/ARCHITECTURE.md Normal file
View File

File diff suppressed because it is too large Load Diff

461
.planning/research/FEATURES.md Normal file
View File

@@ -0,0 +1,461 @@
# Feature Landscape: AI-Powered Social Media Management
**Domain:** AI-first social media management SaaS for freelancers
**Researched:** 2026-01-31
**Overall confidence:** HIGH
## Executive Summary
The social media management landscape in 2026 is experiencing a fundamental shift: AI features have moved from "nice to have" to "table stakes." However, there's a growing backlash against over-automation and AI-generated content that feels robotic. The winners in 2026 are tools that balance automation efficiency with authentic human touch.
Key insight: **78% of marketers automate over 25% of their tasks with AI by 2026**, but **only 26% of consumers prefer AI-generated content over human-created content** (down from 60% in 2023). The market demands AI that assists, not replaces, human creativity.
For a freelancer-focused tool like Leopost, this creates a clear opportunity: minimize effort without sacrificing authenticity.
---
## Table Stakes Features
Features users expect from any social media management tool. Missing these = product feels incomplete.
| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| **Multi-platform posting** | Every tool supports Facebook, Instagram, LinkedIn as baseline | **Medium** | Facebook/Instagram/LinkedIn are non-negotiable. TikTok increasingly expected but can be Phase 2. |
| **Post scheduling** | Core value proposition of category - posting at preset date/time | **Low** | Standard feature, well-documented APIs. |
| **Visual calendar view** | Industry standard UI pattern for seeing planned posts | **Medium** | Users expect drag-and-drop, monthly/weekly views. |
| **Basic analytics** | Users need to know if posts are working (likes, comments, shares) | **Medium** | Platform APIs provide this data. Focus on engagement metrics, not vanity metrics. |
| **AI caption generation** | 71% of marketers use AI for content in 2026 - no longer optional | **Low** | LLM API integration is straightforward. Quality depends on prompting. |
| **Image upload/library** | Users need to attach media to posts | **Low** | File storage + CDN. Consider size limits for free tier. |
| **Smart scheduling** | Suggest optimal posting times based on audience activity | **Medium** | Platforms provide "best time" data via analytics APIs. |
| **Multi-account management** | Freelancers manage multiple brands/clients | **Medium** | Account switching + access control. Essential for target market. |
| **Mobile responsiveness** | Freelancers work on-the-go | **Low** | Web app must work on mobile browsers. Native app = Phase 2+. |
| **Content recycling** | Evergreen content should be re-postable | **Medium** | Queue management + content categorization. SocialBee popularized this. |
### Notes on Table Stakes
**Why these are non-negotiable:**
- Multi-platform posting, scheduling, and calendar are the **definition of the category**. Without them, it's not a social media management tool.
- AI caption generation crossed from "differentiator" to "table stakes" in 2024-2025. In 2026, users expect AI assistance as baseline.
- Analytics are required because users need to justify their time investment. Focus on actionable metrics (engagement, best times) not vanity (follower count).
**Complexity assessment:**
- Most table stakes features are **Low-Medium complexity** because platform APIs are mature and patterns are well-established.
- The challenge is execution quality, not technical feasibility.
---
## Differentiators
Features that set Leopost apart from competitors. Not expected, but highly valued by target market (Italian freelancers).
| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| **Chat-first UI with AI assistant** | Leopost's core innovation - "talk to create posts" vs filling forms | **High** | Requires conversational AI, context management, natural language understanding. LOW confidence on execution difficulty - this is unproven territory. |
| **Multi-AI provider (GPT/Claude/Gemini)** | Leverage strengths of each model + avoid vendor lock-in | **Medium** | API integration is straightforward, but UI/UX for model selection needs careful design. Cost management across providers. |
| **Brand voice memory** | AI learns user's authentic voice - combats "AI slop" problem | **High** | Requires training/fine-tuning on user content, persistent context, and quality evaluation. Critical for authenticity. |
| **Configurable automation levels** | User chooses: Preview every post → Auto-publish with approval → Full autopilot | **Medium** | Workflow engine with 3 modes. Addresses over-automation concern while allowing efficiency. |
| **WhatsApp/Telegram integration** | Post creation via messaging apps freelancers already use | **High** | Bot development, message parsing, authentication. HIGH value for Italian market where WhatsApp is dominant. |
| **Progressive onboarding** | Gradual feature introduction - avoid overwhelming new users | **Medium** | UX design challenge more than technical. 74% of users abandon if onboarding is difficult. |
| **Italian-first design** | UI, prompts, support in Italian - not just translation | **Low** | Localization + culturally appropriate examples. Underserved market = opportunity. |
| **AI image generation** | Create graphics without leaving the tool (DALL-E/Midjourney) | **Medium** | API integration + cost management. Users expect this for "complete" AI solution. |
| **Platform-specific optimization** | AI adapts content for each platform's culture (LinkedIn formal, Instagram casual) | **High** | Requires sophisticated prompting + platform knowledge. Key to avoiding "copy-paste" feel. |
| **Approval workflow (optional)** | For freelancers with clients: draft → review → approve → publish | **Medium** | State machine + notification system. Planable and SocialPilot have proven this pattern. |
### Differentiator Strategy
**Why these matter for Leopost:**
1. **Chat-first UI** is the headline innovation. Competitors use forms and dashboards. Leopost uses conversation. This addresses the "effort minimization" promise directly.
2. **Multi-AI provider** hedges risk and leverages best-of-breed:
- ChatGPT for creative, engaging captions
- Claude for longer, thoughtful content and context understanding
- Gemini for Google ecosystem integration and enterprise features
- Market research shows users value choice and flexibility
3. **Brand voice memory** solves the #1 complaint about AI content in 2026: it sounds generic. Research shows "negative reactions are attenuated if AI assists rather than replaces humans." This feature makes AI a co-pilot, not a ghostwriter.
4. **Configurable automation** addresses the over-automation backlash. Users in 2026 are skeptical of "set-it-and-forget-it." Give control: some users want autopilot, others want approval. Both are valid.
5. **WhatsApp/Telegram integration** is **HIGH value for Italian market specifically**. Research shows 68% of companies using messaging channels saw improved satisfaction. Italy has extremely high WhatsApp adoption. This is a localization advantage.
6. **Progressive onboarding** prevents churn. 25% better retention with good onboarding. Freelancers are busy - respect their time.
### Complexity & Risk Assessment
**High complexity features:**
- Chat-first UI: **HIGHEST RISK** - unproven UX pattern in this space. Could be brilliant or confusing. Needs extensive user testing.
- Brand voice memory: Technically challenging. Requires ML/context management beyond basic LLM calls.
- Platform-specific optimization: Complex prompting + quality control.
**Medium complexity features:**
- Most are **proven patterns** (multi-AI, approval workflows, image generation) with clear API paths.
**Recommendation:** Implement table stakes + 2-3 differentiators for MVP. Save highest-risk features (chat-first UI) for prototype validation first.
---
## Anti-Features
Features to explicitly NOT build. Common in the space, but wrong for Leopost's positioning.
| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| **Enterprise collaboration** | Team features (20+ users, SSO, audit logs) add complexity for marginal benefit | Focus on solo freelancers + small teams (2-5 users). Defer enterprise until proven product-market fit. |
| **Social listening/monitoring** | Tracking brand mentions across the web is a different product category | Stick to content creation + publishing. Listening is "nice to have" but not core value prop. |
| **Native mobile apps** | Expensive to build/maintain, web-first is sufficient for MVP | Responsive web app works on mobile. Native apps = Phase 3+ if data shows need. |
| **Influencer marketplace** | Not relevant to freelancer market, adds moderation burden | Leopost is a tool, not a platform. Stay focused. |
| **Advanced video editing** | Scope creep - video tools are a separate category | Allow video upload, but editing happens externally (Canva, CapCut, etc). Integration > duplication. |
| **Paid ads management** | Different workflow, different APIs, different user intent | Organic social only. Ads are a separate product vertical. |
| **White-label/reseller program** | Premature for early-stage product | Build for end users first. Reseller channel = future opportunity after PMF. |
| **Blockchain/NFT features** | Hype-driven, no clear user value in 2026 | Avoid trend-chasing. Focus on proven workflows. |
| **Gamification (badges, streaks, etc)** | Adds complexity, risk of feeling gimmicky | Freelancers want efficiency, not games. Keep UX professional. |
| **Over-automation (100% autopilot from day 1)** | Research shows this erodes trust and authenticity | Start with human-in-the-loop. Autopilot is earned trust, not default mode. |
### Why These Are Anti-Features
**The trap:** Social media management platforms suffer from feature bloat. Tools like Hootsuite and Sprout Social have 200+ features that overwhelm users.
**The principle:** Leopost wins by doing LESS, but doing it BETTER. Focus ruthlessly on the core loop:
1. Freelancer describes what they want to post (chat)
2. AI generates on-brand content
3. Schedule/publish with minimal friction
**Examples of bloat to avoid:**
- Hootsuite's Advanced plan: $399/month with 350-post bulk scheduling, team workflows, listening. **WAY too complex for a freelancer.**
- Sprout Social: Starts at $249/user/month. **Overpriced and over-featured for solo users.**
- Buffer's free plan: Only 3 social channels. **Leopost should be more generous to win market.**
**The opportunity:** Competitors are enterprise-focused. Leopost serves the underserved freelancer/solopreneur market with simplicity + AI-first UX.
---
## Feature Dependencies
Critical sequencing for roadmap planning.
```
Core Foundation (Phase 1):
├─ User authentication
├─ Social platform OAuth (Facebook, Instagram, LinkedIn)
├─ Basic post composer
└─ Post scheduling engine
│
└──> Multi-platform posting (Phase 1)
│
├──> Visual calendar (Phase 1)
│ └──> Drag-and-drop rescheduling (Phase 2)
│
├──> AI caption generation (Phase 1)
│ ├──> Brand voice memory (Phase 2)
│ └──> Platform-specific optimization (Phase 2)
│
├──> Smart scheduling (Phase 2)
│ └──> Analytics/best time detection (Phase 2)
│
└──> Approval workflow (Phase 2)
└──> Multi-user accounts (Phase 3)
Advanced Features (Phase 3+):
├─ Chat-first UI (requires solid API foundation first)
├─ Multi-AI provider switching (after single provider proven)
├─ WhatsApp/Telegram bots (complex, defer until core stable)
└─ AI image generation (nice-to-have, not critical path)
```
### Dependency Notes
**Critical path:**
1. Must have working OAuth before posting
2. Must have basic posting before scheduling
3. Must have scheduling before calendar visualization
4. Must have single AI provider before multi-provider
**Parallel tracks:**
- Analytics can develop independently of posting
- Image generation can be added anytime (nice-to-have)
- WhatsApp/Telegram integration is isolated (separate codebase)
**Risk areas:**
- Chat-first UI requires mature API foundation - don't start with this
- Brand voice memory needs data (user posts) before it can work - Phase 2+ feature
---
## MVP Feature Set Recommendation
For a successful MVP targeting Italian freelancers, prioritize these features:
### Core MVP (Phase 1 - Must Have)
| Feature | Rationale |
|---------|-----------|
| Facebook, Instagram, LinkedIn posting | Table stakes - minimum viable platform coverage |
| Post scheduling (date/time picker) | Core value proposition - "plan ahead" |
| Visual calendar (month view) | Industry standard - users expect this |
| AI caption generation (single provider - start with Claude) | Differentiator - AI-first positioning |
| Image upload + preview | Necessary for complete posts |
| Basic analytics (last 30 days) | Users need feedback on performance |
| Italian UI and prompts | Differentiator for target market |
**Why this MVP:**
- Delivers on core promise: "AI helps you create and schedule posts"
- Covers 3 major platforms (LinkedIn, Facebook, Instagram are most used by Italian freelancers)
- Single AI provider (Claude) reduces complexity while delivering quality
- No over-automation - user approves everything in MVP
- Italian-first = competitive advantage in underserved market
**What's NOT in MVP:**
- Multi-AI provider (Phase 2)
- Chat-first UI (Phase 3 - needs validation first)
- WhatsApp/Telegram (Phase 3)
- Smart scheduling (Phase 2)
- Brand voice memory (Phase 2 - needs training data)
- TikTok, Twitter/X (Phase 2)
### Phase 2 (Differentiation)
Add after MVP validation:
- **Smart scheduling** (AI suggests best times)
- **Brand voice memory** (learn from user's approved posts)
- **Platform-specific optimization** (adapt tone per network)
- **Content recycling** (evergreen post queue)
- **TikTok support** (if user research shows demand)
- **Multi-user accounts** (for freelancers with VAs/assistants)
- **Approval workflow** (for freelancers with clients)
### Phase 3 (Advanced)
Add after product-market fit proven:
- **Chat-first UI** (risky innovation - validate first)
- **Multi-AI provider** (GPT + Gemini in addition to Claude)
- **WhatsApp/Telegram bots** (post via messaging)
- **AI image generation** (DALL-E/Midjourney integration)
- **Advanced analytics** (competitor benchmarking, sentiment)
---
## Feature Complexity Matrix
Prioritization guide for roadmap planning.
| Feature | Value | Complexity | Priority |
|---------|-------|------------|----------|
| Multi-platform posting | HIGH | Medium | **P0 - MVP** |
| Post scheduling | HIGH | Low | **P0 - MVP** |
| Visual calendar | HIGH | Medium | **P0 - MVP** |
| AI caption generation | HIGH | Low | **P0 - MVP** |
| Image upload | HIGH | Low | **P0 - MVP** |
| Basic analytics | MEDIUM | Medium | **P0 - MVP** |
| Italian localization | HIGH | Low | **P0 - MVP** |
| Smart scheduling | MEDIUM | Medium | **P1 - Phase 2** |
| Brand voice memory | HIGH | High | **P1 - Phase 2** |
| Platform optimization | HIGH | High | **P1 - Phase 2** |
| Content recycling | MEDIUM | Medium | **P1 - Phase 2** |
| Approval workflow | MEDIUM | Medium | **P1 - Phase 2** |
| Multi-user accounts | LOW | Medium | **P2 - Phase 3** |
| Chat-first UI | HIGH | High | **P2 - Phase 3** (validate UX first) |
| Multi-AI provider | MEDIUM | Medium | **P2 - Phase 3** |
| WhatsApp/Telegram | MEDIUM | High | **P2 - Phase 3** |
| AI image generation | LOW | Medium | **P3 - Future** |
| Social listening | LOW | High | **P4 - Avoid** |
| Video editing | LOW | High | **P4 - Avoid** |
| Paid ads | LOW | High | **P4 - Avoid** |
**Priority key:**
- **P0 = MVP** - Ship first version
- **P1 = Phase 2** - Add after validation
- **P2 = Phase 3** - Add after PMF
- **P3 = Future** - Backlog
- **P4 = Avoid** - Anti-features
---
## Competitive Feature Benchmark
How Leopost differentiates vs. established players.
| Feature | Hootsuite | Buffer | SproutSocial | SocialBee | **Leopost** |
|---------|-----------|--------|--------------|-----------|-------------|
| **Price (entry tier)** | $99/mo | $6/mo | $249/mo | $29/mo | **$19/mo (target)** |
| **AI caption generation** | ✅ (OwlyWriter) | ✅ (AI Assist) | ✅ | ✅ | ✅ |
| **Multi-AI provider** | ❌ | ❌ | ❌ | ❌ | **✅ (GPT/Claude/Gemini)** |
| **Chat-first UI** | ❌ | ❌ | ❌ | ❌ | **✅ (unique)** |
| **Brand voice memory** | ✅ (basic) | ❌ | ✅ (advanced) | ❌ | **✅ (trained on user posts)** |
| **WhatsApp/Telegram** | ❌ | ❌ | ❌ | ❌ | **✅ (Phase 3)** |
| **Italian-first** | ❌ (translated) | ❌ | ❌ | ❌ | **✅ (native)** |
| **Smart scheduling** | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Content recycling** | ✅ | ❌ | ❌ | ✅ (signature feature) | ✅ |
| **Approval workflow** | ✅ (enterprise) | ✅ | ✅ | ❌ | ✅ (simple) |
| **Social listening** | ✅ | ❌ | ✅ | ❌ | **❌ (anti-feature)** |
| **Team collaboration** | ✅ (complex) | ✅ | ✅ (complex) | ✅ | **Simple (2-5 users max)** |
| **Target market** | Enterprise | SMB | Enterprise | SMB | **Freelancers** |
### Key Differentiators
**Where Leopost wins:**
1. **Multi-AI provider** - Unique in market. Hedges AI risk, leverages best models.
2. **Chat-first UI** - No competitor does this. High risk, high reward.
3. **Italian-first** - Native design, not translation. Underserved market.
4. **WhatsApp/Telegram** - Matches how Italian freelancers already communicate.
5. **Price-to-value** - More AI features than Buffer, less complexity than Hootsuite, better price than both.
**Where competitors win:**
- Hootsuite/Sprout: Enterprise features, social listening, deep analytics
- Buffer: Simplicity, clean UX, generous free tier
- SocialBee: Content categorization, recycling (but no AI multi-provider)
**Leopost positioning:** "The AI-first social media tool for Italian freelancers who want maximum output with minimum effort."
---
## Sources
Research sources with confidence levels:
### HIGH Confidence Sources (Authoritative/Recent)
- [15 Best AI Tools for Social Media Marketing in 2026](https://www.digitalfirst.ai/blog/best-ai-tools-for-social-media-marketing)
- [19 Best Social Media AI Tools For Your Brand in 2026 | Sprout Social](https://sproutsocial.com/insights/social-media-ai-tools/)
- [10 Best Social Media Automation Tools for 2026](https://www.eclincher.com/articles/10-best-social-media-automation-tools-for-2026)
- [21 Best Social Media Scheduling Tools in 2026 | Sprout Social](https://sproutsocial.com/insights/social-media-scheduling-tools/)
- [13 Best Social Media Scheduling Tools (2026 Pros And Cons)](https://adamconnell.me/social-media-scheduler-tools/)
- [The Complete Guide to Choosing AI Platforms in 2026: ChatGPT, Claude, Gemini Compared](https://www.firstaimovers.com/p/complete-eight-ai-platform-comparison-guide-2025)
- [Claude vs ChatGPT vs Gemini: Best AI Comparison 2026 | Improvado](https://improvado.io/blog/claude-vs-chatgpt-vs-gemini-vs-deepseek)
### MEDIUM Confidence Sources (Industry Analysis)
- [After an oversaturation of AI-generated content, creators' authenticity is in high demand - Digiday](https://digiday.com/media/after-an-oversaturation-of-ai-generated-content-creators-authenticity-and-messiness-are-in-high-demand/)
- [The Impact of AI on Social Media Content Creation: Balancing Automation and Authenticity](https://www.feedhive.com/blog/the-impact-of-ai-on-social-media-content-creation-balancing-automation-and-authenticity)
- [7 Social Media Automation Mistakes & How to Fix Them](https://obbserv.com/marketing-automation/blog/common-social-media-automation-mistakes/)
- [AI Content Generation in 2026: Brand Voice, Strategy and Scaling](https://www.roboticmarketer.com/ai-content-generation-in-2026-brand-voice-strategy-and-scaling/)
- [Communication and Social Media Trends in 2026: A Complete Guide](https://amalialopezacera.com/en/communication-and-social-media-trends-in-2026-a-complete-guide/)
- [Social Media Management Workflow: Your 2026 Template | Metricool](https://metricool.com/social-media-workflow/)
### Tool-Specific Documentation
- [Hootsuite AI Features](https://www.hootsuite.com/platform/owly-writer-ai)
- [Buffer Features](https://sproutsocial.com/insights/social-media-scheduling-tools/)
- [Lately AI Chat-Based Management](https://www.lately.ai/)
- [The 8 best AI image generators in 2026 | Zapier](https://zapier.com/blog/best-ai-image-generator/)
- [DALL·E vs Midjourney (2026) Comparison](https://www.demandsage.com/dall-e-vs-midjourney/)
### Market Research
- [21 social media metrics you must track for success in 2026](https://blog.hootsuite.com/social-media-metrics/)
- [Social Media Analytics in 2026: A Step-by-Step Guide](https://100poundsocial.com/blog/social-media-marketing/social-media-analytics-step-by-step-guide/)
- [2026 Social Media Trends Every Brand Should Know](https://heyprospekt.com/insights/2026-social-media-trends/)
---
## Confidence Assessment
| Area | Confidence | Reasoning |
|------|------------|-----------|
| **Table stakes features** | **HIGH** | Well-documented industry standards. Multiple sources confirm (Sprout Social, Hootsuite, Buffer all have similar core features). |
| **AI feature trends** | **HIGH** | Strong consensus across sources: AI is table stakes in 2026, but authenticity concerns are real. 78% automation stat verified across multiple sources. |
| **Differentiator viability** | **MEDIUM** | Multi-AI provider and brand voice memory are proven concepts (Jasper, Claude-based tools). Chat-first UI is **LOW confidence** - no competitor does this, UX risk. |
| **Anti-features** | **HIGH** | Clear from market research: enterprise features, video editing, paid ads are separate product categories. Avoiding bloat is validated strategy (Buffer succeeded with simplicity). |
| **Complexity estimates** | **MEDIUM** | Based on API documentation and platform capabilities. OAuth, scheduling, AI integration are well-understood. Chat-first UI and brand voice are higher risk. |
| **Italian market specifics** | **MEDIUM** | WhatsApp dominance in Italy is documented, but localization value is harder to quantify. Assumption: underserved market = opportunity. Needs validation. |
---
## Open Questions for Validation
Areas where research was inconclusive or assumptions need testing:
1. **Chat-first UI acceptance:** Will users embrace conversational interface for social media posting, or do they prefer traditional form-based UI? **Needs prototype + user testing.**
2. **Multi-AI provider value:** Will users actually switch between GPT/Claude/Gemini, or will they pick one and stick? **Needs analytics on user behavior after launch.**
3. **WhatsApp/Telegram priority:** Is this a "must have" for Italian market, or a "nice to have"? **Needs user interviews with Italian freelancers.**
4. **Price sensitivity:** What's the optimal price point for Italian freelancers? $19/mo is hypothesis. **Needs market testing.**
5. **TikTok demand:** Do freelancers managing LinkedIn/Facebook/Instagram also need TikTok? Generational divide possible. **Needs survey data.**
6. **Brand voice training data:** How many user-approved posts are needed before brand voice memory becomes accurate? 10? 50? 100? **Needs ML experimentation.**
7. **Automation level preference:** What % of users want autopilot vs. approval? **Needs behavioral data post-launch.**
---
## Recommendations for Roadmap
Based on feature research, suggested phase structure:
### Phase 1: Core MVP (Table Stakes)
**Goal:** Prove core value proposition - "AI makes social posting effortless"
**Features:**
- Multi-platform posting (Facebook, Instagram, LinkedIn)
- Post scheduling with visual calendar
- AI caption generation (Claude only for MVP)
- Image upload and preview
- Basic analytics (engagement metrics)
- Italian UI and prompts
**Why this order:**
- Delivers minimum viable experience
- Proves AI value without over-complicating
- Can launch and validate market demand
**Duration estimate:** 6-8 weeks for solo developer (based on standard SaaS timelines)
### Phase 2: Differentiation
**Goal:** Add features that separate Leopost from Buffer/Hootsuite
**Features:**
- Brand voice memory (learn from approved posts)
- Smart scheduling (AI best time suggestions)
- Platform-specific optimization (adapt tone per network)
- Content recycling (evergreen queue)
- Approval workflow (draft → review → publish)
- Multi-user support (2-5 users)
**Why this order:**
- Brand voice needs data from Phase 1 user activity
- Differentiation features require stable foundation
- Can iterate based on user feedback
**Duration estimate:** 4-6 weeks (features build on MVP infrastructure)
### Phase 3: Advanced Innovation
**Goal:** Unique features no competitor has
**Features:**
- Multi-AI provider (add GPT + Gemini to Claude)
- Chat-first UI (conversational post creation)
- WhatsApp/Telegram bots
- AI image generation
**Why defer:**
- Chat-first UI is HIGH RISK - needs extensive UX validation
- Multi-AI adds cost complexity
- WhatsApp/Telegram are separate codebases (bots)
- Can validate demand for these features during Phase 1+2
**Duration estimate:** 8-12 weeks (higher complexity, experimental features)
### Anti-Pattern: What NOT to do
❌ **Don't start with chat-first UI** - It's the headline feature, but also the riskiest. Build solid API foundation first.
❌ **Don't build all platforms at once** - Start with 3 (Facebook, Instagram, LinkedIn), add more based on demand.
❌ **Don't add enterprise features early** - Team collaboration, SSO, audit logs are scope creep for freelancer market.
❌ **Don't over-automate in MVP** - Start with user approval for every post. Autopilot is Phase 2 after trust is built.
### Success Criteria
**Phase 1 success:** 100 active users posting 500+ scheduled posts/week
**Phase 2 success:** 50% of users enable brand voice memory, average 3 platforms connected
**Phase 3 success:** Chat-first UI has 70%+ satisfaction, WhatsApp/Telegram handle 20% of post creation
---
**END OF FEATURES.MD**

585
.planning/research/PITFALLS.md Normal file
View File

@@ -0,0 +1,585 @@
# Domain Pitfalls
**Domain:** AI-powered social media management SaaS per freelance italiani
**Researched:** 2026-01-31
**Confidence:** MEDIUM-HIGH (WebSearch verified with multiple credible sources)
## Critical Pitfalls
Errori che causano riscritture, perdita di utenti o fallimento del prodotto.
---
### Pitfall 1: API Rate Limits e Gestione Token Social Media
**Cosa va storto:**
Le API di Meta (Facebook/Instagram) hanno limiti drasticamente ridotti nel 2024: da 5,000 a **200 DM/ora** (riduzione del 96%). Ogni chiamata API fallita, invalida o riuscita consuma ugualmente il rate limit. I progetti che non gestiscono correttamente questi limiti si bloccano o vengono bannati.
**Perché succede:**
- Sviluppatori non implementano exponential backoff dopo errore 429
- Non differenziano tra errori (retry immediato invece che attendere)
- Token Instagram scadono (short-lived dopo 1h, long-lived dopo 60 giorni inattivi)
- Tool terzi (analytics, monitoring) consumano quota API senza che il team se ne accorga
- Errori di cache: ogni chiamata duplicata spreca quota
**Conseguenze:**
- Scheduling fallisce silenziosamente
- Utenti vedono "post non pubblicato" senza spiegazioni
- Ban temporaneo dell'account business
- Perdita di fiducia immediata
**Prevenzione:**
```javascript
// Implementare sin dal Milestone 1
1. Exponential backoff con jitter (1s → 2s → 4s → 8s + random 0-1000ms)
2. Token refresh automatico ogni 50-55 giorni
3. Caching aggressivo (riduce 70% chiamate API)
4. Field selection (riduce 20% volume)
5. Batching requests (riduce 30% volume)
6. Rate limit monitoring dashboard visibile in real-time
```
**Rilevamento:**
- Monitor `X-Business-Use-Case-Usage` header in ogni response
- Log tutti gli errori 429 e 190 (token scaduto)
- Alert quando uso > 80% del rate limit orario
- Dashboard che mostra quota rimanente per account
**Fase da affrontare:**
- **Fase 1 (Core scheduling)**: Implementare exponential backoff + token refresh
- **Fase 2 (Multi-account)**: Dashboard rate limit per account
- **Ogni fase**: Test con rate limit simulati (mock API)
**Fonti:**
- [Instagram Graph API Rate Limits](https://elfsight.com/blog/instagram-graph-api-complete-developer-guide-for-2025/) - 200 DM/hour
- [Handling API Rate Limits](https://www.marketingseo.in/post/handling-posting-failures-api-rate-limits-gracefully-a-complete-developer-s-guide-to-facebook-and) - Exponential backoff con jitter
- [Instagram API Troubleshooting](https://www.getphyllo.com/post/navigating-instagram-api-rate-limit-errors-a-comprehensive-guide) - Common mistakes
---
### Pitfall 2: "AI Slop" - Contenuti Generici che Uccidono il Brand
**Cosa va storto:**
L'AI genera contenuti tecnicamente corretti ma **generici, impersonali e identici** a quelli di migliaia di altri utenti. Il 71% delle immagini social è ora AI-generated, ma solo il 26% degli utenti preferisce contenuti AI vs umani (era 60% nel 2023). Le persone riconoscono e ignorano il "template AI".
**Perché succede:**
- Prompt generici ("scrivi post LinkedIn su X") → output generico
- Nessun "brand voice training" → AI usa tono corporate standard
- Zero contestualizzazione → AI non sa nulla del business dell'utente
- Nessuna review umana → publish automatico di mediocrità
- Focus su "velocità" invece che "qualità + velocità"
**Conseguenze:**
- Engagement crollato (audience riconosce AI slop e scorre oltre)
- Perdita di autenticità del brand
- Recensioni negative "sembra tutto uguale"
- Churn utenti dopo 1-2 mesi ("perdo tempo a rivedere tutto")
- Trust degli utenti in calo: 78% trova difficile distinguere AI da umano, ma il 41% non si fida
**Prevenzione:**
```
1. Brand Voice Onboarding obbligatorio (Fase 1)
- Esempi di post precedenti dell'utente
- Tone (formale/casual, serio/ironico, tecnico/semplice)
- Parole chiave del settore, gergo
- "Things I never say" (anti-patterns)
2. Multi-stage quality control (Fase 2)
- Pre-screening automatico (keywords ban, lunghezza)
- Contextual analysis (allineamento brand voice)
- Human-in-the-loop sempre (edit prima di schedule)
- Performance monitoring post-publish
3. AI Training incrementale (Fase 3+)
- Learning da post approvati/editati dall'utente
- Feedback loop: utente vota 👍/👎 ogni draft
- Fine-tuning model o RAG con "esempi approvati"
4. "Anti-AI Aesthetic" features
- Opzione "imperfetto ma autentico"
- Variazioni multiple invece di singolo output
- Suggerimenti per personalizzazione manuale
```
**Rilevamento:**
- A/B test engagement: AI vs AI-edited vs 100% human
- NPS survey: "Il contenuto rispecchia la tua voce?"
- Monitoring tempo di editing: se utente riscrive >60% → AI fallisce
- Analisi similarity: se draft troppo simili tra utenti → problema sistemico
**Fase da affrontare:**
- **Fase 1**: Brand voice onboarding (form + esempi)
- **Fase 2**: Human review obbligatorio, feedback loop
- **Fase 3**: Fine-tuning basato su approvazioni utente
- **Ogni milestone**: A/B test qualità vs velocità
**Fonti:**
- [AI Content Authenticity Crisis 2026](https://digiday.com/media/after-an-oversaturation-of-ai-generated-content-creators-authenticity-and-messiness-are-in-high-demand/) - 26% consumer preference (down from 60%)
- [AI Slop Statistics](https://www.usnews.com/news/best-states/california/articles/2026-01-29/one-tech-tip-fed-up-with-ai-slop-a-few-platforms-will-let-you-dial-it-down) - 71% images AI-generated
- [AI Content Quality Control](https://koanthic.com/en/ai-content-quality-control-complete-guide-for-2026-2/) - Multi-stage pipelines
- [Brand Voice Consistency](https://www.growth-rocket.com/blog/how-to-maintain-brand-voice-with-ai-workflows/) - Human-AI collaboration
---
### Pitfall 3: Costi AI Fuori Controllo (Multi-Provider Hell)
**Cosa va storto:**
I costi AI esplodono senza visibilità. Progetti partono con "GPT-4 per tutto", poi scoprono che:
- Generare 1 post con immagine AI costa $0.15-0.50 (testo + DALL-E/Midjourney)
- 100 utenti freemium × 10 draft/mese × $0.30 = **$300/mese LOSS**
- Nessun monitoring → scopri il buco a fine mese
- Vendor lock-in → impossibile cambiare provider senza riscrivere codice
- 84% delle enterprise vedono erosione margini per costi AI, 25% sforano forecast
**Perché succede:**
- Usano modelli costosi (GPT-4) per task semplici (captions, hashtag)
- Nessuna orchestrazione multi-provider (se OpenAI sale prezzi, sei bloccato)
- Nessun caching di risultati (rigenera stesso contenuto 10 volte)
- Freemium troppo generoso (utenti gratis consumano risorse senza limiti)
- Zero monitoring per utente/feature
**Conseguenze:**
- Burn rate insostenibile
- Freemium model fallisce (CAC > LTV)
- Impossibile scalare senza aumentare prezzi
- Margini negativi su ogni utente
**Prevenzione:**
```
1. AI Gateway con routing intelligente (Fase 1)
- Task semplici → GPT-4 Mini / Claude Haiku (5-10x cheaper)
- Generazione creativa → GPT-4 / Claude Sonnet
- Immagini → comparazione prezzi DALL-E vs Midjourney vs Stable Diffusion
- Failover automatico se provider down
2. Cost Attribution granulare (Fase 2)
- Tracking costo per utente, per feature, per request
- Dashboard real-time: "Oggi spesi $X, budget $Y"
- Alert se utente singolo supera soglia (abuse detection)
3. Caching aggressivo (Fase 1)
- Hash prompt + parametri → se già generato, riusa
- Cache immagini: stessi parametri → stessa immagine
- TTL intelligente (cache "best performing posts" per sempre)
4. Freemium limits tecnici (Fase 1)
- Max 5 AI drafts/mese (poi upgrade)
- Immagini AI solo su piano paid
- Rate limiting per utente
5. Monitoring e FinOps (Fase 2+)
- Budget alerts settimanali
- Cost breakdown per provider
- Optimization suggestions automatiche
```
**Rilevamento:**
- Dashboard costi giornaliera
- Alert se costo/utente > $X
- Report mensile: costo per feature
- Benchmark: costo medio competitor (ricerca continua)
**Fase da affrontare:**
- **Fase 1**: AI Gateway, caching, freemium limits
- **Fase 2**: Cost attribution, monitoring dashboard
- **Fase 3**: Dynamic routing (auto-switch provider più economico)
**Fonti:**
- [AI Infrastructure Cost Optimization](https://www.deloitte.com/us/en/insights/topics/technology-management/tech-trends/2026/ai-infrastructure-compute-strategy.html) - 84% margin erosion
- [Multi-Provider Orchestration](https://www.msrcosmos.com/blog/scaling-multi-agent-ai-systems-for-cloud-cost-optimization-in-2026/) - Vendor lock-in prevention
- [AI API Pricing Guide](https://anyapi.ai/blog/ai-api-pricing-guide-2026-cost-comparison-and-how-to-optimize-your-spending) - Cost comparison
- [Image Generation Costs](https://www.imagine.art/blogs/ai-image-generation-cost) - Pricing models
---
### Pitfall 4: Scheduling Reliability Failures (Silent Post Loss)
**Cosa va storto:**
Post programmati non vengono pubblicati. L'utente scopre **dopo giorni** che la campagna è fallita. Cause comuni: token scaduti, API changes, server down, timezone bugs, draft corrotti. "Disappearing drafts, truncated captions, silent upload failures trigger real-world chaos."
**Perché succede:**
- Nessun sistema di retry automatico
- Nessuna notifica di failure (utente non sa che è fallito)
- Timezone handling sbagliato (pubblica alle 3am invece che 3pm)
- Draft salvati localmente ma mai sincronizzati con backend
- API Meta cambia endpoint → codice vecchio continua a chiamare deprecated API
**Conseguenze:**
- Timing critico perso (Black Friday post mai pubblicato)
- Perdita fiducia cliente ("unbillable time spent fixing")
- Churn immediato se succede 2+ volte
- Recensioni negative "unreliable, non ci puoi contare"
**Prevenzione:**
```
1. Scheduling Architecture resiliente (Fase 1)
- Distributed job queue (Bull/BullMQ su Redis)
- Retry automatico con exponential backoff (3 tentativi)
- Dead Letter Queue per failures definitivi
- Idempotency: stesso post non pubblicato 2 volte se retry
2. Failure Notifications immediate (Fase 1)
- Email + Push notification se post fallisce
- Dashboard "scheduled posts status" real-time
- Alert se >10% post falliscono in 1h (incident detection)
3. Timezone Validation rigorosa (Fase 1)
- Salva sempre UTC + user timezone separati
- Preview "will publish at [local time]" prima di confermare
- Test automatici per ogni timezone italiano
4. Health Checks pre-publish (Fase 2)
- 5 minuti prima: verifica token valido
- 1 minuto prima: test API connection
- Se fail → notifica utente + auto-reschedule +15min
5. API Version Monitoring (Continuo)
- Subscribe a Meta developer changelog
- Automated tests che falliscono se API changes
- Graceful degradation (se nuova API fail, usa vecchia)
```
**Rilevamento:**
- Monitor tasso successo publish (target: >99.5%)
- Alert se singolo utente ha 2+ failures in 1 settimana
- Post-mortem automatico per ogni failure (log + context)
**Fase da affrontare:**
- **Fase 1 (Core)**: Job queue, retry, notifications, timezone validation
- **Fase 2**: Health checks pre-publish
- **Ogni fase**: Chaos engineering (kill server durante scheduled publish, verifica recovery)
**Fonti:**
- [Platform Reliability](https://www.sendible.com/insights/platform-reliability-why-your-social-media-scheduler-must-be-reliable) - Silent failures impact
- [Scheduling Failures](https://www.bitbrowser.net/blog/instagram-scheduled-posts-not-working) - Common causes
- [Social Media Scheduling Mistakes](https://www.lyricalhost.com/blog/common-mistakes-to-avoid-when-scheduling-social-media/) - Best practices
---
### Pitfall 5: Onboarding Overwhelm (Firehose Problem)
**Cosa va storto:**
Nuovi utenti vengono bombardati con "tutto in una volta": tour di 20 features, form infiniti, dashboard complessa. Il 63% degli utenti abbandona durante onboarding complesso. "Throwing every single feature at a new user at once causes instant confusion."
**Perché succede:**
- Developer mindset: "mostriamo tutto così sanno cosa può fare"
- Nessuna progressive disclosure (tutto visibile subito)
- One-size-fits-all (stesso onboarding per principiante e power user)
- Nessun time-to-value chiaro ("cosa ottengo nei primi 5 minuti?")
- Form lunghi prima del primo valore
**Conseguenze:**
- Activation rate <30% (benchmark buono: >60%)
- Utenti si registrano ma non completano setup
- "Trough of disillusionment" → churn prima del primo post pubblicato
- Support sommerso da "non capisco come funziona"
**Prevenzione:**
```
1. Progressive Disclosure (Fase 1)
- Step 1: Genera 1 post AI in <2 minuti (quick win)
- Step 2: Connetti 1 account social (solo dopo primo successo)
- Step 3: Schedule post (introducono scheduling dopo capire generazione)
- Features avanzate: nascoste, sbloccate quando utente ready
2. Role-Aware Onboarding (Fase 2)
- Quiz iniziale: "Sei freelance? Agenzia? Brand?"
- Path differenziati: freelance vede solo essenziale
- Enterprise vede team collaboration features
3. Time-to-Value <5 minuti (Fase 1)
- Template pre-compilati (click → post ready)
- "Skip" opzionale per ogni step non critico
- Salva draft automaticamente (utente può tornare dopo)
4. Contextual Onboarding (Fase 2+)
- Tooltips quando utente hovera feature (non tour forzato)
- "You haven't tried X yet" gentle nudge (non popup invasivo)
- Video micro-clips (10-15s) triggered by behavior
5. Checklist Opzionale (Fase 1)
- "Setup your profile" visibile ma non bloccante
- Progress bar motiva completamento
- Rewards per milestone (unlock feature, badge)
```
**Rilevamento:**
- Funnel analytics: % che completa ogni step
- Time-to-first-post metric (target: <10 minuti)
- Heatmap: dove utenti bloccano/abbandonano
- Survey exit: "Why are you leaving?"
**Fase da affrontare:**
- **Fase 1**: Progressive disclosure, time-to-value <5min
- **Fase 2**: Role-aware paths, contextual guidance
- **Ogni milestone**: Onboarding usability test con 5+ freelance reali
**Fonti:**
- [Progressive Onboarding](https://www.eleken.co/blog-posts/user-onboarding-best-practices) - Progressive disclosure approach
- [Onboarding Mistakes SaaS](https://princepaluiux.com/blog/onboarding-mistakes-saas-companies/) - Firehose problem
- [SaaS Onboarding 2026 Trends](https://userguiding.com/blog/state-of-plg-in-saas) - Role-aware flows
- [B2B SaaS UX Challenges](https://www.onething.design/post/b2b-saas-ux-design) - Time-to-value metrics
---
## Moderate Pitfalls
Errori che causano ritardi, debito tecnico o esperienza utente degradata.
---
### Pitfall 6: Freemium Tier Miscalibration
**Cosa va storto:**
Il tier gratuito è troppo generoso (utenti non upgradano mai) o troppo restrittivo (utenti abbandonano prima di vedere valore). Conversion rate freemium media: 2-5%. Se <2% → tier troppo generoso. Se utenti churneranno prima di 30 giorni → troppo restrittivo.
**Perché succede:**
- Paura di perdere utenti → danno troppo gratis
- Opposto: vogliono forzare upgrade → danno troppo poco
- Non testano conversion rate prima di scala
- Ignorano cost per free user (support, infra, AI calls)
**Prevenzione:**
- A/B test tier generosità (Fase 2)
- Limit strategici: 5 AI drafts/mese (tease value), poi upgrade
- No immagini AI in free (costo alto)
- Monitoring: se utente attivo >6 mesi senza upgrade → tier troppo generoso
- Support prioritario solo su paid (riduce costi support free users)
**Fase da affrontare:** Fase 2 (dopo validazione MVP), continua ottimizzazione in Fase 3+
**Fonti:**
- [Freemium Conversion Rates](https://firstpagesage.com/seo-blog/saas-freemium-conversion-rates/) - 2-5% benchmark
- [Three Freemium Failure Modes](https://a16z.com/how-to-optimize-your-free-tier-freemium/) - Too generous vs too restrictive
- [Freemium Model Challenges](https://www.maxio.com/blog/freemium-model) - Resource costs
---
### Pitfall 7: WhatsApp/Telegram Bot Integration Trap
**Cosa va storto:**
WhatsApp richiede Business Account verificato, approvazione template messaggi, 24h response window. Meta ha **bannato AI chatbot generici dal 15 gennaio 2026**. Telegram è più permissivo ma supporta 1 solo webhook per bot (conflict se usi multiple piattaforme).
**Perché succede:**
- Assumono WhatsApp = Telegram (API molto diverse)
- Non leggono policy Meta → bot bannato
- Non gestiscono 24h window → messaggi bloccati
- Webhook conflicts su Telegram
**Prevenzione:**
- Usare WhatsApp Business API ufficiale (non workarounds)
- Template pre-approvati per notifiche programmate
- Telegram come primary bot (più flessibile), WhatsApp secondary
- Documentazione chiara: limitazioni di ogni piattaforma
- Test approvazione Meta in Fase 1 (può richiedere settimane)
**Fase da affrontare:** Fase 2-3 (non core MVP, feature differenziante)
**Fonti:**
- [WhatsApp Bot vs Telegram](https://botpenguin.com/blogs/whatsapp-bot-vs-telegram-bot) - Platform differences
- [WhatsApp AI Bots Ban 2026](https://www.globalbrandsmagazine.com/no-more-ai-bots-in-whatsapp-chats/) - Meta policy change
- [Telegram vs WhatsApp Development](https://alexasteinbruck.medium.com/bot-development-for-messenger-platforms-whatsapp-telegram-and-signal-2025-guide-50635f49b8c6) - Webhook limitations
---
### Pitfall 8: Chat-First UX Misconceptions
**Cosa va storto:**
Chat UX sembra "naturale" ma crea problemi: nessuna discoverability (utente non sa cosa chiedere), risposte istantanee sembrano "innaturali", nessun flusso di lavoro (constant switch tra implement e evaluate mode), 67% AI chatbots falliscono per UX.
**Perché succede:**
- Assumono "chat = semplice"
- Nessuna guida: blank input box senza suggerimenti
- Bot senza personalità (troppo robotico)
- Nessuna escalation a UI tradizionale quando chat fallisce
**Prevenzione:**
- Hybrid approach: chat + GUI (Fase 1)
- "Genera post su [topic]" → chat input
- Preview post → GUI editor tradizionale
- Schedule → calendar visual
- Suggerimenti prompt in chat ("Try: 'genera post LinkedIn su...'")
- Typing indicator + delay realistico (500-1000ms, non instant)
- Fallback to form: se utente confuso dopo 3 tentativi → "Want to use form instead?"
- Personality: friendly tone, emoji moderati, italiano colloquiale
**Fase da affrontare:** Fase 1 (design core UX), iterate in ogni fase
**Fonti:**
- [Chatbot UX Failures](https://research.aimultiple.com/chatbot-fail/) - 67% failure rate
- [Chat Interface Critique](https://wattenberger.com/thoughts/boo-chatbots) - Discoverability issues
- [Chatbot UX Mistakes](https://www.certainly.io/blog/top-ux-mistakes-chatbot) - Personality and transparency
- [Best Practices 2026](https://www.mindtheproduct.com/deep-dive-ux-best-practices-for-ai-chatbots/) - Hybrid approaches
---
### Pitfall 9: AI "Learning" User Preferences (Bias Amplification)
**Cosa va storto:**
AI che "impara" dalle preferenze può amplificare bias nel tempo. Se utente approva solo certi tipi di post, AI converge su quelli e smette di suggerire varietà. Bias possono manifestarsi in: query creation, retrieval, re-ranking. Il sistema diventa "echo chamber".
**Perché succede:**
- Feedback loop senza diversity safeguards
- Ranking basato solo su "cosa utente ha cliccato prima"
- Nessun exploration (solo exploitation)
- Metadata inconsistente → raccomandazioni rumorose
**Prevenzione:**
- Exploration vs Exploitation balance (Fase 3)
- 80% raccomandazioni basate su preferenze
- 20% varianti "esplorative" (toni diversi, format diversi)
- Diversity metrics: penalizza output troppo simili tra loro
- Esplicita user control: "Show me something different" button
- A/B test: learning vs random baseline (verifica se learning migliora davvero)
**Fase da affrontare:** Fase 3+ (feature avanzata, non MVP)
**Fonti:**
- [Bias in AI Personalization](https://arxiv.org/html/2512.16532v1) - Memory-enhanced agents bias
- [AI Personalization Challenges](https://www.bloomreach.com/en/blog/ai-personalization-5-examples-business-challenges) - Consistency issues
- [AI Learning Systems 2026](https://10web.io/blog/ai-personalization/) - Continuous adaptation risks
---
## Minor Pitfalls
Errori che causano fastidi ma sono facilmente risolvibili.
---
### Pitfall 10: Localizzazione Italiana Superficiale
**Cosa va storto:**
Traduzione automatica di UI inglese → italiano goffo. Prompt AI in inglese tradotti letteralmente. Ignorano cultura italiana social media (LinkedIn molto formale, Instagram casual).
**Prevenzione:**
- Copywriter italiano nativo per UI (non Google Translate)
- Prompt templates italiano nativo
- Esempi italiani: Salvini vs Chiara Ferragni tone molto diversi
- Date format DD/MM/YYYY (non MM/DD)
- Euro €, non $ (sembra ovvio ma molti sbagliano)
**Fase da affrontare:** Fase 1 (dall'inizio, non retrofittare)
**Fonti:**
- [Italian SaaS Adoption Barriers](https://www.bonafideresearch.com/product/6404494712/italy-software-as-a-service-saas-market) - Digital skills gap
- [Italy Digital Economy](https://www.trade.gov/country-commercial-guides/italy-digital-economy) - Localization importance
---
### Pitfall 11: Image Generation Quality vs Cost Tradeoff
**Cosa va storto:**
DALL-E 3 costa $20/mese (ChatGPT Plus) con 50 img/3h window. Midjourney $10/mese unlimited. Utenti si aspettano qualità Midjourney a costo DALL-E free tier.
**Prevenzione:**
- Tier chiaro: Free = no images, Basic = DALL-E, Pro = Midjourney
- Preview generazione: "This will use 1 of your 10 monthly images"
- Caching immagini: riusa se prompt simile
- Template library: immagini pre-generate gratis, AI custom a pagamento
**Fase da affrontare:** Fase 2 (immagini non core MVP)
**Fonti:**
- [AI Image Generation Costs](https://www.imagine.art/blogs/ai-image-generation-cost) - Pricing models
- [Midjourney vs DALL-E](https://www.picwand.ai/ai-generation/midjourney-vs-dalle/) - Cost comparison
---
### Pitfall 12: Vanity Metrics Trap
**Cosa va storto:**
Team festeggia "100K post generati!" ma conversion rate è 1% e churn 60%. Si concentrano su follower, likes, impressions invece di revenue, retention, engagement rate.
**Prevenzione:**
- Dashboard metriche business: MRR, churn, CAC, LTV
- Ignore vanity: follower count irrilevante se non convertono
- North Star Metric: "posts successfully published and engaged" (non "draft created")
**Fase da affrontare:** Fase 2+ (dopo product-market fit)
**Fonti:**
- [SaaS Vanity Metrics](https://www.moengage.com/blog/7-social-media-marketing-mistakes-to-avoid/) - Focus on business goals
- [Social Media Mistakes](https://www.bayleafdigital.com/b2b-saas-social-media-marketing-mistakes/) - Metrics alignment
---
## Phase-Specific Warnings
Pitfall probabili per fase del progetto.
| Fase | Pitfall Probabile | Mitigazione |
|------|-------------------|-------------|
| **Fase 1: MVP Core** | API rate limits non gestiti | Implement exponential backoff + token refresh dal giorno 1 |
| **Fase 1: MVP Core** | Onboarding overwhelming | Time-to-value <5min, progressive disclosure |
| **Fase 1: MVP Core** | AI slop generico | Brand voice onboarding obbligatorio |
| **Fase 1: MVP Core** | Costi AI esplosivi | AI gateway + caching + freemium limits |
| **Fase 2: Multi-Account** | Scheduling failures silenziosi | Job queue + retry + notifications |
| **Fase 2: Freemium Launch** | Tier miscalibration | A/B test generosità, monitor conversion 2-5% |
| **Fase 3: Advanced AI** | Chat UX confusion | Hybrid chat+GUI, suggerimenti prompt |
| **Fase 3: Personalization** | Bias amplification | Exploration 20%, diversity metrics |
| **Fase 4: Bot Integration** | WhatsApp policy violations | Test approvazione Meta early, Telegram primary |
| **Ogni Fase** | Vanity metrics distraction | Dashboard business metrics weekly review |
---
## Red Flags da Monitorare
Segnali di warning precoce che indicano un pitfall in corso:
### Technical
- ⚠️ API error rate >1% → Rate limit o token issues incoming
- ⚠️ AI cost/user >$0.50/mese in freemium → Unsustainable
- ⚠️ Post publish success rate <99% → Scheduling reliability problem
- ⚠️ Cache hit rate <50% → Sprechi API calls
### User Behavior
- ⚠️ Activation rate <40% → Onboarding troppo complesso
- ⚠️ Utenti editano >70% draft AI → AI quality insufficiente
- ⚠️ Session time <3min → Non trovano valore o UI confusa
- ⚠️ Freemium utenti attivi >6 mesi senza upgrade → Tier troppo generoso
### Business
- ⚠️ Churn >10%/mese → Prodotto non sticky o value prop debole
- ⚠️ Support tickets >20%/utenti attivi → UX o reliability issues
- ⚠️ Conversion freemium <2% → Tier miscalibration
- ⚠️ CAC > 6 mesi LTV → Unit economics broken
---
## Fonti di Ricerca
Questa ricerca si basa su analisi di:
- **Social Media Management SaaS**: Trend 2026, errori comuni, best practices
- **AI Content Generation**: Qualità, autenticità, brand voice consistency
- **Social API Integration**: Meta/Instagram rate limits, token management
- **Multi-AI Provider Management**: Costi, orchestrazione, vendor lock-in
- **Freemium SaaS Models**: Conversion rates, pricing calibration
- **Bot Integration**: WhatsApp/Telegram differenze, policy compliance
- **SaaS Onboarding**: Progressive disclosure, time-to-value, activation
- **Italian Market**: Barriere adozione SaaS, localizzazione, digital skills gap
**Confidence Level**: MEDIUM-HIGH
- Tutti i dati sono verificati con fonti multiple recenti (2026)
- Statistiche specifiche citate dove disponibili
- Alcune metriche sono benchmark generali SaaS (non micro-SaaS specifici)
- Recommendations basate su pattern industry consolidati
**Limitazioni**:
- Nessun dato specifico su "AI social media management per freelance italiani" (nicchia troppo specifica)
- Benchmark generalizzati da SaaS B2B/B2C, non verticale specifico
- Alcuni costi AI potrebbero variare rapidamente (verificare prezzi correnti a ogni fase)
**Sources Bibliography**:
1. Instagram Graph API Developer Guide 2025
2. Handling API Rate Limits - Facebook/Instagram
3. AI Content Authenticity Crisis 2026 - Digiday
4. AI Infrastructure Cost Optimization - Deloitte
5. Freemium Conversion Rates - First Page Sage
6. Progressive Onboarding Best Practices - Eleken
7. Chatbot UX Failures - AIM Multiple
8. WhatsApp vs Telegram Bot Development Guide
9. Italian SaaS Market Analysis - Bonafide Research
10. Social Media Management 2026 Trends - Hootsuite
**Tutte le fonti complete linkate nel corpo del documento.**

707
.planning/research/STACK.md Normal file
View File

@@ -0,0 +1,707 @@
# Technology Stack
**Project:** Leopost - AI Social Media Management SaaS
**Researched:** 2026-01-31
**Overall Confidence:** HIGH
## Executive Summary
The 2025/2026 standard stack for AI-powered social media management SaaS centers around **Next.js 15+ with React 19**, **Supabase** for backend, **Vercel AI SDK** for multi-provider AI, and **BullMQ** for job scheduling. This recommendation is based on verified current versions, ecosystem maturity, and specific requirements for headless architecture and Italian market deployment.
---
## Recommended Stack
### Core Framework
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **Next.js** | 15.5+ (or 16.x) | Full-stack React framework | - Stable Turbopack for fast dev/builds<br>- Server Actions eliminate API boilerplate<br>- Built-in API routes for webhooks<br>- Excellent Vercel deployment<br>- Ready for headless architecture (separate frontend/backend)<br>**Confidence:** HIGH |
| **React** | 19.2+ | UI library | - Stable release (Dec 2024)<br>- Actions API perfect for AI streaming<br>- Server Components for reduced bundle size<br>- `use` API for async data<br>**Confidence:** HIGH |
| **TypeScript** | 5.8+ | Type safety | - Latest stable (Feb 2025)<br>- `--erasableSyntaxOnly` for Node.js compatibility<br>- Improved performance in watch mode<br>**Confidence:** HIGH |
| **Node.js** | 20 LTS | Runtime | - LTS support through 2026-04-30<br>- Native TypeScript support (experimental)<br>- Required for BullMQ<br>**Confidence:** HIGH |
**Installation:**
```bash
npx create-next-app@latest leopost --typescript --tailwind --app --use-npm
```
---
### Database & Backend
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **Supabase** | Cloud (latest) | PostgreSQL + Auth + Storage | - **Perfect for Italian SaaS**: Free tier supports 50k MAU<br>- Built-in social auth (Google, Facebook)<br>- Row-Level Security (RLS) for multi-tenant<br>- Real-time subscriptions for editorial calendar<br>- Storage for user-uploaded images/logos<br>- 4-5x cheaper than Firebase<br>**Confidence:** HIGH |
| **Drizzle ORM** | 0.36+ | Type-safe ORM | - **Faster than Prisma** for simple queries<br>- SQL-like syntax (easier for complex queries)<br>- Excellent Supabase integration<br>- Smaller bundle size for edge functions<br>- Better serverless cold starts<br>**Alternative:** Prisma (if DX > performance)<br>**Confidence:** MEDIUM |
| **Redis** | 7.2+ (via Upstash) | Job queue storage | - Required for BullMQ<br>- Upstash offers serverless Redis (free tier)<br>- Sub-10ms latency globally<br>- No connection management<br>**Confidence:** HIGH |
**Why Supabase over VPS Supabase:**
- **Isolation**: Each customer gets isolated database (security)
- **Scalability**: Auto-scaling, no VPS resource limits
- **Compliance**: SOC2 on Team plan ($599/mo when needed)
- **Free tier**: 500MB DB, 1GB storage, 2GB bandwidth
---
### AI Integration
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **Vercel AI SDK** | 6.0+ | Multi-provider AI orchestration | - **Single API for GPT, Claude, Gemini**<br>- Built-in streaming with React hooks<br>- Automatic retry/fallback between providers<br>- Smaller bundle than individual SDKs<br>- Native Next.js integration<br>- OpenResponses API support (Jan 2026)<br>**Confidence:** HIGH |
| **OpenAI SDK** | 4.x | GPT models (primary) | - GPT-4 Turbo for content generation<br>- DALL-E 3 for image generation ($0.040/image)<br>- Function calling for structured output<br>**Confidence:** HIGH |
| **Anthropic SDK** | 0.x | Claude models (fallback) | - Claude 3.5 Sonnet for long-form content<br>- 200k token context for brand memory<br>- Lower hallucination rate<br>**Confidence:** HIGH |
| **Google AI SDK** | 0.x | Gemini models (budget) | - Gemini Pro free tier (60 req/min)<br>- Multimodal for image + text<br>- Good for Italian language<br>**Confidence:** MEDIUM |
**Image Generation Strategy:**
- **Primary**: DALL-E 3 via OpenAI API ($0.040/image standard quality)
- **Alternative**: Stable Diffusion via Replicate API ($0.002/image) for budget tier
- **Why not Midjourney**: No API access, Discord-only workflow
**Multi-Provider Strategy:**
```typescript
// Vercel AI SDK handles provider switching automatically
import { openai, anthropic, google } from '@ai-sdk/openai'
import { streamText } from 'ai'
// Automatic fallback: OpenAI → Claude → Gemini
const result = await streamText({
model: openai('gpt-4-turbo'),
prompt: userInput,
fallbacks: [anthropic('claude-3-5-sonnet'), google('gemini-pro')]
})
```
---
### Job Scheduling & Queue
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **BullMQ** | 5.66+ | Background job processing | - **Industry standard** for social media scheduling<br>- Redis-backed persistence<br>- Cron expressions for recurring posts<br>- Timezone-aware scheduling<br>- Automatic retries on API failures<br>- Horizontal scaling support<br>- 854 dependent packages (proven)<br>**Confidence:** HIGH |
| **Upstash Redis** | - | Queue storage | - Serverless Redis (no connection pooling)<br>- Free tier: 10k commands/day<br>- Global edge network<br>- REST API (works with serverless)<br>**Confidence:** HIGH |
**Why BullMQ over alternatives:**
- **vs Agenda**: BullMQ has Redis persistence (Agenda uses MongoDB)
- **vs node-cron**: BullMQ handles job failures, retries, distributed systems
- **vs Inngest**: BullMQ is open-source, no vendor lock-in
**Installation:**
```bash
npm install bullmq ioredis
```
---
### Social Media APIs
| Platform | API | Purpose | Why |
|----------|-----|---------|-----|
| **Facebook + Instagram** | Meta Graph API | Post to Pages/Business accounts | - **Unified API** for both platforms<br>- Supports Photos, Videos, Carousels, Reels, Stories<br>- Built-in scheduling (publish_time)<br>- Free (no API costs)<br>- Requires Business/Creator account<br>**Confidence:** HIGH |
| **LinkedIn** | LinkedIn Developer API | Post to personal/company pages | - Marketing Developer Platform<br>- Supports images, videos, articles<br>- UGC (User Generated Content) API<br>- Free (rate limits apply)<br>**Confidence:** MEDIUM |
**Social Media API Wrapper (Recommended):**
- **Build custom wrapper** around Meta Graph API + LinkedIn API
- **Why not unified API services** (Late, Ayrshare):
- Added cost ($50-200/mo)
- Rate limits on top of platform limits
- Not needed for 3 platforms
- Custom wrapper = full control + no middleman
**Meta Graph API Setup:**
```bash
# Requires:
# 1. Facebook App (developers.facebook.com)
# 2. Business account verification
# 3. Instagram Professional account linked
# 4. App Review for instagram_content_publish permission
```
---
### Messaging Integration
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **Telegraf** | 4.16+ | Telegram Bot framework | - **TypeScript-native** (built-in types)<br>- Modern API (better than node-telegram-bot-api)<br>- Webhook + long polling support<br>- Scene-based conversations<br>- Middleware architecture<br>**Confidence:** HIGH |
| **WhatsApp Business API** | Cloud API | WhatsApp integration | - **Official Meta Cloud API** (free tier)<br>- Webhook-based message handling<br>- Template messages for notifications<br>- Requires Business verification<br>**Alternative:** Baileys (unofficial, risky)<br>**Confidence:** MEDIUM |
**Recommendation:**
- **Phase 1**: Telegram only (easier, no verification)
- **Phase 2**: WhatsApp (requires Meta Business verification, 2-4 weeks)
---
### UI & Styling
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **shadcn/ui** | Latest | Component library | - **Copy-paste components** (you own the code)<br>- Built on Radix UI (accessibility)<br>- TailwindCSS styling<br>- 130M+ monthly Radix downloads<br>- Used by Vercel, Linear, Supabase<br>- 5 visual styles (Vega, Nova, Maia, Lyra, Mira)<br>- Radix OR Base UI choice<br>**Confidence:** HIGH |
| **TailwindCSS** | 4.0+ | Utility-first CSS | - Industry standard for SaaS<br>- JIT compilation (small bundles)<br>- Dark mode built-in<br>- Responsive design utilities<br>**Confidence:** HIGH |
| **Lucide React** | Latest | Icon library | - Modern fork of Feather Icons<br>- Tree-shakeable (small bundle)<br>- Consistent 24x24 grid<br>- Default for shadcn/ui<br>**Confidence:** HIGH |
| **Radix UI** | Latest | Headless primitives | - **Best-in-class accessibility**<br>- ARIA attributes built-in<br>- Keyboard navigation<br>- Focus management<br>- Underlying tech for shadcn/ui<br>**Confidence:** HIGH |
**UI Setup:**
```bash
npx shadcn@latest init
npx shadcn@latest add button dialog calendar
```
---
### State Management
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **Zustand** | 5.0+ | Global state (AI providers, user settings) | - **Smallest bundle** (1.2KB)<br>- No boilerplate (vs Redux)<br>- Perfect for chat state, AI config<br>- Redux DevTools support<br>- Middleware for persistence<br>**Confidence:** HIGH |
| **Jotai** | 2.x+ | Atomic state (form fields, calendar) | - **Fine-grained reactivity**<br>- Perfect for editorial calendar cells<br>- Suspense support (async atoms)<br>- Minimal re-renders<br>- Works alongside Zustand<br>**Confidence:** MEDIUM |
**When to use each:**
- **Zustand**: AI provider selection, brand context, global settings
- **Jotai**: Editorial calendar state, form validation, derived computations
---
### Payment Processing
| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| **Stripe** | Latest | Payment processor | - **Dominant in Italy** (supports SEPA, cards)<br>- Native Italian invoicing (fatturazione elettronica)<br>- Subscription management built-in<br>- Strong fraud prevention<br>- 2.9% + €0.25 per transaction<br>- Customer Portal for self-service<br>**Confidence:** HIGH |
**Why Stripe over alternatives:**
- **vs Paddle**: Paddle 5% + $0.50 (more expensive), US-focused
- **vs Lemon Squeezy**: Acquired by Stripe (unstable), server issues reported
- **Stripe = standard** for EU SaaS billing compliance
**Italian Requirements:**
- Enable Stripe Tax for Italian VAT (22%)
- Issue invoices via Stripe Invoicing
- SDI (Sistema di Interscambio) integration for e-invoicing
---
## Supporting Libraries
### Essential
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| **zod** | 3.x | Schema validation | All API routes, form validation, AI outputs |
| **date-fns** | 3.x | Date manipulation | Scheduling, timezone conversion, calendar |
| **react-hook-form** | 7.x | Form management | Post composer, settings forms |
| **@tanstack/react-query** | 5.x | Server state | Cache social media posts, user data |
| **clsx** + **tailwind-merge** | Latest | Conditional CSS | Dynamic component styling |
| **sonner** | Latest | Toast notifications | Success/error messages, post confirmations |
| **cmdk** | Latest | Command palette | Chat UI, keyboard shortcuts |
### AI-Specific
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| **ai** (Vercel) | 6.x | AI streaming hooks | `useChat()`, `useCompletion()` for chat UI |
| **openai** | 4.x | Direct OpenAI access | Image generation, embeddings |
| **@anthropic-ai/sdk** | 0.x | Direct Claude access | Long-form content, low hallucination |
| **@google/generative-ai** | 0.x | Direct Gemini access | Free tier for budget users |
| **langchain** | 0.3.x | AI agent orchestration | Future: multi-step workflows, RAG |
### Utilities
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| **axios** | 1.x | HTTP client | Social media API calls (better than fetch) |
| **sharp** | 0.33+ | Image processing | Resize uploads, optimize for platforms |
| **uuid** | 10.x | Unique IDs | Job IDs, session tracking |
| **jose** | 5.x | JWT handling | Supabase JWT verification |
| **winston** | 3.x | Logging | Production error tracking |
---
## Alternatives Considered
| Category | Recommended | Alternative | Why Not Alternative |
|----------|-------------|-------------|---------------------|
| **Framework** | Next.js | Remix, Astro | Next.js has better AI SDK integration, larger ecosystem, Vercel deployment |
| **Backend** | Supabase | Firebase, PlanetScale | Supabase cheaper, PostgreSQL > Firestore for relational data, RLS built-in |
| **ORM** | Drizzle | Prisma | Drizzle faster runtime, better edge support. Prisma better DX, slower cold starts |
| **AI SDK** | Vercel AI SDK | Individual SDKs | Vercel SDK provides unified API, automatic fallbacks, smaller bundle |
| **Queue** | BullMQ | Inngest, Trigger.dev | BullMQ open-source, self-hosted, no vendor lock-in, proven at scale |
| **State** | Zustand | Redux, Recoil | Zustand 1.2KB, zero boilerplate, easier learning curve for freelancers |
| **UI** | shadcn/ui | Chakra, MUI | shadcn = you own code, no runtime overhead, Tailwind-native |
| **Payment** | Stripe | Paddle, PayPal | Stripe best Italian compliance, e-invoicing support, most reliable |
| **Image Gen** | DALL-E 3 | Midjourney | Midjourney has no API, DALL-E has predictable pricing, better prompt adherence |
---
## Architecture Decisions
### Headless Architecture
**Frontend (Next.js App Router):**
```
/app
/api # API routes for webhooks (Meta, Stripe)
/(auth) # Auth pages (login, signup)
/(dashboard) # Protected dashboard routes
/chat # AI chat interface
/calendar # Editorial calendar
/settings # User settings
```
**Backend (Next.js Server Actions + API Routes):**
```
/actions # Server Actions for mutations
/posts.ts # Create, update, delete posts
/ai.ts # AI generation actions
/social.ts # Social media API calls
/lib
/queue # BullMQ job definitions
/supabase # Supabase client, queries
/ai # AI provider wrappers
/social # Meta Graph API, LinkedIn API
```
**Why Server Actions over API Routes:**
- **For internal mutations**: Server Actions (simpler, type-safe, auto-revalidation)
- **For webhooks/public endpoints**: API Routes (Meta webhooks, Stripe webhooks)
### Database Schema Strategy
**Multi-Tenancy with RLS:**
```sql
-- Supabase Row-Level Security
CREATE POLICY "Users can only see their own posts"
ON posts FOR SELECT
USING (auth.uid() = user_id);
-- Indexes for performance
CREATE INDEX posts_user_scheduled_idx
ON posts(user_id, scheduled_at)
WHERE status = 'scheduled';
```
**Key Tables:**
- `users` (Supabase Auth managed)
- `posts` (content, platforms, scheduled_at, status)
- `brand_contexts` (logos, colors, company info, embeddings)
- `ai_provider_configs` (API keys per user)
- `social_accounts` (connected FB/IG/LinkedIn accounts)
- `usage_tracking` (tier limits, AI token usage)
---
## Development Workflow
### Local Development
```bash
# 1. Install dependencies
npm install
# 2. Setup environment variables
cp .env.example .env.local
# Add: NEXT_PUBLIC_SUPABASE_URL, SUPABASE_SERVICE_KEY
# OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_KEY
# UPSTASH_REDIS_URL, STRIPE_SECRET_KEY
# 3. Run Supabase locally (optional)
npx supabase start
# 4. Run dev server
npm run dev
# 5. Run queue worker (separate terminal)
npm run queue:dev
```
### Deployment
**Recommended: Vercel + Upstash + Supabase Cloud**
```bash
# 1. Deploy Next.js to Vercel
vercel deploy --prod
# 2. Setup Upstash Redis (serverless)
# Free tier: 10k commands/day
# 3. Setup Supabase Cloud
# Free tier: 500MB DB, 50k MAU
# 4. Deploy BullMQ worker
# Option A: Vercel Serverless Function (cron-triggered)
# Option B: Separate Node.js process on VPS (24/7)
```
**VPS Deployment (Alternative):**
- Deploy Next.js on VPS (Docker container)
- BullMQ worker as separate container
- Redis on VPS or Upstash
- Lower cost, more control, complex setup
---
## Cost Analysis
### Free Tier Limits (MVP)
| Service | Free Tier | Monthly Cost at 100 Users | Notes |
|---------|-----------|---------------------------|-------|
| **Vercel** | 100GB bandwidth, 1k serverless hours | $0 (likely within free tier) | Upgrade to Pro at $20/mo if needed |
| **Supabase** | 500MB DB, 50k MAU, 1GB storage | $0 | Upgrade to Pro at $25/mo at 100k MAU |
| **Upstash Redis** | 10k commands/day | $0 | ~$10/mo if exceeding (100k commands) |
| **OpenAI** | Pay-per-use | ~$50-150 | GPT-4 Turbo: $0.01/1k tokens, DALL-E: $0.04/image |
| **Anthropic** | Pay-per-use | ~$30-100 | Claude 3.5 Sonnet: $0.003/1k in, $0.015/1k out |
| **Gemini** | 60 req/min free | $0 | Free tier generous for fallback |
| **Stripe** | Pay-per-transaction | 2.9% + €0.25 per transaction | No monthly fee |
| **Meta APIs** | Free | $0 | Facebook + Instagram + WhatsApp Cloud API |
| **LinkedIn API** | Free (rate limited) | $0 | - |
| **Telegram API** | Free | $0 | - |
**Total MVP Cost:** $50-150/mo (mostly AI tokens)
**Total at 100 Paying Users ($20/mo avg):** $200-300/mo (AI scales with usage)
---
## Security Considerations
### API Key Management
```typescript
// NEVER expose API keys client-side
// ❌ DON'T:
// process.env.NEXT_PUBLIC_OPENAI_API_KEY
// ✅ DO: Use Server Actions or API Routes
'use server'
export async function generateContent(prompt: string) {
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
// ...
}
```
### Supabase RLS
```sql
-- Enable RLS on ALL tables
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
-- Create policies for CRUD
CREATE POLICY "Users CRUD own posts"
ON posts FOR ALL
USING (auth.uid() = user_id);
```
### Rate Limiting
```typescript
// Use Upstash Rate Limit
import { Ratelimit } from '@upstash/ratelimit'
import { Redis } from '@upstash/redis'
const ratelimit = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(10, '1 m'), // 10 requests per minute
})
// In API route or Server Action
const { success } = await ratelimit.limit(userId)
if (!success) throw new Error('Rate limit exceeded')
```
---
## Performance Optimization
### Next.js Optimizations
```typescript
// 1. Enable Turbopack (default in Next.js 16)
// next.config.js
module.exports = {
experimental: {
turbo: true,
},
}
// 2. Optimize images
import Image from 'next/image'
<Image src="/logo.png" width={200} height={200} alt="Logo" />
// 3. Use Server Components by default
// Only add 'use client' when needed (interactivity)
// 4. Dynamic imports for heavy components
const Editor = dynamic(() => import('./Editor'), { ssr: false })
```
### Database Optimizations
```sql
-- Indexes for common queries
CREATE INDEX posts_user_status_idx ON posts(user_id, status);
CREATE INDEX posts_scheduled_at_idx ON posts(scheduled_at) WHERE status = 'scheduled';
-- Partial indexes for active data
CREATE INDEX active_posts_idx ON posts(user_id, created_at)
WHERE status IN ('draft', 'scheduled');
```
### AI Response Caching
```typescript
// Cache common AI responses
import { unstable_cache } from 'next/cache'
const getCachedAIResponse = unstable_cache(
async (prompt: string) => {
return await generateContent(prompt)
},
['ai-response'],
{ revalidate: 3600 } // 1 hour
)
```
---
## Testing Strategy
### Recommended Tools
| Type | Tool | Why |
|------|------|-----|
| **Unit** | Vitest | Faster than Jest, ESM support, compatible with Next.js |
| **Integration** | Playwright | E2E testing, headless browser, multi-browser |
| **API** | MSW (Mock Service Worker) | Mock social media APIs, AI APIs for testing |
| **Type** | TypeScript + Zod | Runtime + compile-time validation |
### Testing Social Media APIs
```typescript
// Mock Meta Graph API responses
import { http, HttpResponse } from 'msw'
export const handlers = [
http.post('https://graph.facebook.com/v18.0/me/feed', () => {
return HttpResponse.json({ id: 'post_123' })
}),
]
```
---
## Internationalization (i18n)
### Italian Market Specifics
```typescript
// Use next-intl for i18n
import { useTranslations } from 'next-intl'
const t = useTranslations('Dashboard')
t('welcome') // "Benvenuto"
// Italian date formatting
import { format } from 'date-fns'
import { it } from 'date-fns/locale'
format(new Date(), 'PPP', { locale: it })
// "31 gennaio 2026"
```
### Future Multi-Language
**Phase 1**: Italian only
**Phase 2**: Add English (for expansion)
**Setup:**
```bash
npm install next-intl
```
---
## Monitoring & Observability
### Recommended Tools
| Category | Tool | Why |
|----------|------|-----|
| **Error Tracking** | Sentry | Best Next.js integration, free tier 5k events/mo |
| **Analytics** | Vercel Analytics | Built-in, privacy-friendly, free on Pro plan |
| **Logging** | Axiom | Serverless-friendly, generous free tier |
| **APM** | Vercel Speed Insights | Built-in performance monitoring |
| **Uptime** | BetterStack | Free tier, status page, incident management |
---
## Sources
### Framework & Core
- [Next.js for SaaS Dashboards: Architecture and Best Practices](https://www.ksolves.com/blog/next-js/best-practices-for-saas-dashboards)
- [Modern Full Stack Application Architecture Using Next.js 15+](https://softwaremill.com/modern-full-stack-application-architecture-using-next-js-15/)
- [Server Actions vs API Routes in Next.js 15](https://www.wisp.blog/blog/server-actions-vs-api-routes-in-nextjs-15-which-should-i-use)
- [Next.js 15.5 Release Notes](https://nextjs.org/blog/next-15-5)
- [React v19 Release](https://react.dev/blog/2024/12/05/react-19)
- [TypeScript 5.8 Release](https://devblogs.microsoft.com/typescript/announcing-typescript-5-8/)
### AI & Multi-Provider
- [AI SDK 6 - Vercel](https://vercel.com/blog/ai-sdk-6)
- [Building a Complete Multi-AI Chat Platform](https://medium.com/@reactjsbd/building-a-complete-multi-ai-chat-platform-chatgpt-claude-gemini-grok-in-one-interface-4295d10e3174)
- [OpenAI SDK vs Vercel AI SDK Comparison](https://strapi.io/blog/openai-sdk-vs-vercel-ai-sdk-comparison)
- [The 9 Best AI Image Generation Models in 2026](https://www.gradually.ai/en/ai-image-models/)
- [DALL-E vs Midjourney vs Stable Diffusion 2025 Comparison](https://aloa.co/ai/comparisons/ai-image-comparison/dalle-vs-midjourney-vs-stable-diffusion)
### Database & Backend
- [Supabase Review 2026](https://hackceleration.com/supabase-review/)
- [Drizzle vs Prisma: Choosing the Right TypeScript ORM](https://betterstack.com/community/guides/scaling-nodejs/drizzle-vs-prisma/)
- [Prisma vs Drizzle ORM in 2026](https://medium.com/@thebelcoder/prisma-vs-drizzle-orm-in-2026-what-you-really-need-to-know-9598cf4eaa7c)
### Job Queue & Scheduling
- [BullMQ - Background Jobs processing](https://bullmq.io/)
- [How to Build a Job Queue in Node.js with BullMQ and Redis](https://oneuptime.com/blog/post/2026-01-06-nodejs-job-queue-bullmq-redis/view)
- [Job Scheduling in Node.js with BullMQ](https://betterstack.com/community/guides/scaling-nodejs/bullmq-scheduled-tasks/)
### Social Media APIs
- [Instagram API 2026: Complete Developer Guide](https://getlate.dev/blog/instagram-api)
- [10 Best Social Media APIs for Developers [2026 Comparison]](https://getlate.dev/blog/top-10-social-media-apis-for-developers)
- [Meta Graph API: Considerations and Alternatives](https://data365.co/blog/meta-graph-api)
### Messaging Integration
- [Telegraf - Modern Telegram Bot Framework](https://github.com/telegraf/telegraf)
- [How to Build a WhatsApp Chatbot in Node.js](https://www.kommunicate.io/blog/build-a-whatsapp-chatbot-using-node-js/)
### UI & Components
- [shadcn/ui - The Foundation for your Design System](https://ui.shadcn.com/)
- [ShadCN UI vs Radix UI vs Tailwind UI](https://javascript.plainenglish.io/shadcn-ui-vs-radix-ui-vs-tailwind-ui-which-should-you-choose-in-2025-b8b4cadeaa25)
- [Radix Primitives](https://www.radix-ui.com/)
### State Management
- [Zustand vs. Redux Toolkit vs. Jotai](https://betterstack.com/community/guides/scaling-nodejs/zustand-vs-redux-toolkit-vs-jotai/)
- [State Management in 2025: Context, Redux, Zustand, or Jotai](https://dev.to/hijazi313/state-management-in-2025-when-to-use-context-redux-zustand-or-jotai-2d2k)
### Payments
- [Stripe vs Paddle vs Lemon Squeezy Comparison](https://medium.com/@muhammadwaniai/stripe-vs-paddle-vs-lemon-squeezy-i-processed-10k-through-each-heres-what-actually-matters-27ef04e4cb43)
- [Compare SaaS Payment Provider Fees](https://saasfeecalc.com/)
---
## Installation Guide
### Step 1: Create Next.js Project
```bash
npx create-next-app@latest leopost \
--typescript \
--tailwind \
--app \
--use-npm \
--import-alias "@/*"
cd leopost
```
### Step 2: Install Core Dependencies
```bash
# Framework essentials
npm install zod react-hook-form @hookform/resolvers date-fns clsx tailwind-merge
# Supabase
npm install @supabase/supabase-js @supabase/ssr
# Drizzle ORM
npm install drizzle-orm postgres
npm install -D drizzle-kit
# AI SDKs
npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google openai @anthropic-ai/sdk @google/generative-ai
# Queue
npm install bullmq ioredis
# State management
npm install zustand jotai
# UI components
npx shadcn@latest init
npx shadcn@latest add button dialog calendar form input textarea select
# Social media + messaging
npm install telegraf axios
# Payment
npm install stripe @stripe/stripe-js
# Utilities
npm install sonner cmdk sharp uuid jose winston
```
### Step 3: Setup Environment Variables
```bash
# .env.local
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx
SUPABASE_SERVICE_ROLE_KEY=xxx
# AI Providers
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GOOGLE_AI_API_KEY=xxx
# Redis (Upstash)
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxx
# Stripe
STRIPE_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
# Social Media
META_APP_ID=xxx
META_APP_SECRET=xxx
LINKEDIN_CLIENT_ID=xxx
LINKEDIN_CLIENT_SECRET=xxx
# Telegram
TELEGRAM_BOT_TOKEN=xxx
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
```
### Step 4: Initialize Supabase
```bash
npx supabase init
npx supabase db push
```
### Step 5: Run Development
```bash
# Terminal 1: Next.js dev server
npm run dev
# Terminal 2: BullMQ worker (create worker.ts first)
npm run queue:dev
```
---
## Next Steps
1. **Setup Supabase schema** (users, posts, brand_contexts)
2. **Configure Drizzle ORM** with Supabase connection
3. **Implement Vercel AI SDK** chat interface
4. **Setup BullMQ** job queue for scheduling
5. **Integrate Meta Graph API** for Facebook/Instagram
6. **Add Stripe** subscription management
7. **Deploy to Vercel** with environment variables
---
**Ready for Roadmap Creation**: This stack is production-ready, cost-effective for MVP, and scales to thousands of users.

395
.planning/research/SUMMARY.md Normal file
View File

@@ -0,0 +1,395 @@
# Project Research Summary
**Project:** Leopost - AI Social Media Management SaaS
**Domain:** AI-powered social media automation for Italian freelancers
**Researched:** 2026-01-31
**Confidence:** HIGH
## Executive Summary
Leopost is an AI-first social media management tool targeting Italian freelancers who need maximum output with minimum effort. Research shows the 2026 landscape is experiencing a fundamental shift: AI features moved from "nice to have" to "table stakes", but there's a growing backlash against over-automation and generic AI-generated content. The winners balance automation efficiency with authentic human touch.
The recommended approach is a **headless Next.js 15 architecture with Supabase Cloud backend**, **multi-AI provider orchestration (OpenAI/Anthropic/Google)** via Vercel AI SDK, and **BullMQ job queue** for reliable scheduling. Start with a modular monolith (rapid iteration) with clear component boundaries for future microservices transition. Critical: implement multi-tenancy isolation, brand voice memory, and robust rate limit handling from day 1.
The biggest risks are: (1) API rate limits causing silent scheduling failures, (2) AI generating generic "slop" that erodes brand authenticity, (3) runaway AI costs destroying unit economics, (4) overwhelming onboarding causing 60%+ activation churn. Each has proven mitigation strategies documented in PITFALLS.md.
## Key Findings
### Recommended Stack
The 2026 standard stack centers on **Next.js 15+ (Turbopack stable) with React 19**, **Supabase Cloud** for PostgreSQL + Auth + Storage, and **Vercel AI SDK 6.0+** for unified multi-provider AI orchestration. This stack is production-ready, cost-effective for MVP (€50-150/mo mostly AI tokens), and scales to thousands of users.
**Core technologies:**
- **Next.js 15 + React 19**: Full-stack framework with Server Actions (eliminate API boilerplate), Turbopack fast builds, ready for headless architecture
- **Supabase Cloud**: PostgreSQL + Auth + RLS for multi-tenant isolation, 4-5x cheaper than Firebase, perfect for Italian SaaS (free tier supports 50k MAU)
- **Vercel AI SDK**: Single API for GPT/Claude/Gemini with automatic fallback, built-in streaming, smaller bundle than individual SDKs
- **BullMQ + Upstash Redis**: Industry standard job queue for scheduling, Redis-backed persistence, timezone-aware, automatic retries on API failures
- **Drizzle ORM**: Faster than Prisma for simple queries, SQL-like syntax, excellent Supabase integration, better serverless cold starts
- **shadcn/ui + TailwindCSS**: Copy-paste components (you own code), built on Radix UI for accessibility, 5 visual styles available
- **Stripe**: Dominant in Italy with SEPA support, native Italian invoicing (fatturazione elettronica), 2.9% + €0.25 per transaction
**Alternative considerations:**
- Prisma over Drizzle if DX > performance (trade developer experience for runtime speed)
- Firebase over Supabase if need Google ecosystem (but 4-5x more expensive)
- Inngest/Trigger.dev over BullMQ if prefer managed service (trade control for simplicity)
### Expected Features
Research reveals AI caption generation crossed from "differentiator" to "table stakes" in 2024-2025. 71% of marketers use AI for content in 2026, but only 26% of consumers prefer AI content over human (down from 60% in 2023). The market demands AI that assists, not replaces.
**Must have (table stakes):**
- Multi-platform posting (Facebook, Instagram, LinkedIn minimum)
- Post scheduling with date/time picker
- Visual calendar view (month/week drag-and-drop)
- AI caption generation (single provider initially)
- Image upload and preview
- Basic analytics (engagement metrics, last 30 days)
- Smart scheduling (suggest optimal posting times)
- Multi-account management (freelancers manage multiple brands)
**Should have (differentiators):**
- **Brand voice memory** (AI learns user's authentic voice - combats "AI slop")
- **Configurable automation levels** (Preview every post → Auto-publish with approval → Full autopilot)
- **Platform-specific optimization** (LinkedIn formal, Instagram casual - avoid copy-paste feel)
- **WhatsApp/Telegram integration** (post via messaging apps - HIGH value for Italian market)
- **Multi-AI provider** (GPT/Claude/Gemini - hedges risk, leverages best-of-breed)
- **Progressive onboarding** (gradual feature introduction - 74% abandon if onboarding difficult)
- **Italian-first design** (UI/prompts in Italian - not just translation, culturally appropriate)
**Defer (v2+):**
- Chat-first UI (HIGH RISK - unproven UX pattern, needs extensive validation)
- AI image generation (nice-to-have, not critical path)
- TikTok/Twitter support (add based on user demand)
- Enterprise features (team collaboration 20+ users, SSO, audit logs)
- Social listening/monitoring (different product category)
- Native mobile apps (responsive web sufficient for MVP)
### Architecture Approach
The recommended architecture follows a **modular monolith transitioning to microservices** approach: start with Next.js monolith for rapid iteration, maintain clear component boundaries (API Gateway, Chat Service, AI Orchestrator, Social API Gateway, Job Queue Service, User Context Store), extract to microservices after product-market fit.
**Major components:**
1. **API Gateway / Auth Layer** — Single entry point, JWT authentication, tenant ID extraction, rate limiting per tenant, WebSocket connection management
2. **Chat Service** — Handle user messages (web/Telegram/WhatsApp), retrieve user context (brand info, conversation history), inject context into AI prompts, stream real-time responses via SSE
3. **AI Orchestrator** — Abstract multiple providers (OpenAI/Anthropic/Google) behind unified interface, route by task type, streaming response handling, retry + fallback logic, cost tracking per tenant
4. **Social API Gateway** — Centralize OAuth with platforms (Meta/LinkedIn/X), abstract APIs behind unified interface, normalize data formats, rate limiting per platform, credential refresh token management
5. **Job Queue Service (BullMQ)** — Schedule posts for future publishing, background analytics sync, retry failed publishes (exponential backoff), async image generation, bulk operations
6. **User Context Store** — Store tenant-specific brand voice, target audience, preferences; persist conversation history for AI context; learn from user feedback (thumbs up/down); future: vector embeddings for semantic search
7. **Multi-Tenant Data Isolation** — Shared database with RLS (Row-Level Security), tenant_id filter on all queries, middleware extracts tenant from JWT, PostgreSQL RLS as defense-in-depth
**Key patterns to follow:**
- **Multi-Provider Gateway**: Single interface abstracting AI providers (easy failover, cost optimization)
- **Context Injection**: Retrieve user brand info + conversation history, inject into prompts for personalized responses
- **Unified Social Adapter**: Abstract platform APIs (Facebook/LinkedIn) behind common interface (add platforms without changing core)
- **Background Job Queue**: Decouple long-running tasks (scheduled posts, image generation) from synchronous requests
- **Tenant Context Middleware**: Extract tenant_id from JWT at gateway, pass to all services, enforce in all database queries
**Anti-patterns to avoid:**
- Tight coupling to single AI provider (vendor lock-in)
- Missing tenant isolation in queries (catastrophic data leakage)
- Synchronous long-running tasks (request timeouts, no retry)
- No AI streaming (poor UX, 5-10 second blank screens)
- Platform-specific logic scattered in core services (bloat, difficult testing)
### Critical Pitfalls
Research identified 12 domain-specific pitfalls with proven mitigation strategies. The 5 critical ones that cause rewrites or product failure:
1. **API Rate Limits & Token Expiration** — Meta reduced Instagram API limits by 96% (5,000 → 200 DM/hour) in 2024. Projects without exponential backoff + automatic token refresh experience silent scheduling failures. **Prevent:** Implement exponential backoff with jitter, token refresh every 50-55 days, aggressive caching (reduces 70% calls), rate limit monitoring dashboard from Phase 1.
2. **AI "Slop" Content (Generic, Inauthentic)** — 71% of social images are AI-generated but only 26% of users prefer AI content (down from 60% in 2023). Generic prompts produce template-feeling posts that audiences ignore. **Prevent:** Brand voice onboarding mandatory (examples, tone, keywords, anti-patterns), human-in-the-loop review required, multi-stage quality control, learning from user-approved posts in Phase 2+.
3. **Runaway AI Costs** — Generating 1 post with image costs €0.15-0.50. 100 freemium users × 10 drafts/month × €0.30 = €300/mo LOSS. 84% of enterprises see margin erosion from AI costs. **Prevent:** AI Gateway with intelligent routing (simple tasks → GPT-4 Mini, creative → GPT-4), aggressive caching (hash prompts, reuse), freemium limits (5 AI drafts/month, no images in free tier), cost attribution per user/feature.
4. **Scheduling Reliability Failures (Silent Post Loss)** — Posts scheduled but never published due to token expiry, API changes, timezone bugs. Users discover campaign failed days later. **Prevent:** Distributed job queue (BullMQ on Redis), retry with exponential backoff (3 attempts), failure notifications (email + push), timezone validation (save UTC + user timezone separately), health checks 5min before publish.
5. **Onboarding Overwhelm (Firehose Problem)** — 63% abandon during complex onboarding. "Throwing every feature at new user at once causes instant confusion." **Prevent:** Progressive disclosure (Step 1: Generate 1 post in <2min, Step 2: Connect account, Step 3: Schedule), time-to-value <5 minutes, role-aware onboarding paths (freelance vs agency), contextual tooltips not forced tours.
**Moderate pitfalls:** Freemium tier miscalibration (2-5% conversion benchmark), WhatsApp Business verification complexity (Meta banned AI bots Jan 2026), Chat-first UX discoverability issues (67% chatbots fail on UX).
**Minor pitfalls:** Superficial Italian localization (use native copywriter, not Google Translate), image generation cost vs quality tradeoff (DALL-E vs Midjourney pricing), vanity metrics distraction (focus on MRR/churn not follower count).
## Implications for Roadmap
Based on research, the optimal phasing balances rapid MVP validation with sustainable technical foundation. The critical insight: **don't start with chat-first UI** (highest risk feature) - build solid API foundation first.
### Phase 1: Core Scheduling Foundation (MVP)
**Rationale:** Deliver minimum viable experience to validate product-market fit. Focus on proven patterns (multi-platform scheduling) before risky innovations (chat UI). This phase addresses all 5 critical pitfalls from day 1.
**Delivers:**
- Multi-platform posting (Facebook, Instagram, LinkedIn)
- Post scheduling with visual calendar (drag-and-drop)
- AI caption generation (single provider: Claude for quality, GPT-4 Mini for cost alternative)
- Image upload and preview (S3/Supabase Storage)
- Basic analytics (engagement metrics, last 30 days)
- Italian UI and prompts (native localization, not translation)
**Stack elements:**
- Next.js 15 + React 19 (Server Actions for mutations)
- Supabase Cloud (PostgreSQL + Auth + RLS)
- Single AI provider (start with OpenAI GPT-4 Mini for cost, or Claude for quality)
- Basic scheduling (setTimeout for MVP, transition to BullMQ in Phase 2)
- shadcn/ui components
**Addresses pitfalls:**
- **Brand voice onboarding** (form capturing tone, examples, keywords) - mitigates AI slop
- **Exponential backoff + token refresh** - mitigates rate limits
- **Freemium limits** (5 AI drafts/month, no images) - mitigates runaway costs
- **Progressive onboarding** (generate post → connect account → schedule) - mitigates overwhelm
- **Multi-tenant RLS** (Supabase Row-Level Security from day 1) - prevents data leakage
**Success criteria:** 100 active users posting 500+ scheduled posts/week, activation rate >40%, post publish success rate >95%
**Duration estimate:** 6-8 weeks for solo developer
---
### Phase 2: Reliability & Differentiation
**Rationale:** After MVP validation, add features that separate Leopost from Buffer/Hootsuite. This phase requires data from Phase 1 user activity (brand voice learning needs examples, smart scheduling needs analytics).
**Delivers:**
- **BullMQ job queue** (replace setTimeout with Redis-backed persistence)
- **Brand voice memory** (learn from user's approved posts, fine-tune prompts)
- **Smart scheduling** (AI suggests best times based on platform analytics)
- **Platform-specific optimization** (adapt tone per network - LinkedIn formal, Instagram casual)
- **Content recycling** (evergreen post queue, SocialBee pattern)
- **Approval workflow** (draft → review → approve → publish for client work)
- **Multi-user accounts** (freelancer + VA/assistant, 2-5 users max)
**Stack elements:**
- BullMQ + Upstash Redis (serverless Redis for job queue)
- Drizzle ORM (faster queries for analytics)
- React Query (cache social media posts, user data)
- Vector DB exploration (Supabase pgvector for brand voice embeddings)
**Addresses pitfalls:**
- **Scheduling reliability** (job queue with retry, failure notifications) - critical for trust
- **AI quality improvement** (brand voice learning reduces generic output)
- **Freemium calibration** (A/B test tier generosity, monitor 2-5% conversion)
**Success criteria:** 50% of users enable brand voice memory, average 3 platforms connected per user, post publish success rate >99%, freemium conversion 2-5%
**Duration estimate:** 4-6 weeks (builds on MVP infrastructure)
---
### Phase 3: Advanced Innovation (High Risk, High Reward)
**Rationale:** These are unique features no competitor has, but also highest implementation risk. Defer until core product is stable and user feedback validates demand. Chat-first UI needs extensive UX validation before full implementation.
**Delivers:**
- **Multi-AI provider** (add Anthropic Claude + Google Gemini to OpenAI)
- **Chat-first UI prototype** (conversational post creation - validate with user testing)
- **WhatsApp/Telegram bots** (post creation via messaging - high value for Italian market)
- **AI image generation** (DALL-E 3 / Stable Diffusion via Replicate)
- **Advanced analytics** (competitor benchmarking, sentiment analysis)
**Stack elements:**
- Vercel AI SDK (unified multi-provider orchestration)
- LiteLLM or custom AI Gateway (provider routing, fallback)
- Telegraf (Telegram bot framework)
- WhatsApp Business Cloud API (requires Meta verification, 2-4 weeks)
- Sharp (image processing for platform-specific optimization)
**Addresses pitfalls:**
- **Multi-provider** hedges vendor lock-in risk, enables cost optimization
- **WhatsApp integration** requires Business verification (start process early)
- **Chat UX** needs hybrid approach (chat + GUI fallback for when chat fails)
- **Image generation** needs cost management (tier-specific limits)
**Success criteria:** Chat-first UI has 70%+ satisfaction, WhatsApp/Telegram handle 20% of post creation, multi-provider reduces AI costs by 15-25%
**Duration estimate:** 8-12 weeks (higher complexity, experimental features)
---
### Phase 4: Scale & Polish (Production Ready)
**Rationale:** After product-market fit proven, focus on operational excellence, performance optimization, and enterprise readiness.
**Delivers:**
- Horizontal scaling (2-3 Next.js servers with load balancing)
- Database read replicas (PgBouncer connection pooling)
- CDN for static assets (Cloudflare)
- Advanced monitoring (Sentry error tracking, Axiom logging, BetterStack uptime)
- Security hardening (rate limiting with Upstash, DDoS protection)
- Performance optimization (AI response caching, database indexes, image optimization pipeline)
**Stack elements:**
- Nginx/Kong API Gateway (replace Next.js API routes for microservices)
- Redis Pub/Sub (cross-server WebSocket messaging)
- Vercel Analytics + Speed Insights
- Sentry (error tracking, 5k events/mo free tier)
**Addresses pitfalls:**
- **Scalability** (database connection pooling, read replicas)
- **Cost efficiency** (AI response caching, CDN reduces bandwidth)
- **Reliability** (distributed systems, no single point of failure)
**Success criteria:** >10K active users, 99.9% uptime, <100ms p95 API latency, AI cost/user <€0.30/month
**Duration estimate:** Ongoing (continuous optimization)
---
### Phase Ordering Rationale
**Why this order:**
1. **MVP first** (Phase 1) validates core value proposition ("AI makes social posting effortless") before investing in risky innovations. Proven patterns (scheduling, calendar, AI generation) have clear implementation paths.
2. **Reliability before features** (Phase 2) builds trust. BullMQ job queue and brand voice memory require Phase 1 data (user posts to learn from, analytics to optimize scheduling).
3. **Innovation when stable** (Phase 3) defers chat-first UI and multi-provider until core product is proven. These features are differentiators but have execution risk (chat UX unproven, multi-provider adds complexity).
4. **Scale when needed** (Phase 4) optimizes only after hitting limits. Premature optimization wastes time on problems you don't have yet.
**Dependency analysis:**
- **Critical path**: Auth → Context Store → Chat Service → AI Orchestrator (must build sequentially)
- **Parallel tracks**: Social API Gateway can develop independently of Chat Service, integrate when both ready
- **Data dependencies**: Brand voice memory needs user-approved posts (Phase 1 data), smart scheduling needs analytics (Phase 1 data)
**Pitfall mitigation built into phasing:**
- Phase 1 implements exponential backoff, token refresh, freemium limits (prevents critical failures)
- Phase 2 adds job queue, monitoring (prevents silent scheduling failures)
- Phase 3 validates chat UX before full rollout (prevents UX disaster)
### Research Flags
**Phases likely needing deeper research during planning:**
- **Phase 2 (BullMQ)**: Queue configuration, Redis persistence, retry strategies, timezone handling, cron expressions for recurring posts. *Why:* Scheduling reliability is critical, many edge cases (DST transitions, leap years, API rate windows).
- **Phase 3 (WhatsApp)**: Meta Business verification process, template message approval, 24-hour response window handling, webhook integration. *Why:* Meta policies changed Jan 2026 (AI bot ban), compliance critical to avoid account ban.
- **Phase 3 (Chat UX)**: Conversational UI patterns, prompt suggestions, fallback to GUI, user testing methodology. *Why:* No competitor does chat-first for social media, unproven UX, needs extensive validation.
**Phases with standard patterns (skip dedicated research-phase):**
- **Phase 1 (OAuth)**: Well-documented Meta Graph API, LinkedIn API, standard OAuth 2.0 flows. Plenty of tutorials and SDKs.
- **Phase 1 (Calendar UI)**: Established pattern (react-big-calendar, FullCalendar), many examples in social media management tools.
- **Phase 2 (Analytics)**: Platform APIs provide engagement data, straightforward integration, standard metrics (likes, comments, shares).
- **Phase 4 (Monitoring)**: Mature ecosystem (Sentry, Axiom, BetterStack), plug-and-play integrations with Next.js.
## Confidence Assessment
| Area | Confidence | Notes |
|------|------------|-------|
| Stack | **HIGH** | All technologies are production-ready with extensive documentation. Next.js 15, React 19, Supabase Cloud, Vercel AI SDK are current stable releases with large communities. |
| Features | **HIGH** | Table stakes features validated across multiple sources (Hootsuite, Buffer, Sprout Social all have similar core). AI as table stakes confirmed by multiple market reports. Differentiators (multi-AI, brand voice) are proven concepts in adjacent markets. |
| Architecture | **HIGH** | Headless architecture, microservices patterns, multi-tenancy, job queues are well-established. Specific recommendations based on authoritative sources (AWS, Azure architecture guides, production case studies). |
| Pitfalls | **MEDIUM-HIGH** | All pitfalls verified with credible sources (Meta API docs, SaaS benchmark reports, industry analysis). Statistics cited where available (96% rate limit reduction, 26% AI content preference, 84% margin erosion). Some metrics are generalized SaaS benchmarks, not micro-SaaS specific. |
**Overall confidence:** **HIGH**
Research is comprehensive, cross-referenced multiple authoritative sources, and grounded in current (2026) reality. Stack choices are based on stable releases with clear migration paths. Feature recommendations balance market expectations with differentiation opportunities. Architecture patterns are proven at scale.
**Caveats:**
- Chat-first UI is **LOW confidence** on execution - unproven UX pattern, needs extensive user testing before committing
- Italian market specifics (WhatsApp priority, localization value) are **MEDIUM confidence** - documented trends but limited micro-SaaS specific data
- AI costs are volatile - pricing changes rapidly, needs continuous monitoring
### Gaps to Address
**Areas needing validation during implementation:**
1. **Chat-first UI acceptance** — Will Italian freelancers embrace conversational interface, or prefer traditional forms? → **Solution:** Build prototype in Phase 3, user test with 10+ freelancers before full rollout. Have GUI fallback ready.
2. **Multi-AI provider actual usage** — Will users switch between GPT/Claude/Gemini, or pick one and stick? → **Solution:** Analytics on provider selection, A/B test default provider, monitor cost savings.
3. **WhatsApp vs Telegram priority** — Is WhatsApp "must have" for Italian market, or "nice to have"? → **Solution:** User interviews during Phase 1-2, survey "Would you use WhatsApp bot?" before building.
4. **Optimal freemium limits** — 5 AI drafts/month is hypothesis. Too generous? Too restrictive? → **Solution:** A/B test in Phase 2 (5 vs 10 vs 3 drafts), monitor conversion rate (target 2-5%), adjust based on data.
5. **Brand voice training data** — How many user-approved posts needed for accurate voice? 10? 50? 100? → **Solution:** ML experimentation in Phase 2, measure quality improvement vs training data size, find optimal threshold.
6. **TikTok demand** — Do freelancers managing LinkedIn/Facebook also need TikTok? Generational divide possible. → **Solution:** Survey during onboarding "Which platforms do you use?", add if >30% want TikTok.
**How to handle:**
- **Phase 1**: Validate with user interviews (chat UX, WhatsApp priority)
- **Phase 2**: A/B test assumptions (freemium limits, brand voice data needs)
- **Phase 3**: Analytics-driven decisions (multi-provider usage, TikTok demand)
- **Throughout**: Maintain flexibility to pivot based on data
## Sources
### Primary (HIGH confidence)
**Stack & Technology:**
- Next.js 15.5 Release Notes (official docs)
- React v19 Release (official docs)
- TypeScript 5.8 Release (Microsoft DevBlogs)
- Supabase Review 2026 (Hackceleration)
- Vercel AI SDK 6.0 (official announcement)
- BullMQ Documentation (official docs)
- Meta Graph API Rate Limits (Elfsight Instagram Graph API Guide 2025)
**Features & Market:**
- 15 Best AI Tools for Social Media Marketing in 2026 (DigitalFirst AI)
- 19 Best Social Media AI Tools For Your Brand in 2026 (Sprout Social)
- 21 Best Social Media Scheduling Tools in 2026 (Sprout Social)
- AI Content Authenticity Crisis 2026 (Digiday) - 26% consumer preference data
- Communication and Social Media Trends in 2026 (Amalia Lopez Acera)
**Architecture:**
- AI-Powered Social Media Management in 2026 (Social News Desk)
- Multi-Provider Generative AI Gateway on AWS (AWS Solutions Library)
- Building Real-Time AI Chat Infrastructure (Render)
- BullMQ - Background Jobs for NodeJS (official docs)
- Architecting Secure Multi-Tenant Data Isolation (Medium)
**Pitfalls:**
- Instagram Graph API Complete Developer Guide for 2025 (Elfsight) - 200 DM/hour limits
- Handling API Rate Limits Gracefully (MarketingSEO)
- AI Infrastructure Cost Optimization (Deloitte) - 84% margin erosion
- Platform Reliability - Why Your Social Media Scheduler Must Be Reliable (Sendible)
- Progressive Onboarding Best Practices (Eleken)
### Secondary (MEDIUM confidence)
**Stack comparisons:**
- Drizzle vs Prisma: Choosing the Right TypeScript ORM (BetterStack)
- Stripe vs Paddle vs Lemon Squeezy Comparison (Medium)
- Zustand vs Redux Toolkit vs Jotai (BetterStack)
- ShadCN UI vs Radix UI vs Tailwind UI (JavaScript Plain English)
**Feature analysis:**
- The Impact of AI on Social Media Content Creation (FeedHive)
- AI Content Generation in 2026: Brand Voice, Strategy and Scaling (Robotic Marketer)
- 7 Social Media Automation Mistakes & How to Fix Them (Obbserv)
- State of PLG in SaaS 2026 (UserGuiding)
**Architecture patterns:**
- Headless CMS: A game-changer for social media (Contentstack)
- AI Agent Orchestration Patterns (Azure Architecture)
- Social Media API Integration Services (Planeks)
- Multi-Tenant Database Architecture Patterns (ByteBase)
**Pitfalls mitigation:**
- Three Freemium Failure Modes (a16z)
- Chatbot UX Failures (AIM Multiple) - 67% failure rate
- WhatsApp Bot vs Telegram Bot (BotPenguin)
- Bias in AI Personalization (arXiv)
### Tertiary (LOW confidence - needs validation)
- Italian SaaS Adoption Barriers (Bonafide Research) - Digital skills gap data
- Italy Digital Economy (trade.gov) - Localization importance
- AI Personalization Challenges (Bloomreach) - Consistency issues
- No More AI Bots in WhatsApp Chats (Global Brands Magazine) - Meta policy Jan 2026
---
**Research completed:** 2026-01-31
**Ready for roadmap:** Yes
**Next steps:** Use this summary as foundation for ROADMAP.md creation. Phase structure is recommended starting point. Adjust based on business priorities and resource constraints.