# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Suno Spaces is a digital music collaboration platform inspired by physical music studios. It enables users to listen, create, and jam together in themed, customizable spaces.

**Current Status**: Early prototype stage. The repository contains only architectural documentation (THOUGHTS.md) with no implemented code yet.

## Planned Technical Stack

- **Frontend**: React, TypeScript, Tailwind CSS, Next.js
- **Backend**: Convex (multiplayer backend), Convex Auth (Google OAuth for @suno.com emails only), Modal
- **Deployment**: Vercel (domain: spaces.suno.run)
- **APIs**: Internal Suno APIs for music functionality

## Core Architectural Concepts

### Space Structure

- **Spaces**: Top-level containers (similar to Discord servers) owned by individual users or groups
- **Rooms**: Sub-spaces within each Space (similar to Discord channels), starting as chat interfaces
- **Showcase**: Customizable aesthetic area for each Space (like MySpace/Neocities pages)

### Music Playback

- Each room supports synchronized music playback with optional video/images
- Queue/playlist system for "radio mode" where users passively listen together
- Future: Voice chat overlay during playback

### Orphy Assistant

- AI assistant (named after Orpheus) that can be tagged in messages
- Functions: Song creation, DJ duties, production assistance, room radio control

### Theming System

Design constraint: Spaces, rooms, and showcases must be highly customizable with themes (colors, backgrounds, fonts) that work seamlessly across desktop and mobile.

### Permissioning

- Space ownership model with invite links
- Future: Public and private rooms with allowlists

## Development Approach

This is built for rapid AI-enabled prototyping as an internal tool. Prioritize:

- Modern frontend patterns with React/TypeScript
- Leveraging Convex's native multiplayer capabilities
- Extensible backend architecture suitable for iterative development

## TypeScript Quality Checks

**IMPORTANT**: Always check for TypeScript errors in the Convex backend after making changes:

```bash
npx tsc --noEmit --project convex/tsconfig.json
```

Common patterns for Convex:

- Use `getAuthUserId(ctx)` from `@convex-dev/auth/server` to get current user ID
- Never query users table with `by_token` index - it doesn't exist with Convex Auth
- Always import types from `./_generated/dataModel` for type safety

# important-instruction-reminders

ALWAYS run TypeScript checks on convex folder after making changes: `npx tsc --noEmit --project convex/tsconfig.json`