# 002: Core Features Implementation

## Overview

Build out the core functionality for Suno Spaces including spaces/rooms management, messaging, presence tracking, and the full UI. This phase assumes 001 (skeleton infrastructure) is complete.

## Goals

- Implement complete schema for all entities (SpaceMembers, Invites, Messages, Presence)
- Build space and room management (CRUD operations with permissions)
- Implement invite link system for easy collaboration
- Create real-time presence tracking
- Build message system with reactions and mentions
- Build full UI for spaces, rooms, chat, and member management
- Create basic showcase area for each space

## Schema Implementation

Extend the minimal schema from 001 to include:

### Complete User Schema
- Users: Add `homeSpaceId` field for personal space

### Space Management
- SpaceMembers: spaceId, userId, joinedAt, role, isKicked (for member list and moderation)
- SpaceInvites: spaceId, code, createdBy, expiresAt (for invite links)
- Spaces: Add showcaseConfig field for theming, isHomeSpace field to mark home spaces

### Rooms
- Rooms: Add isPrivate, allowlist fields (implementation of private rooms optional for this phase)

### Real-time Features
- UserPresence: userId, spaceId, roomId, status, lastSeen (real-time presence tracking)
- Messages: roomId, userId, content, timestamp, reactions, mentions

## Backend Functions (Convex)

### User Operations
- Auto-create home space on first sign-in
- Update user profile (handle, displayName, avatar)
- Query user presence

### Space Operations
- Create space (with default showcase config)
- Update space settings
- Delete space (owner only)
- List user's spaces
- Get space members with presence
- Kick member from space (owner only)

### Invite Operations
- Generate invite link/code
- Validate and use invite code to join space
- List active invites for a space
- Revoke invite

### Room Operations
- Create room in space
- Update room settings
- Delete room
- List rooms in space
- Query room with messages

### Message Operations
- Send message (with mentions)
- Add/remove reaction to message
- Delete own message
- Query messages with pagination

### Presence Operations
- Update user presence (space/room location, status)
- Track active users in space/room
- Handle presence timeout/cleanup

## Permission System

Implement permission checks in all Convex functions:
- **Space owners** can: create/update/delete rooms, kick members, manage invites
- **Space members** can: read space/rooms, create messages
- **Users** can: update/delete only their own messages
- **Private rooms** (if implemented): only accessible to allowlist users

## UI Components

### Authentication Flow
- Landing page with Google sign-in
- Post-auth redirect to home space or last visited space

### Layout & Navigation
- App header with space selector/navigation
- Space sidebar with room list
- Member list with presence indicators
- Mobile-responsive navigation

### Space View
- Space header (name, settings button for owner)
- Room list navigation
- Member list with online/offline status
- Invite button (generates shareable link)
- Basic showcase area

### Room View
- Room header with name
- Message feed with infinite scroll/pagination
- Message composer with mention autocomplete
- Emoji reaction picker

### Member Management
- Member list UI with roles
- Kick member button (for owners)
- Presence indicators (online, in room X, idle, offline)

### Showcase Area
- Basic canvas/display area for each space
- Simple config structure (theme colors, background)
- Placeholder for future drag-and-drop editor

## Acceptance Criteria

- [ ] User gets a home space created automatically on first sign-in
- [ ] Authenticated user can create additional spaces
- [ ] Space owner can create rooms within their space
- [ ] Spaces have a member list showing real-time presence
- [ ] Users can generate and use invite links to join spaces
- [ ] Space owners can kick users from their space
- [ ] Users can send messages with emoji reactions
- [ ] Users can mention other users and Orphy in messages
- [ ] Navigation between spaces and rooms works seamlessly
- [ ] Each space has a basic showcase area
- [ ] Real-time updates work (new messages, presence changes, etc.)
- [ ] Mobile web experience is fully functional
- [ ] All permission checks are enforced server-side

## Technical Considerations

### Relational Database Design

Follow relational architecture patterns with proper foreign keys, indexes, and normalized data structures. Leverage Convex's built-in support for reactive queries and real-time subscriptions.

### Theming System Foundation

Implement basic theming infrastructure (color scheme storage, custom backgrounds) that can be extended later. Ensure themes work across desktop and mobile web.

### Mobile Web

All features must work on both desktop and mobile web. Use responsive design patterns throughout.

### Solo and Multiplayer (Sync and Async)

Design features to work well both synchronously (real-time collaboration) and asynchronously (drop in, leave messages, work independently). The home space concept ensures everyone has a personal creative space that works solo.

### Presence System

Implement robust presence tracking using Convex's multiplayer capabilities. Consider:
- Heartbeat/ping mechanism to update lastSeen
- Automatic cleanup of stale presence data
- Efficient queries to show who's online/in which room

### Chat Features

- Emoji reactions stored efficiently (consider reaction counts vs. individual records)
- Mention detection (@user, @Orphy) with autocomplete
- Message pagination for performance

### Orphy Assistant Data Model

Messages can mention @Orphy. For now, just store the mention - actual assistant responses will be implemented in a future phase. Consider how Orphy responses will fit into the message/thread structure later.

## Out of Scope (Future Phases)

- Atoms system (moved to Phase 003)
- Music playback system and queue/playlist (radio mode)
- Orphy assistant implementation (actual AI responses, creation, DJ features)
- Thread/comment system for messages
- User hover previews with stats and mini-showcase
- Advanced theme customization UI
- Showcase canvas editor with drag-and-drop, freeform placement, snap-to-grid
- Rich invite link pages with OpenGraph previews and stats
- Voice chat overlay during music playback
- Actual private rooms implementation with allowlists (schema exists but feature optional)
- Alternative room types (DAW timeline, FigJam canvas, multiplayer rhythm game)
- Native iOS/Android apps
- VR support