# Core Services

Suno's architecture consists of several key services that work together to deliver AI-generated music.

## Studio API (Django Backend)

**Location**: `/studio_api`

**Purpose**: The heart of Suno - handles all core application logic

### Tech Stack

- **Framework**: Django with Django Ninja for API endpoints
- **Database**: PostgreSQL (via Django ORM)
- **Caching**: Redis / Valkey (multiple instances)
- **Background Jobs**: Celery with Redis broker
- **Authentication**: Clerk integration
- **Payments**: Stripe
- **Real-time**: Ably for live updates

### Django Apps Structure

```
studio_api/studio_api/
├── bots/              # Core music generation
├── billing/           # Subscription and payment logic
├── video_generation/  # Video/image generation
├── search/            # Elasticsearch integration
├── dynamodb/          # DynamoDB handlers
└── user_data/         # User profiles and settings
```

### API Design

Uses Django Ninja for type-safe, fast API endpoints:

```python
from ninja import Router
from studio_api.bots.schemas import GenerateRequest, ClipResponse

router = Router()

@router.post("/generate", response=ClipResponse)
def generate_music(request, payload: GenerateRequest):
    # Type-checked request/response
    clip = create_clip(payload.prompt)
    return clip
```

### Background Jobs (Celery)

Scheduled tasks handle recurring operations:

- **Every minute**: Update trending playlists, send notifications
- **Every 5 seconds**: Generate "living radio" clips
- **Hourly**: Update contest votes, clean up old data
- **Daily**: Refresh top clips, user analytics
- **Weekly**: Regenerate genre playlists

## Frontend (Next.js Web App)

**Location**: `/ui/app-ui`

**Purpose**: User-facing interface for music creation and discovery

### Tech Stack

- **Framework**: Next.js 15 with App Router
- **UI**: React 19 + TypeScript
- **Styling**: Tailwind CSS, Chakra UI (legacy), Emotion (for /studio)
- **State Management**: TanStack Query (primary), MobX (audio player)
- **Authentication**: Clerk
- **Analytics**: Segment, Datadog RUM

### State Management Strategy

**Priority order**:
1. **TanStack Query** - All server state and API caching
2. **useState** - Local component state
3. **useContext** - Shared state across components
4. **MobX** - Complex UI state (audio player, timeline editor)

Example:
```typescript
const { data: clips, isLoading } = useQuery({
  queryKey: ['clips', userId],
  queryFn: async () => {
    const response = await apiClient.GET('/api/clips');
    return deepCamelKeys(response.data);
  },
  staleTime: 30000,
});
```

### API Integration

Type-safe API client generated from Django OpenAPI schema:

```bash
# Generate types from backend schema
pnpm gen-types
```

This creates `src/lib/gen.ts` with full TypeScript types for all API endpoints.


## Suno Utils (Shared Library)

**Location**: `/suno_utils`

**Purpose**: Common Python toolkit used across all services

### What's Inside

**Audio Processing** (`audio/`):
- Codec utilities (MP3, WAV, OGG encoding/decoding)
- Waveform generation and analysis
- Beat detection and music theory utilities
- Stem separation helpers

**Modal Workers** (`worker/`):
- Music generation workers (Chirp V4)
- Video generation workers (SDXL, WAN2, Higgsfield)
- Audio processing workers (stems, upsampling)
- Feature extraction workers (BPM, key detection)
- LLM integration workers (GPT-4 for lyrics)

**Cloud Abstraction** (`cloud/`):
- Adapters for Modal and Azure
- Queue management (Redis queues)
- Volume/storage abstractions
- Callback handlers

## Suno Orpheus (Chat Service)

**Location**: `/suno_orpheus`

**Purpose**: Conversational interface for music creation

### Features

- Chat-based music generation
- Multi-turn conversations
- Tool calling for music actions
- Streaming responses
- Context-aware suggestions

### Integration

Works with:
- Studio API for music generation
- GPT-4 for conversation handling
- Modal for ML inference

## Suno Recs (Recommendation Engine)

**Location**: `/suno_recs`

**Purpose**: Personalized music recommendations

### Features

- Hook recommendations (music video suggestions)
- Feed orchestration (personalized home feed)
- ML-based scoring and ranking
- A/B testing for ranking algorithms

### Tech

- Python service with Modal workers
- Feast feature store for ML features
- Redis for real-time features
- PostgreSQL for user interaction history

## Service Communication

### API Calls

Frontend ↔ Studio API:
- REST API with JSON
- Type-safe via generated OpenAPI client

Studio API ↔ Modal:
- Redis queues for job submission
- HTTP callbacks for results

### Real-time Updates

- **Ably**: Frontend ↔ Studio API for live generation status
- **Redis Pub/Sub**: Internal service communication