sunoflow

SunoFlow

A mobile-first web app for managing and generating music with the Suno API. Features AI music generation, playlist management, lyrics editing, audio waveform playback, and a public sharing system.

Features

• Mobile-responsive layout with bottom navigation and swipe gestures
• User registration and login (email/password + Google OAuth)
• Email verification, password reset, and notification system
• AI music generation via Suno API with a generation queue and progress tracking
• Song library with favorites, playlists, history, and discovery
• Audio waveform player, mashup studio, and audio upload
• Lyrics and prompt templates with LLM-powered generation
• Public song/playlist sharing via shareable slugs (/s/[slug], /p/[slug])
• Persona manager and style boost
• Admin dashboard: users, analytics, logs, error reports
• Swagger API docs at /api/docs
• Sentry error tracking, Pino structured logging, rate limiting

Tech Stack

Layer	Technology
Framework	Next.js 15 (App Router)
Language	TypeScript
Styling	Tailwind CSS
Auth	NextAuth.js v5 + Prisma adapter
ORM	Prisma v5
Database	PostgreSQL 16
Email	Mailjet (falls back to console log)
LLM	OpenAI API (gpt-4o-mini)
Music API	sunoapi.org
Monitoring	Sentry
Logging	Pino
Testing	Vitest (unit) + Playwright (E2E)
Package manager	pnpm

Quick Start

Prerequisites

• Node.js 20+
• pnpm (npm install -g pnpm)
• PostgreSQL 16 (or use the Docker Compose stack below)

1. Clone and install

git clone https://github.com/lx-0/SunoFlow.git
cd SunoFlow
pnpm install

2. Configure environment

cp .env.example .env

Edit .env — the minimum required vars are:

SUNOFLOW_DATABASE_URL="[REDACTED:DB Connection String]
DATABASE_URL="[REDACTED:DB Connection String]
AUTH_SECRET="<generate with: npx auth secret>"
AUTH_URL="http://localhost:3000"

See Environment Variables for the full reference.

3. Run the database and apply migrations

# Option A: use Docker Compose to spin up Postgres
docker compose up db -d

# Option B: use an existing Postgres instance — skip the above

pnpm exec prisma migrate deploy

4. Start the development server

pnpm dev

Open http://localhost:3000. You will be redirected to /login. Click Create one to register.

---

Environment Variables

Copy .env.example to .env and fill in the values. All variables are documented inline in .env.example.

Variable	Required	Description
SUNOFLOW_DATABASE_URL	Yes	Postgres connection URL (used by Prisma schema)
DATABASE_URL	Yes	Postgres connection URL (used by Next.js env validation)
AUTH_SECRET	Yes	Random secret for NextAuth — generate with npx auth secret
AUTH_URL	Yes	Public base URL of the app (e.g. http://localhost:3000)
SUNOAPI_KEY	No	API key from sunoapi.org for music generation
OPENAI_API_KEY	No	OpenAI API key for LLM features (lyrics, prompts)
OPENAI_MODEL	No	OpenAI model override (default: gpt-4o-mini)
MAILJET_API_KEY	No	Mailjet API key for transactional email
MAILJET_SECRET_KEY	No	Mailjet secret key
EMAIL_FROM	No	Sender address for transactional email
AUTH_GOOGLE_ID	No	Google OAuth client ID
AUTH_GOOGLE_SECRET	No	Google OAuth client secret
NEXT_PUBLIC_SITE_URL	No	Public-facing URL for OG tags and sitemaps
ALLOWED_ORIGINS	No	Comma-separated allowed CORS origins
RATE_LIMIT_MAX_GENERATIONS	No	Max AI generation requests per user per window (default: 10)
LOG_LEVEL	No	Pino log level: trace|debug|info|warn|error|fatal (default: info)
LOG_PRETTY	No	Pretty-print logs in dev (true/false)
SENTRY_DSN	No	Sentry DSN for server-side error tracking
NEXT_PUBLIC_SENTRY_DSN	No	Sentry DSN for client-side error tracking
SENTRY_AUTH_TOKEN	No	Sentry auth token for source map uploads during build
SENTRY_ORG	No	Sentry organisation slug
SENTRY_PROJECT	No	Sentry project slug
STRIPE_SECRET_KEY	No	Stripe secret key (sk_test_… / sk_live_…)
STRIPE_PUBLISHABLE_KEY	No	Stripe publishable key (pk_test_… / pk_live_…)
STRIPE_WEBHOOK_SECRET	No	Stripe webhook signing secret (whsec_…) — required for /api/webhooks/stripe
STRIPE_PRICE_STARTER	No	Stripe Price ID for the Starter plan ($9.99/mo)
STRIPE_PRICE_PRO	No	Stripe Price ID for the Pro plan ($24.99/mo)
STRIPE_PRICE_STUDIO	No	Stripe Price ID for the Studio plan ($49.99/mo)