# 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