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

# Backend
cd backend && uvicorn main:app --reload

# Frontend
cd frontend && npm run dev

Production

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