# Suno Spaces

Digital music collaboration platform - Early prototype (Phase 001: Skeleton)

## Overview

Suno Spaces is a collaborative platform for music creation and sharing. This is the initial skeleton implementation with basic authentication and project structure.

## Tech Stack

- **Frontend**: Next.js 15+ (App Router), React 19, TypeScript, Tailwind CSS
- **Backend**: Convex (multiplayer backend with real-time capabilities)
- **Auth**: Convex Auth with Google OAuth (@suno.com emails only)
- **Deployment**: Vercel

## Current Status (Phase 001)

**Implemented:**
- ✅ Next.js with TypeScript and Tailwind CSS
- ✅ Convex backend with minimal schema (Users, Spaces, Rooms)
- ✅ Google OAuth authentication restricted to @suno.com
- ✅ Landing page with sign-in
- ✅ Basic authenticated dashboard
- ✅ Placeholder space view
- ✅ Basic routing structure

**Not Yet Implemented (Phase 002):**
- Home space auto-creation
- Room creation and management
- Real-time presence tracking
- Message/chat system
- Atoms (creative assets)
- Invite links
- Member management
- Showcase area

## Prerequisites

- Node.js 18+
- npm
- Convex account (free tier works)
- Google Cloud OAuth credentials
- @suno.com email address for testing

## Setup Instructions

### 1. Install Dependencies

```bash
npm install
```

### 2. Convex Setup

The Convex project should already be initialized. If starting fresh:

```bash
npx convex dev
```

This will:
- Create a Convex deployment
- Generate the `.env.local` file with `CONVEX_DEPLOYMENT` and `NEXT_PUBLIC_CONVEX_URL`
- Push the schema and functions
- Enable HTTP actions for OAuth

### 3. Google OAuth Setup

**Quick Setup:** See [AUTH_SETUP.md](./AUTH_SETUP.md) for detailed step-by-step instructions.

**Summary:**

1. Find your callback URL from `.env.local`:
   - Look for `NEXT_PUBLIC_CONVEX_URL`
   - Callback URL = `[NEXT_PUBLIC_CONVEX_URL]/api/auth/callback/google`
   - Example: `https://accomplished-bass-647.convex.cloud/api/auth/callback/google`

2. Create OAuth credentials in [Google Cloud Console](https://console.cloud.google.com):
   - OAuth consent screen: Internal (for Suno workspace)
   - OAuth client type: Web application
   - Add your callback URL to Authorized redirect URIs

3. Set environment variables in Convex:
   ```bash
   npx convex env set AUTH_GOOGLE_ID your_client_id_here
   npx convex env set AUTH_GOOGLE_SECRET your_client_secret_here
   npx convex env set SITE_URL "http://localhost:3000"
   ```

**Important:**
- Use `AUTH_GOOGLE_ID` and `AUTH_GOOGLE_SECRET` (not CLIENT_ID/CLIENT_SECRET)
- `SITE_URL` is required (use `http://localhost:3000` for dev, `https://spaces.suno.run` for production)

### 4. Suno API Setup (for song generation)

Set these environment variables in your Convex dashboard:

```bash
npx convex env set SUNO_BASE_URL "https://studio-api.suno.ai"
npx convex env set SUNO_SESSION_TOKEN "your_session_token_here"
```

See `lib/README.md` for details on using the Suno API client.

### 5. Run Development Server

Start Convex (in one terminal):

```bash
npx convex dev
```

Start Next.js (in another terminal):

```bash
npm run dev
```

Visit `http://localhost:3000`

## Project Structure

```
/app                        # Next.js app router
  /page.tsx                 # Landing page with auth
  /dashboard/page.tsx       # User dashboard (spaces list)
  /space/[id]/page.tsx      # Individual space view
  /layout.tsx               # Root layout with Convex provider
  /globals.css              # Global styles with Tailwind
/components
  /ConvexClientProvider.tsx # Convex client wrapper
  /ui                       # Shared UI components (empty for now)
  /auth                     # Auth components (empty for now)
/convex                     # Convex backend
  /schema.ts                # Database schema
  /auth.ts                  # Auth configuration
  /http.ts                  # HTTP routes for OAuth
  /users.ts                 # User queries/mutations
  /spaces.ts                # Space queries/mutations
  /_generated/              # Auto-generated by Convex
/lib                        # External API clients and utilities
  /sunoClient.ts            # Suno API client for song generation
  /README.md                # Documentation for lib utilities
/public                     # Static assets
```

## Available Scripts

```bash
npm run dev        # Start Next.js dev server
npm run build      # Build for production
npm start          # Start production server
npm run lint       # Run ESLint
```

For Convex:

```bash
npx convex dev     # Run Convex in development mode
npx convex deploy  # Deploy Convex to production
```

## Testing Authentication

1. Start both `npx convex dev` and `npm run dev`
2. Visit `http://localhost:3000`
3. Click "Sign in with Google"
4. Use a @suno.com email address
5. You should be redirected to `/dashboard`
6. Dashboard will show "You don't have any spaces yet"

## Schema

### Users (from authTables)
- Managed by Convex Auth
- Fields: `email`, `emailVerified`, `name`, `image`, etc.
- Includes all necessary indexes for auth

### Spaces
- `name`, `ownerId` (ref to users), `metadata`

### Rooms
- `spaceId` (ref to spaces), `name`, `type`

Plus additional auth tables (sessions, accounts, etc.) from Convex Auth.

## Deployment (Vercel)

1. Push code to GitHub
2. Import project to Vercel
3. Add environment variables in Vercel dashboard:
   - `CONVEX_DEPLOYMENT` (use production deployment from Convex)
   - `NEXT_PUBLIC_CONVEX_URL`
4. Deploy to production
5. Configure custom domain `spaces.suno.run` in Vercel settings
6. Update Google OAuth redirect URIs with production URL

## Next Steps (Phase 002)

See `plans/002_core_features.md` for the full feature implementation plan:
- Auto-create home space on first sign-in
- Full schema (SpaceMembers, Invites, Messages, Atoms, Presence)
- Space/room CRUD operations
- Real-time presence tracking
- Message system with reactions and mentions
- Atoms (creative assets) with async creation
- Invite link system
- Member management

## Troubleshooting

### "This Convex deployment does not have HTTP actions enabled"
- Make sure `convex/http.ts` exists
- Run `npx convex dev` to push the HTTP routes

### Missing environment variable `SITE_URL`
- This is required for Convex Auth to work
- Set it with: `npx convex env set SITE_URL "http://localhost:3000"`
- For production: `npx convex env set SITE_URL "https://spaces.suno.run"`

### Build fails with "Property 'users' does not exist on type '{}'"
- Run `npx convex dev` to generate API types
- Check that `convex/_generated/api.d.ts` includes your modules

### Google OAuth error "redirect_uri_mismatch"
- Check that the redirect URI in Google Cloud Console matches your Convex deployment URL
- Development format: `https://[deployment-name].convex.site/api/auth/callback/google`
- Production format: `https://[deployment-name].convex.cloud/api/auth/callback/google`
- Find your exact URL in `.env.local` as `NEXT_PUBLIC_CONVEX_URL`

### "Only @suno.com email addresses are allowed"
- This is expected! Auth is restricted to @suno.com emails only
- Update `convex/auth.ts` if you need to change this restriction

### Error: "Index users.email not found"
- This means you're redefining the `users` table in your schema
- The `users` table comes from `...authTables` and shouldn't be redefined
- Remove any custom `users` table definition from `convex/schema.ts`
- The auth tables include all necessary fields and indexes

## License

Internal Suno tool - not for public distribution