🚀 SocialFlow: Premium YouTube & Instagram Automation SaaS

SocialFlow is a high-performance SaaS platform built for professional creators. It streamlines content management through automated metadata synchronization, multi-platform publishing (YouTube & Instagram), quota-shielded channel intelligence, and AI-driven workflows, all wrapped in a state-of-the-art "Liquid Glass" design system.

---

✨ Core Features

• 🛡️ Quota-Shielded Analytics: Intelligent server-side caching (Turbo/Soft/Passive tiers) to protect API limits while providing 7/28/90-day insights.
• 📸 Multi-Platform Publishing: Direct YouTube integrations and advanced Instagram Reels publishing via tunnel-based media handoffs and dynamic n8n polling loops.
• 💎 Liquid Glass UI: A premium, theme-aware design system featuring 24px backdrop blurs and satin surfaces for an elite user experience.
• 🤖 n8n Automation Engine: Background circuits for real-time status syncing, metadata forging, long-form video polling, and automated cross-platform deletion.
• 🎬 Content Hub: Centralized dashboard for managing drafts, High-Fidelity resolution tracking (SD/HD/4K/8K), and promoting videos seamlessly.
• ✨ Ai Smart Engine: Google Generative AI integration for crafting perfect multi-platform metadata instantly.
• ✉️ Secure Support Matrix: Zero-backend Formspree integration for secure, real-time priority support tickets directly from the dashboard and landing page.
• 👤 Identity Sync: Dual-track identity management separating Google account data from personalized brand display names.

---

🛠️ Tech Stack & Dependencies

Core Frameworks

• Framework: Next.js 16.2 (App Router & Server Actions)
• Language: TypeScript 5
• Styling: Vanilla CSS (Liquid Glass System)
• Icons: Lucide React 1.14
• Charts: Recharts 3.8

Backend & Database

• Database: PostgreSQL 8.20
• ORM: Prisma Client 5.21
• Authentication: NextAuth.js 4.24 (Google OAuth 2.0)
• APIs: Googleapis 171.4, Google Generative AI 0.24

Automation Infrastructure

• Workflow Engine: n8n (Self-hosted via Docker)
• Tunnels: Cloudflare (cloudflared)

---

📁 Project Structure & Directory Breakdown

socialflow/
├── prisma/                  # Database schema (schema.prisma) and migrations
├── public/
│   └── workflows/           # n8n Automation circuit JSON exports
├── src/
│   ├── app/
│   │   ├── actions/         # Server Actions (YouTube/Instagram API, Settings)
│   │   ├── api/             # REST API routes (OAuth, Webhooks, Sync Status)
│   │   ├── auth/            # Authentication Pages
│   │   ├── dashboard/       # Core SaaS Views (Overview, Posts, Ai Smart Engine, Analytics, Settings)
│   │   └── globals.css      # Liquid Glass design system tokens & global styles
│   ├── components/          # Reusable UI (Dashboard Greeting, AI Forecast Cards, Auth)
│   └── lib/                 # Core utilities (NextAuth config, Prisma Client, upload cache)
├── docker-compose.yml       # n8n infrastructure containerization
└── package.json             # Core project dependencies & scripts

---

🚀 Setup & Installation

1. Environment Configuration

Create a .env file in the root directory:

# ─── Database ───────────────────────────────────────────────
DATABASE_URL="postgresql://user:password@localhost:5432/socialflow_db?schema=public"

# ─── NextAuth ───────────────────────────────────────────────
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-random-secret-here"   # generate with: openssl rand -base64 32

# ─── Google OAuth (YouTube API) ─────────────────────────────
# Create credentials at https://console.cloud.google.com/
# Required scopes: youtube.force-ssl, userinfo.profile, userinfo.email
GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="GOCSPX-your-google-client-secret"

# ─── Google Gemini AI (Ai Smart Engine) ─────────────────────
# Get your key at https://aistudio.google.com/app/apikey
GOOGLE_GEMINI_API_KEY="AIzaSy-your-gemini-api-key"

# ─── Meta / Facebook (Instagram) ────────────────────────────
# Create an app at https://developers.facebook.com/
# Required permissions: instagram_basic, instagram_content_publish, pages_read_engagement
FACEBOOK_CLIENT_ID="your-facebook-app-id"
FACEBOOK_CLIENT_SECRET="your-facebook-app-secret"

# ─── n8n Automation Webhooks ─────────────────────────────────
# Use 'webhook-test' path while testing in n8n editor
# Use 'webhook' path after activating the workflow
N8N_WEBHOOK_URL="http://localhost:5678/webhook/socialflow-ai-generate"
N8N_SCHEDULE_WEBHOOK_URL="http://localhost:5678/webhook/socialflow-scheduler"
N8N_STATUS_UPDATE_WEBHOOK_URL="http://localhost:5678/webhook/socialflow-status-update"
NEXT_PUBLIC_N8N_DELETE_WEBHOOK_URL="http://localhost:5678/webhook/socialflow-delete"
N8N_INSTAGRAM_WEBHOOK_URL="http://localhost:5678/webhook/instagram-publish"

# ─── Cloudflare Tunnel ──────────────────────────────────────
# Run: cloudflared tunnel --url http://localhost:3000
# Copy the generated *.trycloudflare.com URL here
PUBLIC_TUNNEL_URL="https://your-tunnel-id.trycloudflare.com"

2. Install Dependencies

npm install

3. Initialize Database

Push the Prisma schema to your PostgreSQL database:

npx prisma db push

(Optional) To launch Prisma Studio for DB management:

npx prisma studio

4. Setup Infrastructure (n8n & Tunnels)

Start the n8n automation engine:

docker-compose up -d

Expose your local environment via Cloudflare Tunnel (required for Instagram media handoff):

cloudflared tunnel --url http://localhost:3000

Note: Copy the generated .trycloudflare.com URL into your .env as PUBLIC_TUNNEL_URL.

5. Launch Platform

Start the Next.js development server:

npm run dev

---

📄 Documentation

For a deeper dive into the architectural blueprints, database models, and automation circuits, see:

• Project - SocialFlow.md

---

Built with passion for the creator economy.