SongCraft
AI · Lyric Studio

PRD · v1.0

SongCraft — Product Requirements Document

A complete, opinionated spec for rebuilding SongCraft from scratch in any vibe-coding environment (Lovable, Cursor, Anti-Gravity, Bolt, v0, Replit, etc.). Hand this entire document to your AI builder as the source of truth.

React 19
TanStack Start
Tailwind v4
Supabase / Lovable Cloud
Lovable AI Gateway
Suno-aware

1. Vision & Positioning

SongCraft is a privacy-first, AI-augmented lyric studio for independent songwriters and Suno AI musicians. It pairs a distraction-free rich-text writing surface with structured songwriting tools: brief building, song-map planning, Suno-style tag composition, AI co-writing, rhyme/meter analysis, and creative inspiration generators. The product feels like a modern SaaS app (Linear / Notion / Raycast vibes) rather than a paper-and-pen notebook.

Tagline: "AI Lyric Studio for Songwriters & Suno Artists."

Differentiators: (1) songs are private by default with RLS; (2) AI is context-aware of the entire song (brief + lyrics + style); (3) Suno tags are first-class with explanations of what each tag does; (4) writing-first mobile-friendly tab layout; (5) a built-in AI style builder that produces Suno-ready prompts.

2. Users & Personas

  • Indie songwriter — writes lyrics daily, needs rhymes/structure help, exports PDF.
  • Suno power user — composes prompts with structural + style tags, iterates fast.
  • Bedroom producer — pastes external lyrics, rewrites in their voice, generates style.
  • Hobbyist poet — uses Brief + Creative tools to brainstorm.

3. Product Principles

  • Distraction-free first. The Write tab is the hero; everything else collapses.
  • Context-aware AI. Every AI call receives song brief + current lyrics + style.
  • Sparkles everywhere. Any field that can be AI-assisted has a ✨ button.
  • No paper skeuomorphism. Modern SaaS surfaces, semantic tokens, theming.
  • Privacy by default. RLS on every table, no training on user content.
  • Selection is sacred. Selecting lines opens a context menu with AI variants that respect rhythm / theme / mood.

4. Information Architecture

Public site

  • / Landing — hero, features, Suno styles, testimonials, CTA.
  • /pricing, /about, /blog, /contact, /changelog, /roadmap.
  • Legal: /privacy, /terms, /gdpr, /ccpa, /dpa.
  • /prd (this document).

App

  • /auth sign-in / sign-up (email + Google).
  • /studio the writing app (tab-based bottom nav on mobile).
  • /studio/$songId/chat deep-link chat per song.
  • /account profile; /account/billing, /account/keys, /account/privacy.

5. Design System & Themes

  • Tailwind v4 via src/styles.css with semantic CSS variables.
  • Fonts: Fraunces (display), Inter (UI), JetBrains Mono (mono labels).
  • Tokens: --background, --foreground, --primary, --primary-foreground, --accent, --muted, --card, --border, --ring + gradients --gradient-ember and --shadow-glow.
  • Themes (selectable from header settings dropdown): Ember (default), Indigo, Sunset, Mono, Rose Quartz, Ocean Mist, Forest, Slate, Mocha, Neon Nights.
  • Theme bootstrap reads localStorage["sc-theme"] and applies data-theme on <html>.
  • Components are shadcn/ui based; never hardcode color utilities.

6. Studio (core app)

The Studio is a tab-based, bottom-navigation app optimized for writing. Sticky bottom tab bar on mobile (Songs · Write · Craft · Chat); top header is minimal with: song title (multi-line editable), theme/settings, tags toggle, styles dialog, creative dialog, account.

Top header (in writing window)

  • Song-name input (multi-line, doesn't lose focus on each keystroke; tags wrap on next line, not inline).
  • Icons: Tag (toggle inline tags panel), Palette (Creative dialog), Sliders (AI Style Builder dialog), Settings (theme + preferences), Account.

Bottom tabs

  • Songs — list / search / pin / folder, plus "New from paste" workflow.
  • Write — rich text editor + inline Tags toggle.
  • Craft — Brief / Analyze / Co-writer (slimmed; no Tags / Creative / Styles tabs here).
  • Chat — per-song AI conversation history.

7. Write — Editor

  • Rich-text (Tiptap or equivalent) with proper paragraph blocks (<p>), bold/italic/underline, lists, blockquote, headings for section labels.
  • Formatting toolbar (floating or top-of-card) — must look like a real editor, not a textarea.
  • Focus mode hides everything but the canvas.
  • Tag insertion places at cursor with proper paragraph spacing.
  • Word + line + estimated duration counts in the footer.
  • Autosave on debounce (~600 ms) to songs.lyrics_html.
  • PDF export via src/lib/pdf-export.ts.

Selection context menu (right-click on selected lines)

  • "Rewrite (keep rhyme)", "Strengthen imagery", "Make more poetic", "Simplify", "Translate", "Make rhythmic with chorus".
  • AI must consider rhythm, theme, emotion, meaning, mood of the song.
  • Returns 3 variants in a popover; click to replace selection.

8. Tags Panel

Toggled inline below the editor via the header Tag icon (max-h ~42vh). Renders TagsBrowser: sticky search, sticky category chips (Structure, Mood, Instruments, Vocals, Style), info-popover on each tag explaining what it does for Suno / song composition. Clicking inserts the tag at cursor.

9. Craft — Brief / Analyze / Co-writer

Brief

  • Fields: description, emotions, mindset, storyline, references, wordbank, poetry, songmap, composition.
  • Each field has chip pickers (where relevant) and a ✨ AI button that calls brief-field with full song context.

Analyze

  • Detect rhyme scheme, meter consistency, repetition, hook quality, emotional arc.
  • Per-line annotations + summary card.

Co-writer (Chat)

  • Persistent per-song chat (table chat_messages).
  • Knows brief + lyrics; can propose verses, hooks, bridges.

10. Creative Tools

Header Palette icon opens a dialog with card-based generators: Imagery, Hooks, Storyline beats, Title ideas, Metaphors, Cover concept. Each card streams 3-6 results and supports "Insert into lyrics" or "Add to brief".

11. AI Style Builder

Header Sliders icon opens the Styles dialog (styles-panel.tsx). Multi-step builder (Genre → Mood → Tempo → Instruments → Vocal → Production → Era). Each step has a ✨ "AI suggest" button calling style-suggest with the previous answers + song context. Output is a Suno-ready prompt string plus shortlistable presets saved to style_presets. "Apply to song" writes the style to the song record.

12. Songs Manager & Projects

  • List with search, sort (updated/created/title), filter by project/folder, pin.
  • Drag-and-drop reorder (sortable) inside a project.
  • New song: blank · from template · from paste (paste raw lyrics from anywhere — not limited to library songs) · from another song in library.
  • Rewrite-from-song dialog has two modes: library and paste.
  • Soft delete + restore.

13. Templates, Suno presets, Song map

  • src/lib/song-templates.ts exports META_TAGS categories and starter song maps.
  • src/lib/suno-presets.ts exports curated style presets per genre.
  • Song map info component explains each section's purpose.

14. AI Endpoints & Prompts

Single edge function ai-songcraft with a mode discriminator. Backed by Lovable AI Gateway (default model: Gemini 2.5 Flash; allow opt-in GPT/Claude). Always include a system prompt establishing voice, restraint, and Suno conventions.

POST /functions/v1/ai-songcraft
{
  "mode": "brief-field" | "style-suggest" | "rewrite-selection"
        | "creative" | "analyze" | "chat" | "rewrite-from-song",
  "song": { "title", "lyrics_html", "brief", "style", "tags" },
  "field"?: "storyline" | "wordbank" | ...,
  "selection"?: "<plain text>",
  "intent"?: "keep-rhyme" | "more-poetic" | "simplify" | ...,
  "history"?: [{ "role": "user"|"assistant", "content": "..." }]
}
→ streamed text or JSON { variants: string[] }

Prompt rules

  • Never invent facts about the songwriter.
  • Respect existing rhyme scheme & syllable count unless asked otherwise.
  • Reflect declared emotions/mood.
  • Output without markdown unless asked.

15. Selection Context Menu

Implemented via shadcn ContextMenu over the editor. On selection, capture plain text + DOM range; submit to rewrite-selection with the full song context. Render 3 variants in a popover; clicking one replaces the range.

16. Auth & Account

  • Supabase Auth (email + Google). No anonymous; no auto-confirm.
  • /account shows loader while resolving session; never auto-redirects authenticated users to /auth.
  • Profile (name, photo via Google), API keys (BYO model keys), privacy controls (delete account, export data).

17. Plans & Billing

  • Plans in src/lib/plans.ts: Free, Songwriter, Studio.
  • Paddle (global) primary; Razorpay (India) via api.public.razorpay-webhook.ts.
  • Server fn billing.functions.ts for entitlements and portal links.

18. Privacy, Security, RLS

  • Every public table: GRANT + ENABLE RLS + per-user policies via auth.uid().
  • Roles in separate user_roles table with has_role() SECURITY DEFINER.
  • Cookie banner + GDPR/CCPA/DPA pages.
  • AI gateway calls only send the relevant snippet/lyrics; no training retention.

19. Data Model (DB schema)

-- profiles
create table public.profiles (
  id uuid primary key references auth.users(id) on delete cascade,
  display_name text, avatar_url text,
  preferences jsonb default '{}'::jsonb,
  created_at timestamptz default now()
);

-- projects (folders)
create table public.projects (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references auth.users(id) on delete cascade,
  name text not null, color text,
  sort_index int default 0,
  created_at timestamptz default now()
);

-- songs
create table public.songs (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references auth.users(id) on delete cascade,
  project_id uuid references public.projects(id) on delete set null,
  title text not null default 'Untitled',
  lyrics_html text default '',
  brief jsonb default '{}'::jsonb,         -- SongBrief shape
  style jsonb default '{}'::jsonb,         -- Suno style prompt + components
  tags text[] default '{}',
  pinned boolean default false,
  sort_index int default 0,
  deleted_at timestamptz,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- chat_messages (per song)
create table public.chat_messages (
  id uuid primary key default gen_random_uuid(),
  song_id uuid not null references public.songs(id) on delete cascade,
  user_id uuid not null references auth.users(id) on delete cascade,
  role text check (role in ('user','assistant','system')) not null,
  content text not null,
  created_at timestamptz default now()
);

-- style_presets (shortlist)
create table public.style_presets (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references auth.users(id) on delete cascade,
  name text, prompt text, components jsonb,
  created_at timestamptz default now()
);

-- user_roles
create type public.app_role as enum ('admin','moderator','user');
create table public.user_roles (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references auth.users(id) on delete cascade,
  role public.app_role not null,
  unique (user_id, role)
);

-- GRANTS + RLS per table (omitted for brevity — see "public-schema-grants" rule).

20. API & Server Functions

  • src/lib/account.functions.ts — profile read/update, delete account.
  • src/lib/billing.functions.ts — entitlements, portal, webhook reconciliation.
  • Edge fn ai-songcraft — all AI modes (see §14).
  • Public route api/public/razorpay-webhook.ts — signature verified.

21. Tech Stack

  • Frontend: React 19, TanStack Start v1, TanStack Router (file-based), TanStack Query, Vite 7, Tailwind v4, shadcn/ui, lucide-react.
  • Editor: Tiptap (StarterKit + Underline + Placeholder).
  • Backend: Supabase (Postgres + Auth + Edge Functions + Storage).
  • AI: Lovable AI Gateway (Gemini 2.5 Flash default).
  • Payments: Paddle (global), Razorpay (IN).
  • Hosting: Cloudflare Workers (TanStack Start adapter).

22. File / Route Map

src/
  routes/
    __root.tsx                  global nav, ThemeBootstrap, AuthProvider, Toaster, CookieBanner
    index.tsx                   landing
    pricing.tsx about.tsx blog.tsx contact.tsx changelog.tsx roadmap.tsx
    privacy.tsx terms.tsx gdpr.tsx ccpa.tsx dpa.tsx
    prd.tsx                     this document
    auth.tsx                    sign in / sign up
    account.tsx account.billing.tsx account.keys.tsx account.privacy.tsx
    studio.tsx                  tabbed studio (Songs / Write / Craft / Chat)
    studio.$songId.chat.tsx     per-song chat
    api.public.razorpay-webhook.ts
  components/
    settings-menu.tsx (+ ThemeBootstrap)
    lyric-editor.tsx
    song-brief.tsx
    tags-browser.tsx
    creative-tools.tsx
    styles-panel.tsx
    song-analyzer.tsx
    song-map-info.tsx
    projects-manager.tsx
    sortable-song-item.tsx
    cover-panel.tsx
    chip-picker.tsx
    cookie-banner.tsx
    site-footer.tsx
    ui/* (shadcn)
  lib/
    auth-context.tsx theme.ts plans.ts pdf-export.ts
    song-templates.ts suno-presets.ts utils.ts
    account.functions.ts billing.functions.ts
  integrations/supabase/* (client, server, middleware, types)
  styles.css                    Tailwind v4 + theme tokens
supabase/functions/ai-songcraft/index.ts

23. Empty / Error / Loading states

  • Every list has a friendly empty state with a single primary CTA.
  • Every async surface has a skeleton or spinner; never a blank screen.
  • Toasts (sonner) for save / delete / AI errors with retry actions.
  • 404 (NotFoundComponent) uses musical metaphor ("Off the score.").

24. Settings, Themes, Preferences

  • Dropdown from header gear icon: Theme picker (10+), Language, Default new-song template, Default keys (Suno tags), Privacy quick-links, Sign out.
  • Persisted in localStorage and (when logged in) profiles.preferences.

25. Marketing site & SEO

  • Per-route head() with unique title (≤60), description (≤160), og:title/description; og:image only at leaf routes.
  • Single H1 per page; semantic HTML; alt text everywhere.
  • JSON-LD on landing (SoftwareApplication) + pricing (Product/Offer).

26. Success Metrics

  • Activation: % new users who create > 1 song in first session.
  • Engagement: songs/week/user; AI assists/song; Suno tags inserted/song.
  • Retention: W1, W4; PDF exports; chat threads opened.
  • Revenue: trial→paid conversion; Studio plan share.

27. Roadmap & Out-of-scope

  • Planned: collaborator invites, voice memo → transcription → draft, mobile PWA, Suno V4.5 preset pack, multilingual rhyme dictionaries, song version history.
  • Out-of-scope v1: native DAW, audio recording, marketplace, public portfolios.

28. Build Order (rebuild guide)

  • ① Scaffold TanStack Start + Tailwind v4 + shadcn; wire AuthProvider + ThemeBootstrap.
  • ② Supabase: create tables (§19) with GRANTs + RLS; seed roles.
  • ③ Landing + legal + auth + account routes (SEO-ready).
  • ④ /studio shell with bottom tabs (Songs / Write / Craft / Chat) and header icons.
  • ⑤ Lyric editor (Tiptap) with autosave + PDF export.
  • ⑥ Songs manager (list, search, projects, paste-to-new).
  • ⑦ Brief editor with ✨ per-field AI.
  • ⑧ Tags browser (inline toggle + info popovers).
  • ⑨ AI edge function (ai-songcraft) all modes.
  • ⑩ Selection context menu + 3-variant popover.
  • ⑪ Creative dialog + Styles dialog (AI Style Builder).
  • ⑫ Chat tab + per-song history.
  • ⑬ Billing (Paddle + Razorpay webhook) + entitlements.
  • ⑭ Settings menu with 10+ themes & preferences.
  • ⑮ Polish: empty/error states, toasts, analytics, SEO meta on every route.

End of PRD · v1.0 · This document is the single source of truth for rebuilding SongCraft.← Back home