you-music/STRUCTURE.md

# YouMusic - Complete Project Structure

```
you-music/
├── README.md                          # Main documentation
├── QUICKSTART.md                      # Quick start guide
├── PROJECT_SUMMARY.md                 # Project summary
├── LICENSE                            # MIT License
├── .gitignore                         # Git ignore rules
├── setup.sh                           # Setup script
├── Dockerfile                         # Docker image definition
├── docker-compose.yml                 # Docker compose config
│
├── backend/                           # Python FastAPI backend
│   ├── .env.example                   # Environment variables example
│   ├── pyproject.toml                 # Python dependencies (uv)
│   ├── main.py                        # FastAPI application entry
│   │
│   └── app/
│       ├── __init__.py
│       │
│       ├── core/                      # Core configuration
│       │   ├── __init__.py
│       │   └── config.py              # Settings and configuration
│       │
│       ├── db/                        # Database configuration
│       │   ├── __init__.py
│       │   └── session.py             # SQLAlchemy async session
│       │
│       ├── models/                    # SQLAlchemy models
│       │   ├── __init__.py
│       │   └── models.py              # Music & Playlist models
│       │
│       ├── schemas/                   # Pydantic schemas
│       │   ├── __init__.py
│       │   └── schemas.py             # Request/Response schemas
│       │
│       ├── api/                       # API endpoints
│       │   ├── __init__.py
│       │   ├── music.py               # Music CRUD endpoints
│       │   ├── playlist.py            # Playlist management
│       │   ├── download.py            # Download functionality
│       │   └── search.py              # Search endpoints
│       │
│       ├── services/                  # Business logic
│       │   ├── __init__.py
│       │   ├── downloader.py          # Music download service (yt-dlp)
│       │   └── search.py              # Search service
│       │
│       └── utils/                     # Utility functions
│           └── __init__.py
│
├── frontend/                          # React + TypeScript frontend
│   ├── .env.example                   # Frontend env variables
│   ├── package.json                   # Node.js dependencies
│   ├── tsconfig.json                  # TypeScript config
│   ├── tsconfig.node.json             # TypeScript Node config
│   ├── vite.config.ts                 # Vite build config
│   ├── tailwind.config.js             # Tailwind CSS config
│   ├── postcss.config.js              # PostCSS config
│   ├── index.html                     # HTML entry point
│   │
│   └── src/
│       ├── main.tsx                   # React entry point
│       ├── App.tsx                    # Main App component
│       ├── index.css                  # Global styles (Tailwind)
│       │
│       ├── components/                # React components
│       │   ├── Navigation.tsx         # Top navigation bar
│       │   ├── MusicLibrary.tsx       # Library view
│       │   │
│       │   ├── ui/                    # shadcn/ui components
│       │   │   ├── button.tsx         # Button component
│       │   │   ├── input.tsx          # Input component
│       │   │   └── slider.tsx         # Slider component
│       │   │
│       │   ├── player/                # Music player components
│       │   │   └── Player.tsx         # Main player component
│       │   │
│       │   ├── search/                # Search functionality
│       │   │   └── SearchPage.tsx     # Search page
│       │   │
│       │   └── playlist/              # Playlist management
│       │       └── PlaylistsPage.tsx  # Playlists page
│       │
│       ├── api/                       # API client
│       │   └── client.ts              # Axios API client
│       │
│       ├── lib/                       # Utility functions
│       │   └── utils.ts               # Helper functions
│       │
│       ├── types/                     # TypeScript types
│       │   └── index.ts               # Type definitions
│       │
│       └── hooks/                     # Custom React hooks
│           └── (future hooks)
│
└── data/                              # Runtime data (created at runtime)
    ├── music/                         # Downloaded music files
    ├── uploads/                       # Uploaded music files
    ├── temp/                          # Temporary files
    └── youmusic.db                    # SQLite database
```

## File Descriptions

### Root Level
- **README.md**: Comprehensive project documentation
- **QUICKSTART.md**: Quick start guide for new users
- **PROJECT_SUMMARY.md**: Feature summary and architecture
- **LICENSE**: MIT License
- **.gitignore**: Git ignore patterns
- **setup.sh**: Automated setup script
- **Dockerfile**: Multi-stage Docker build
- **docker-compose.yml**: Docker service orchestration

### Backend (`backend/`)
- **main.py**: FastAPI application initialization, CORS setup, route mounting
- **pyproject.toml**: All Python package dependencies (managed by uv)

#### Core (`backend/app/core/`)
- **config.py**: Application settings using Pydantic Settings

#### Database (`backend/app/db/`)
- **session.py**: SQLAlchemy async engine and session management

#### Models (`backend/app/models/`)
- **models.py**:
  - Music model (tracks, metadata)
  - Playlist model (user playlists)
  - Many-to-many relationship table

#### Schemas (`backend/app/schemas/`)
- **schemas.py**:
  - Pydantic models for request/response
  - Validation schemas
  - Type hints for API

#### API (`backend/app/api/`)
- **music.py**: Music CRUD operations, search, upload
- **playlist.py**: Playlist management endpoints
- **download.py**: Download from URLs (YouTube, Bilibili)
- **search.py**: Search external sources

#### Services (`backend/app/services/`)
- **downloader.py**:
  - yt-dlp integration
  - Download logic from xiaomusic
  - Metadata extraction
- **search.py**:
  - YouTube search
  - Bilibili search
  - Result parsing

### Frontend (`frontend/`)
- **index.html**: Single-page app entry point
- **package.json**: npm dependencies and scripts
- **vite.config.ts**: Vite configuration, proxy setup
- **tailwind.config.js**: Tailwind theme configuration

#### Source (`frontend/src/`)
- **main.tsx**: React app initialization, providers
- **App.tsx**: Main app component, routing, player state
- **index.css**: Tailwind directives, CSS variables

#### Components (`frontend/src/components/`)
- **Navigation.tsx**: Responsive navigation bar
- **MusicLibrary.tsx**: Music library grid view

##### UI Components (`frontend/src/components/ui/`)
- shadcn/ui components styled with Tailwind

##### Player (`frontend/src/components/player/`)
- **Player.tsx**: Full-featured music player with controls

##### Search (`frontend/src/components/search/`)
- **SearchPage.tsx**: Search interface, results display

##### Playlist (`frontend/src/components/playlist/`)
- **PlaylistsPage.tsx**: Playlist management UI

#### API Client (`frontend/src/api/`)
- **client.ts**:
  - Axios instance
  - API function definitions
  - Type-safe endpoints

#### Types (`frontend/src/types/`)
- **index.ts**: TypeScript interfaces for Music, Playlist, etc.

#### Utils (`frontend/src/lib/`)
- **utils.ts**: Helper functions (cn, formatDuration)

## Key Technologies

### Backend
- **FastAPI**: Modern Python web framework
- **SQLAlchemy**: SQL toolkit and ORM
- **yt-dlp**: Universal media downloader
- **mutagen**: Audio metadata library
- **aiosqlite**: Async SQLite driver

### Frontend
- **React 18**: UI library
- **TypeScript**: Type safety
- **Vite**: Fast build tool
- **TanStack Query**: Data fetching
- **shadcn/ui**: Component library
- **Tailwind CSS**: Utility-first CSS

### DevOps
- **Docker**: Containerization
- **Docker Compose**: Multi-container orchestration

## Data Flow

1. **Search**: Frontend → Search API → External APIs → Results
2. **Download**: Frontend → Download API → yt-dlp → File + DB entry
3. **Play**: Frontend → Music API → File stream → Audio player
4. **Playlist**: Frontend → Playlist API → Database → Updated state

## API Communication

All frontend-backend communication uses REST APIs:
- JSON request/response
- Standard HTTP methods (GET, POST, PUT, DELETE)
- Error handling with HTTP status codes
- CORS enabled for development

## Database Schema

### Tables
1. **music**: Stores music metadata and file paths
2. **playlists**: User-created playlists
3. **playlist_music**: Many-to-many relationship

### Relationships
- One playlist has many music items
- One music item can be in many playlists

## Environment Variables

### Backend (`.env`)
- DATABASE_URL: Database connection
- MUSIC_DIR: Music storage path
- PROXY: Optional HTTP proxy
- FFMPEG_LOCATION: FFmpeg binary path

### Frontend (`.env`)
- VITE_API_URL: Backend API URL

## Build & Run

### Development
```bash
# Backend
cd backend && uvicorn main:app --reload

# Frontend
cd frontend && npm run dev
```

### Production
```bash
docker-compose up -d
```

## Port Configuration

- **8000**: Main application (backend + frontend)
- **3000**: Frontend dev server (development only)

## Volume Mounts (Docker)

- `./data:/app/data` - Persistent music and database storage
- `./backend:/app/backend` - Hot reload for development