# Project Structure

Glockenspiel is organized as a monorepo with clear service boundaries. Here's what each directory contains:

## Directory Layout

```
glockenspiel/
├── studio_api/          # Main Django REST API
├── suno_utils/          # Shared Python utilities & Modal workers
├── ui/app-ui/           # Next.js web application
├── suno_orpheus/        # Chat-based music creation service
├── suno_recs/           # Recommendation engine
├── suno-cdk/            # AWS infrastructure (CDK)
├── suno_wiki/           # This documentation site
└── setup.sh             # Local development setup script
```

## Main Components

### `/studio_api`

**Purpose**: The heart of Suno - our Django REST API

**Contains**:
- Django apps for different features (`bots`, `billing`, `video_generation`, `search`)
- API endpoints using Django Ninja
- Celery background jobs
- Database models and migrations
- Management commands

**Key Files**:
- `settings.py` - Django configuration
- `urls.py` - API route definitions
- `celery.py` - Background job definitions
- `manage.py` - Django CLI entrypoint

### `/suno_utils`

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

**Contains**:
- Audio processing utilities (`audio/` - codecs, waveforms, beat detection)
- Modal worker implementations (`worker/` - ML inference jobs)
- Cloud abstraction layer (`cloud/` - Modal/Azure adapters)
- Shared business logic

**Used By**: `studio_api`, Modal workers, `suno_orpheus`, `suno_recs`

### `/ui/app-ui`

**Purpose**: User-facing web application

**Contains**:
- Next.js 15 App Router pages (`src/app/`)
- React components (`src/components/`)
- API client (`src/lib/apiClient.ts`)
- State management (TanStack Query, MobX)
- Styling (Tailwind, Chakra UI, Emotion)

**Key Files**:
- `src/app/` - Page routes
- `src/lib/gen.ts` - Auto-generated API types
- `package.json` - Dependencies and scripts

### `/suno_orpheus`

**Purpose**: Chat-based music creation service

**Contains**:
- Conversational UI for music generation
- Tool handlers for chat actions
- Streaming response handling
- Integration with LLMs

### `/suno_recs`

**Purpose**: Recommendation engine

**Contains**:
- Hook recommendations
- Feed orchestration
- ML-based scoring
- Feast feature store integration

### `/suno-cdk`

**Purpose**: Infrastructure as Code (AWS CDK)

**Contains**:
- TypeScript CDK stack definitions
- Backend infrastructure (ECS, ALB)
- Background job infrastructure (Celery)
- Redis cache stacks
- Event streaming stacks
- Monitoring and alerting

**Key Files**:
- `bin/suno-cdk.ts` - Entry point
- `lib/` - Stack definitions

### `/suno_wiki`

**Purpose**: This internal documentation site

**Tech**: Next.js + Nextra documentation framework

**Contains**: Guides, runbooks, architecture docs

## Configuration Files

### Root Level

- **`setup.sh`** - Automated local development setup
- **`lefthook.yml`** - Git hooks configuration (pre-commit checks)
- **`pyproject.toml`** - Python project metadata
- **`.github/workflows/`** - CI/CD workflows

### Service-Specific

- **`studio_api/.env`** - Backend environment variables
- **`ui/app-ui/.env`** - Frontend environment variables
- **`~/.modal.toml`** - Modal authentication config

## Common Patterns

### Python Services Structure

```
service_name/
├── service_name/        # Main package
│   ├── __init__.py
│   ├── settings.py      # Configuration
│   ├── api.py           # API endpoints
│   └── models.py        # Data models
├── tests/               # Test files
├── pyproject.toml       # Dependencies (uv)
└── README.md            # Service documentation
```

### Frontend Structure

```
ui/app-ui/
├── src/
│   ├── app/             # Next.js pages (App Router)
│   ├── components/      # React components
│   ├── lib/             # Utilities and API client
│   ├── state/           # State management
│   └── styles/          # Global styles
├── public/              # Static assets
└── package.json         # Dependencies (pnpm)
```

## Navigation Tips

- **API Endpoints**: Look in `studio_api/studio_api/*/api.py`
- **Database Models**: Look in `studio_api/studio_api/*/models.py`
- **Modal Workers**: Look in `suno_utils/suno_utils/worker/modal_*.py`
- **Frontend Pages**: Look in `ui/app-ui/src/app/`
- **Background Jobs**: Look in `studio_api/studio_api/celery.py`