leopost/.planning/research/STACK.md

# 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.