00-project-overview

Instruction file imported from FindMalek/sonaraem (.cursor/rules/00-project-overview.mdc). Copyright stays with the author.

Project Overview

What is Sonaraem

Sonaraem is an AI-powered music organization app. It syncs a user's Spotify library, classifies tracks with LLMs, clusters them by embedding similarity, and auto-generates playlists. It is a pnpm + Turborepo monorepo with four Next.js (App Router) apps and shared packages.

Monorepo Structure

Applications

• apps/api (api): Next.js API server (port 3002) — oRPC, Better Auth (dashboard + admin), Trigger.dev webhook
• apps/dashboard (dashboard): Next.js user dashboard (port 3003) — Spotify OAuth, waitlist-gated
• apps/web (web): Next.js web app (port 3001) — public waitlist signup
• apps/admin (admin): Internal admin dashboard (port 3004) — email/password, waitlist approval

Packages

• packages/auth: Better Auth factories — separate dashboard (Spotify) and admin (email/password) instances
• packages/common: Shared schemas, types, services, Trigger.dev task definitions
• packages/config: Shared tsconfig.base.json
• packages/core: Initialises DB + dashboardAuth / adminAuth; re-exports auth as dashboard alias
• packages/db: Drizzle ORM schema + migrations + DB client
• packages/env: Zod-validated env presets (never use process.env directly)
• packages/logger: Pino structured logger
• packages/orpc: oRPC routers, procedures, context, and client
• packages/tracing: OpenTelemetry instrumentation
• packages/ui: shadcn/ui component library + shared Tailwind config
• packages/email: React Email templates + Resend send layer (@sonaraem/email)

Hard Rules

1. Never process.env directly. Use import { env } from "@sonaraem/env/server".
2. Never construct an LLM provider client directly outside @sonaraem/ai-provider. Consumers use getAIModel(task) from @sonaraem/ai-provider — it resolves the model for that task's fixed assigned provider (TASK_PROVIDER in packages/ai-provider/src/models.ts; each task is pinned to one of groq | concentrate, not a global runtime switch). @sonaraem/ai-provider itself is the one place that's allowed to call createGroq/createOpenAI.
3. Never inngest. Background jobs use @trigger.dev/sdk only.
4. All env vars prefixed SONARAEM_ or NEXT_PUBLIC_SONARAEM_.
5. JSONB progress writes: use updateStageProgress(runId, stage, val). Never overwrite the full column in concurrent code.
6. DB driver is conditional. .neon.tech URL → @neondatabase/serverless, otherwise → pg. Do not change this logic.

Git commits

Use conventional prefixes: feat: fix: chore: perf: refactor: (scope optional).

Do not name AI assistants, IDEs, or vendor coding tools in commit messages, PR titles, or PR bodies (e.g. Claude, Cursor, Copilot, ChatGPT, Windsurf). Write commits as a human contributor would. Do not add Co-authored-by: lines for tools.