leopost/.planning/ROADMAP.md

# Roadmap: Leopost

## Overview

Leopost viene costruito in 10 fasi incrementali che portano da zero a un micro-SaaS AI-first funzionante. Iniziamo con fondamenta solide (auth, database, multi-tenancy), aggiungiamo integrazione social e AI, implementiamo scheduling affidabile con job queue, poi concludiamo con funzionalità avanzate (AI learning, messaging bots). Ogni fase consegna capacità verificabili dall'utente, nessun lavoro speculativo.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [ ] **Phase 1: Foundation & Auth** - User accounts, plans, multi-tenant database
- [ ] **Phase 2: Social Platform Integration** - Facebook OAuth, Graph API setup
- [ ] **Phase 3: Onboarding & Context** - Brand context capture, persistent memory
- [ ] **Phase 4: AI Chat Interface** - Chat UI, multi-model support, conversation management
- [ ] **Phase 5: Content Generation** - AI text and image generation
- [ ] **Phase 6: Scheduling Foundation** - Post scheduling, reliable publishing with job queue
- [ ] **Phase 7: Automation & Calendar** - Automation levels, visual calendar
- [ ] **Phase 8: AI Learning** - AI learns user preferences from feedback
- [ ] **Phase 9: Editorial Planning** - AI creates editorial calendar
- [ ] **Phase 10: Messaging Integration** - Telegram and WhatsApp bot commands

## Phase Details

### Phase 1: Foundation & Auth
**Goal**: Users can create accounts, log in, and subscribe to plans in a secure multi-tenant environment
**Depends on**: Nothing (first phase)
**Requirements**: AUTH-01, AUTH-02, AUTH-03
**Success Criteria** (what must be TRUE):
  1. User can register with email/password and receive confirmation email
  2. User can log in with Google OAuth and stay authenticated across sessions
  3. User can view and switch between Free, Creator, and Pro plans
  4. System enforces plan-specific limits (configured in database, enforced in API)
  5. All data is isolated per tenant (RLS active, no cross-tenant leakage)
**Plans**: 6 plans in 4 waves

Plans:
- [ ] 01-01-PLAN.md — Project setup (Next.js + Supabase clients)
- [ ] 01-02-PLAN.md — Database schema (plans, profiles, RLS)
- [ ] 01-03-PLAN.md — Email/password auth flow
- [ ] 01-04-PLAN.md — Google OAuth integration
- [ ] 01-05-PLAN.md — Middleware & route protection
- [ ] 01-06-PLAN.md — Subscription management UI

### Phase 2: Social Platform Integration
**Goal**: Users can securely connect their Facebook account for publishing
**Depends on**: Phase 1
**Requirements**: AUTH-04
**Success Criteria** (what must be TRUE):
  1. User can click "Connect Facebook" and complete OAuth flow
  2. Facebook access token is stored securely with automatic refresh
  3. User can view connected Facebook pages and select target page
  4. System handles token expiration gracefully (refresh before publish)
  5. API rate limits are monitored and logged (dashboard shows remaining quota)
**Plans**: 6 plans in 4 waves

Plans:

### Phase 3: Onboarding & Context
**Goal**: New users provide brand context that AI uses for personalized content
**Depends on**: Phase 1
**Requirements**: ONBR-01, ONBR-02
**Success Criteria** (what must be TRUE):
  1. New user sees progressive onboarding wizard (not overwhelming)
  2. User provides business name, sector, and description in < 2 minutes
  3. Brand context persists in database and loads in future sessions
  4. User can update brand info anytime via settings page
  5. AI prompts automatically inject brand context (verified in logs)
**Plans**: 6 plans in 4 waves

Plans:

### Phase 4: AI Chat Interface
**Goal**: Users interact with AI assistant to create content via natural conversation
**Depends on**: Phase 3
**Requirements**: CHAT-01, CHAT-02, CHAT-03
**Success Criteria** (what must be TRUE):
  1. User sees chat interface as main screen (not buried in tabs)
  2. User can send message and receive AI response in < 5 seconds
  3. User can choose AI model (GPT, Claude, Gemini) in settings
  4. AI suggests 3-5 initial actions after onboarding (e.g., "Create first post")
  5. Conversation history persists (user can scroll back, AI remembers context)
**Plans**: 6 plans in 4 waves

Plans:

### Phase 5: Content Generation
**Goal**: AI generates quality text posts and images adapted to brand voice
**Depends on**: Phase 4
**Requirements**: CONT-01, CONT-02
**Success Criteria** (what must be TRUE):
  1. User asks "Create post about [topic]" and receives text draft in < 10 seconds
  2. Generated post uses brand context (tone, sector, target audience)
  3. User asks "Add image" and receives AI-generated image in < 30 seconds
  4. User can regenerate content with feedback ("Make it more casual")
  5. Generated content displays in chat with edit capability
**Plans**: 6 plans in 4 waves

Plans:

### Phase 6: Scheduling Foundation
**Goal**: Users reliably schedule posts and they publish automatically at specified time
**Depends on**: Phase 2, Phase 5
**Requirements**: SCHD-01, SCHD-02
**Success Criteria** (what must be TRUE):
  1. User can set date/time for post and it saves to queue
  2. Post publishes to Facebook automatically at scheduled time (99%+ reliability)
  3. User receives notification when post is published (or if it fails)
  4. Job queue handles retries with exponential backoff (API failures don't lose posts)
  5. Timezone is handled correctly (user sees local time, system schedules in UTC)
**Plans**: 6 plans in 4 waves

Plans:

### Phase 7: Automation & Calendar
**Goal**: Users configure automation level and visualize scheduled posts in calendar
**Depends on**: Phase 6
**Requirements**: SCHD-03, SCHD-04
**Success Criteria** (what must be TRUE):
  1. User can set automation level (Approval → Semi-Auto → Autopilot)
  2. In Approval mode, AI generates drafts and user must manually approve
  3. In Autopilot mode, AI generates and publishes without user action
  4. Calendar view shows all scheduled posts (color-coded by platform)
  5. User can drag-and-drop posts to reschedule in calendar
**Plans**: 6 plans in 4 waves

Plans:

### Phase 8: AI Learning
**Goal**: AI improves content quality over time by learning user's authentic voice
**Depends on**: Phase 7
**Requirements**: CHAT-04
**Success Criteria** (what must be TRUE):
  1. User can give thumbs up/down feedback on generated content
  2. AI analyzes approved posts to identify tone, vocabulary, structure patterns
  3. Future posts incorporate learned preferences (measurably more "on brand")
  4. User sees improvement notification ("AI learned from 10 approved posts")
  5. Learning data is per-tenant (AI doesn't leak patterns across users)
**Plans**: 6 plans in 4 waves

Plans:

### Phase 9: Editorial Planning
**Goal**: AI proactively creates multi-week content calendar aligned to business goals
**Depends on**: Phase 8
**Requirements**: CONT-03
**Success Criteria** (what must be TRUE):
  1. User asks "Create 2-week plan" and AI generates calendar with 10-14 post ideas
  2. Editorial plan includes diverse content types (educational, promotional, engagement)
  3. User can accept entire plan or edit individual posts
  4. Accepted plan populates calendar with draft posts (ready to review/publish)
  5. AI considers business context (sector trends, user's past successful posts)
**Plans**: 6 plans in 4 waves

Plans:

### Phase 10: Messaging Integration
**Goal**: Users can create and schedule posts via Telegram or WhatsApp commands
**Depends on**: Phase 6
**Requirements**: MSGN-01, MSGN-02
**Success Criteria** (what must be TRUE):
  1. User connects Telegram bot and can send "/create [topic]" to generate post
  2. Telegram bot responds with draft post and options (edit, schedule, publish now)
  3. User connects WhatsApp bot (Business API verified) with same functionality
  4. Both bots support voice messages (transcribed to text, processed by AI)
  5. Posts created via messaging appear in web calendar (sync across channels)
**Plans**: 6 plans in 4 waves

Plans:

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation & Auth | 0/6 | Planned | - |
| 2. Social Platform Integration | 0/TBD | Not started | - |
| 3. Onboarding & Context | 0/TBD | Not started | - |
| 4. AI Chat Interface | 0/TBD | Not started | - |
| 5. Content Generation | 0/TBD | Not started | - |
| 6. Scheduling Foundation | 0/TBD | Not started | - |
| 7. Automation & Calendar | 0/TBD | Not started | - |
| 8. AI Learning | 0/TBD | Not started | - |
| 9. Editorial Planning | 0/TBD | Not started | - |
| 10. Messaging Integration | 0/TBD | Not started | - |