replit.md

Ai&R System v1.1

Overview

This is an AI-powered music A&R (Artists & Repertoire) analysis tool called "The Ai&R System." It uses a Dual-Model Orchestration pipeline with a Two-Stage Workflow:

Stage 1 ("The Breach"): Gemini Flash extracts Sonic DNA (quantitative audio features, X-Factor keywords, primary reference artist, technical profiles) → Groq generates Suno v4 style tags and 3 suggested song titles. No lyrics generated at this stage.

Stage 2 ("The Synthesis"): User selects a title → Groq generates full anti-cringe lyrics (24+ lines) with reference artist vocal branding and X-Factor metatag injection. If Groq fails, Gemini handles everything as a fallback.

The app is a full-stack TypeScript monorepo with a React frontend and Express backend, backed by PostgreSQL for storing analysis history. Apple-style minimalist black UI with action-first layout (Copy Suno Prompt, Copy Lyrics, Go to Suno buttons at top).

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Monorepo Structure

• client/ — React SPA (Vite + TypeScript)
• server/ — Express API server (TypeScript, runs via tsx)
• shared/ — Shared types, schemas, and route definitions used by both client and server
• migrations/ — Drizzle-generated database migrations
• attached_assets/ — Reference documents (prompt engineering specs, UI mockups)

Frontend Architecture

• Framework: React 18 with TypeScript, bundled by Vite
• Routing: Wouter (lightweight client-side router)
• State/Data Fetching: TanStack React Query for server state management
• UI Components: shadcn/ui (new-york style) built on Radix UI primitives with Tailwind CSS
• Animations: Framer Motion for reveal effects and log animations
• Icons: Lucide React
• Styling: Tailwind CSS with CSS variables for theming. Dark-only monochromatic theme (pure black background, white text, green accents). Uses three font families: Inter (sans), Newsreader (serif), Geist Mono (monospace).
• Key Pages: Home page (/) is the main analysis interface; Pricing page (/pricing); Help page (/help); 404 page for unknown routes
• Path Aliases: @/ maps to client/src/, @shared/ maps to shared/

Backend Architecture

• Framework: Express.js on Node.js with TypeScript
• API Pattern: Routes defined in shared/routes.ts as a typed contract (method, path, input/output schemas via Zod). Both client and server reference the same route definitions.
• AI Integration: Dual-Model Orchestration with efficient fallback
  • Gemini Flash (Analyst): Extracts raw Music Observation via @google/genai, accessed through Replit AI Integrations (AI_INTEGRATIONS_GEMINI_API_KEY and AI_INTEGRATIONS_GEMINI_BASE_URL)
  • Groq Llama-3.3-70b (Architect & Poet): Stage 1 generates Suno tags and 3 suggested titles. Stage 2 generates full lyrics for a selected title. Uses groq-sdk (GROQ_API_KEY env var)
  • Fallback: If Groq fails, Gemini Architect Fallback reuses existing Gemini observation data (no re-call). If no Groq API key, Gemini Unified mode handles everything.
  • Spotify Integration (server/spotify.ts): Searches Spotify for artist/track, retrieves audio features (if API allows), artist genres, popularity, album art. Real audio features override Gemini estimates for Deep Scan. Connected via Replit Connector.
  • Helpers: safeParseJson() centralized JSON parsing, generateWithGroq()/generateWithGemini() shared AI wrappers, validateArchitectOutput() post-parse validation, trimForResponse() strips non-UI fields from API response (full data stored in DB), enrichWithSpotify() merges Spotify data into sonicDna
• Dev Server: Vite dev server is used as middleware in development (HMR via server/vite.ts); static files served in production from dist/public
• Build: Custom build script (script/build.ts) — Vite builds the client, esbuild bundles the server into dist/index.cjs

API Endpoints

• POST /api/analyze — Stage 1 endpoint. Accepts targetArtist (required). Runs dual-model pipeline: Gemini extracts Sonic DNA → Groq generates Suno tags and 3 suggested titles. Returns structured JSON with sonicDna (tags, suggestedTitles, audioFeatures, highImpactKeywords, primaryReferenceArtist) and pipeline indicator. Response includes pipeline field: "dual", "gemini-fallback", or "gemini-only". Note: Suno tags do NOT include artist names.
• POST /api/generate-lyrics — Stage 2 endpoint. Accepts selectedTitle (string) and sonicDna (full sonic DNA from Stage 1). Generates full anti-cringe lyrics (24+ lines) with reference artist vocal branding. Returns { sunoScript: string }.
• GET /api/history — Returns all past analysis results ordered by creation date (newest first)

Replit AI Integrations (Pre-built Modules)

Located in server/replit_integrations/:

• chat/ — Generic chat conversation routes with Gemini (conversations + messages CRUD)
• image/ — Image generation endpoint using gemini-2.5-flash-image
• batch/ — Batch processing utilities with rate limiting, retries, and concurrency control

These are supplementary modules. The main analysis feature uses Gemini directly in server/routes.ts.

Database

• Database: PostgreSQL (required, via DATABASE_URL environment variable)
• ORM: Drizzle ORM with drizzle-zod for schema-to-validation integration
• Schema (shared/schema.ts):
  • analysis_results table: id (serial PK), target_artist (text), reference_artist (text), sonic_dna (jsonb — stores tags, BPM, key, instruments, etc.), narrative (text), created_at (timestamp)
• Additional schemas (shared/models/chat.ts):
  • conversations table: id, title, created_at
  • messages table: id, conversation_id (FK to conversations), role, content, created_at
• Migrations: Use npm run db:push (drizzle-kit push) to sync schema to database
• Storage Layer: server/storage.ts — DatabaseStorage class implements IStorage interface with createAnalysis() and getHistory() methods

Key Design Decisions

1. Shared route contracts — Route definitions with Zod schemas in shared/routes.ts ensure type safety across client-server boundary
2. JSONB for Sonic DNA — The analysis output from Gemini is complex nested JSON; storing as JSONB allows flexible querying without rigid column structure
3. Gemini JSON cleaning — The backend strips markdown code blocks (```json) from both Gemini and Groq responses before parsing
4. Dual-Model Orchestration — Gemini as Analyst (data extraction) + Groq as Architect (creative generation) with automatic fallback
5. Interscope Deep Scan — 5 circular audio feature gauges (Energy, Valence, Acousticness, Danceability, Instrumentalness) scored 0.0-1.0. Uses Spotify real data when available (with green "Live" badge), falls back to Gemini estimation
6. Replit Auth — Google login via Replit OpenID Connect (passport-based). Users table has credits, freeUsesRemaining, totalAnalyses columns. Freemium model: 3 free analyses, then 10 credits per analysis. Auth middleware on /api/analyze. Credits endpoint at GET /api/credits.

External Dependencies

Required Services

• PostgreSQL Database — Connection string via DATABASE_URL environment variable. Required for all data persistence.
• Google Gemini AI (via Replit AI Integrations) — Two environment variables required:
  • AI_INTEGRATIONS_GEMINI_API_KEY — API key for Gemini
  • AI_INTEGRATIONS_GEMINI_BASE_URL — Base URL for the Gemini-compatible endpoint
  • Model used: gemini-2.5-flash (Analyst role)
• Groq AI — Environment variable required:
  • GROQ_API_KEY — API key for Groq
  • Model used: llama-3.3-70b-versatile (Architect & Poet role)

Key NPM Dependencies

• @google/genai — Google Gemini AI client
• groq-sdk — Groq AI client (Llama 3.3 70B)
• drizzle-orm + drizzle-kit + drizzle-zod — Database ORM and migration tooling
• express + connect-pg-simple — HTTP server and session store
• @tanstack/react-query — Client-side data fetching
• framer-motion — UI animations
• wouter — Client-side routing
• zod — Schema validation (shared between client and server)
• shadcn/ui ecosystem — Radix UI primitives, Tailwind CSS, class-variance-authority, clsx, tailwind-merge