Project documentation
Melofy is a modern, full-featured music streaming platform that combines the best of Spotify-like streaming with unique features that set it apart from competitors. Built with cutting-edge web technologies, Melofy offers users a seamless experience for discovering, streaming, downloading, and organizing their music library.
-
🔽 Flexible Download Options
- Unlike most streaming platforms, Melofy allows users to download songs for offline listening
- Multiple quality options: 128kbps, 256kbps, 320kbps, lossless
- DRM-protected files that work across devices
- Smart download management with storage analytics
- Why it matters: Users have true ownership and control over their music
-
🔍 MP3 File Recognition
- Upload unknown MP3 files and instantly identify them using advanced audio fingerprinting
- Batch upload support for multiple files
- Automatic metadata extraction and correction
- Recognition history tracking
- Why it matters: Helps users organize their existing music collections and discover songs they don't know
-
📚 Comprehensive Library Management
- Organize songs, albums, artists, and playlists in one place
- Smart categorization and tagging
- Recently played history
- Cross-device synchronization
- Why it matters: All-in-one music management solution
-
🎨 Modern User Experience
- Clean, intuitive interface inspired by Spotify but with unique design elements
- Real-time music player with queue management
- Personalized recommendations
- Dark/light theme support
- Why it matters: Professional, polished experience that rivals major platforms
| Category | Technology | Purpose |
|---|---|---|
| Framework | React 18 | UI component library |
| Language | TypeScript | Type safety and better DX |
| Build Tool | Vite | Fast development and optimized builds |
| State Management | Redux Toolkit | Global state management |
| Routing | React Router v6 | Client-side navigation |
| Styling | Tailwind CSS | Utility-first CSS framework |
| Audio Playback | Howler.js | Cross-browser audio support |
| HTTP Client | Axios | API communication |
| Forms | React Hook Form | Form validation and handling |
| Notifications | React Hot Toast | Toast notifications |
| Icons | Lucide React | Modern icon library |
| Date Handling | date-fns | Date formatting |
| Category | Technology | Purpose |
|---|---|---|
| Runtime | Node.js | JavaScript runtime |
| Language | TypeScript | Type safety |
| Framework | Express.js | Web framework |
| Database | PostgreSQL | Relational database |
| ORM | Prisma | Database ORM |
| Caching | Redis | Session and data caching |
| File Storage | AWS S3 | Cloud storage for music files |
| CDN | CloudFront | Content delivery network |
| Authentication | JWT + bcrypt | Secure authentication |
| Validation | Zod | Input validation |
| File Upload | Multer | File upload handling |
| Audio Processing | FFmpeg | Audio format conversion |
| Music Recognition | ACRCloud API | Audio fingerprinting |
| SendGrid | Email service | |
| Payment | Stripe | Subscription management |
| Category | Technology | Purpose |
|---|---|---|
| Version Control | Git + GitHub | Source control |
| Deployment | Docker | Containerization |
| CI/CD | GitHub Actions | Automated deployment |
| Monitoring | Sentry | Error tracking |
| Analytics | Mixpanel | User analytics |
frontend/
├── public/ # Static assets
│ ├── favicon.ico
│ ├── logo.png
│ ├── manifest.json
│ └── robots.txt
│
├── src/
│ ├── api/ # API communication layer
│ │ ├── client.ts # Axios instance
│ │ ├── endpoints.ts # API endpoints
│ │ └── services/
│ │ ├── auth.service.ts
│ │ ├── music.service.ts
│ │ ├── playlist.service.ts
│ │ ├── library.service.ts
│ │ ├── search.service.ts
│ │ ├── download.service.ts
│ │ ├── recognition.service.ts
│ │ ├── streaming.service.ts
│ │ └── user.service.ts
│ │
│ ├── assets/ # Images, fonts, sounds
│ │ ├── images/
│ │ ├── fonts/
│ │ └── sounds/
│ │
│ ├── components/ # React components
│ │ ├── common/ # Reusable components
│ │ │ ├── Button/
│ │ │ ├── Input/
│ │ │ ├── Modal/
│ │ │ ├── Card/
│ │ │ ├── Spinner/
│ │ │ └── Avatar/
│ │ │
│ │ ├── layout/ # Layout components
│ │ │ ├── Header/
│ │ │ ├── Sidebar/
│ │ │ ├── MainLayout/
│ │ │ └── AuthLayout/
│ │ │
│ │ ├── player/ # Music player
│ │ │ ├── Player/
│ │ │ ├── Queue/
│ │ │ ├── NowPlaying/
│ │ │ └── MiniPlayer/
│ │ │
│ │ ├── music/ # Music display
│ │ │ ├── SongCard/
│ │ │ ├── AlbumCard/
│ │ │ ├── ArtistCard/
│ │ │ ├── PlaylistCard/
│ │ │ └── SongList/
│ │ │
│ │ ├── playlist/ # Playlist management
│ │ ├── library/ # Library components
│ │ ├── search/ # Search components
│ │ ├── recognition/ # MP3 recognition
│ │ ├── download/ # Download management
│ │ └── auth/ # Authentication
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── useAuth.ts
│ │ ├── usePlayer.ts
│ │ ├── useQueue.ts
│ │ ├── useAudio.ts
│ │ └── useDebounce.ts
│ │
│ ├── pages/ # Page components
│ │ ├── Home/
│ │ ├── Browse/
│ │ ├── Search/
│ │ ├── Library/
│ │ ├── Playlist/
│ │ ├── Album/
│ │ ├── Artist/
│ │ ├── Recognition/
│ │ ├── Downloads/
│ │ ├── Profile/
│ │ ├── Settings/
│ │ ├── Auth/
│ │ └── NotFound/
│ │
│ ├── routes/ # Routing
│ │ ├── index.tsx
│ │ ├── PrivateRoute.tsx
│ │ └── routes.config.ts
│ │
│ ├── store/ # Redux store
│ │ ├── index.ts
│ │ ├── hooks.ts
│ │ └── slices/
│ │ ├── authSlice.ts
│ │ ├── playerSlice.ts
│ │ ├── queueSlice.ts
│ │ ├── librarySlice.ts
│ │ ├── playlistSlice.ts
│ │ ├── searchSlice.ts
│ │ ├── uiSlice.ts
│ │ └── downloadSlice.ts
│ │
│ ├── types/ # TypeScript types
│ │ ├── index.ts
│ │ ├── music.types.ts
│ │ ├── auth.types.ts
│ │ ├── playlist.types.ts
│ │ ├── player.types.ts
│ │ ├── download.types.ts
│ │ └── recognition.types.ts
│ │
│ ├── utils/ # Utility functions
│ │ ├── formatters/
│ │ ├── validators/
│ │ ├── storage.ts
│ │ ├── constants.ts
│ │ └── helpers.ts
│ │
│ ├── styles/ # Global styles
│ │ ├── index.css
│ │ ├── globals.css
│ │ └── themes/
│ │
│ ├── config/ # Configuration
│ │ ├── api.config.ts
│ │ ├── app.config.ts
│ │ └── theme.config.ts
│ │
│ ├── App.tsx
│ ├── main.tsx
│ └── vite-env.d.ts
│
├── .env
├── .env.example
├── .gitignore
├── package.json
├── tailwind.config.js
├── tsconfig.json
├── vite.config.ts
└── README.md
backend/
├── src/
│ ├── config/ # Configuration
│ │ ├── database.ts # PostgreSQL connection
│ │ ├── redis.ts # Redis connection
│ │ ├── storage.ts # AWS S3 configuration
│ │ ├── auth.ts # JWT configuration
│ │ └── app.ts # App settings
│ │
│ ├── controllers/ # Request handlers
│ │ ├── auth.controller.ts # Authentication
│ │ ├── music.controller.ts # Music CRUD
│ │ ├── playlist.controller.ts # Playlist management
│ │ ├── library.controller.ts # User library
│ │ ├── search.controller.ts # Search functionality
│ │ ├── download.controller.ts # Download management
│ │ ├── recognition.controller.ts # MP3 recognition
│ │ ├── streaming.controller.ts # Audio streaming
│ │ └── user.controller.ts # User profile
│ │
│ ├── models/ # Database models (Prisma)
│ │ ├── User.model.ts
│ │ ├── Song.model.ts
│ │ ├── Album.model.ts
│ │ ├── Artist.model.ts
│ │ ├── Playlist.model.ts
│ │ ├── PlaylistSong.model.ts
│ │ ├── Library.model.ts
│ │ ├── Download.model.ts
│ │ ├── Recognition.model.ts
│ │ └── index.ts
│ │
│ ├── routes/ # API routes
│ │ ├── auth.routes.ts # /api/auth/*
│ │ ├── music.routes.ts # /api/music/*
│ │ ├── playlist.routes.ts # /api/playlists/*
│ │ ├── library.routes.ts # /api/library/*
│ │ ├── search.routes.ts # /api/search/*
│ │ ├── download.routes.ts # /api/downloads/*
│ │ ├── recognition.routes.ts # /api/recognition/*
│ │ ├── streaming.routes.ts # /api/stream/*
│ │ ├── user.routes.ts # /api/users/*
│ │ └── index.ts
│ │
│ ├── services/ # Business logic
│ │ ├── auth.service.ts # JWT, password hashing
│ │ ├── music.service.ts # Music operations
│ │ ├── playlist.service.ts # Playlist logic
│ │ ├── library.service.ts # Library operations
│ │ ├── search.service.ts # Search algorithms
│ │ ├── download.service.ts # Download logic + DRM
│ │ ├── recognition.service.ts # ACRCloud integration
│ │ ├── streaming.service.ts # Audio streaming
│ │ ├── storage.service.ts # S3 operations
│ │ ├── email.service.ts # Email sending
│ │ └── recommendation.service.ts # Music recommendations
│ │
│ ├── middlewares/ # Express middlewares
│ │ ├── auth.middleware.ts # JWT verification
│ │ ├── error.middleware.ts # Error handling
│ │ ├── validation.middleware.ts # Request validation
│ │ ├── upload.middleware.ts # File upload (Multer)
│ │ ├── rateLimit.middleware.ts # Rate limiting
│ │ └── logging.middleware.ts # Request logging
│ │
│ ├── validators/ # Input validation
│ │ ├── auth.validator.ts
│ │ ├── music.validator.ts
│ │ ├── playlist.validator.ts
│ │ └── file.validator.ts
│ │
│ ├── utils/ # Utility functions
│ │ ├── jwt.ts # JWT helpers
│ │ ├── bcrypt.ts # Password hashing
│ │ ├── logger.ts # Winston logger
│ │ ├── errors.ts # Custom error classes
│ │ ├── response.ts # Standard responses
│ │ └── helpers.ts
│ │
│ ├── types/ # TypeScript types
│ │ ├── express.d.ts # Extend Express types
│ │ ├── user.types.ts
│ │ ├── music.types.ts
│ │ └── index.ts
│ │
│ ├── database/ # Database
│ │ ├── schema.prisma # Prisma schema
│ │ ├── migrations/ # Database migrations
│ │ └── seeds/ # Seed data
│ │
│ ├── jobs/ # Background jobs
│ │ ├── audioProcessing.job.ts
│ │ ├── cleanup.job.ts
│ │ └── analytics.job.ts
│ │
│ ├── app.ts # Express app
│ └── server.ts # Server entry point
│
├── uploads/ # Temporary uploads
├── logs/ # Application logs
├── .env
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
├── prisma/
│ └── schema.prisma
└── README.md
- User registration with email verification
- Login with JWT token authentication
- Password reset functionality
- Social login (Google, Facebook) - Optional
- Session management
- Role-based access control (User, Premium, Admin)
- High-quality audio streaming (128kbps, 256kbps, 320kbps)
- Adaptive bitrate streaming based on connection
- Crossfade between tracks
- Gapless playback
- Volume normalization
- Playback history tracking
- Play, pause, next, previous controls
- Seekable progress bar
- Volume control with mute
- Shuffle mode
- Repeat modes (off, all, one)
- Queue management (add, remove, reorder)
- Now playing screen with lyrics
- Mini player for background playback
- Download songs for offline listening
- Multiple quality options
- DRM protection
- Download progress tracking
- Storage management
- Download queue
- Auto-delete old downloads
- WiFi-only download option
- Upload MP3 files for identification
- Audio fingerprinting via ACRCloud
- Batch upload support
- Recognition history
- Automatic metadata extraction
- Add identified songs to library
- Liked songs collection
- Saved albums
- Followed artists
- User playlists
- Recently played
- Listening statistics
- Smart playlists (auto-generated)
- Create custom playlists
- Add/remove songs
- Reorder songs (drag & drop)
- Playlist cover customization
- Public/private playlists
- Collaborative playlists
- Share playlists
- Search songs, albums, artists, playlists
- Advanced filters (genre, year, popularity)
- Search suggestions
- Recently searched
- Trending searches
- Genre browsing
- New releases
- Top charts
- Personalized recommendations
- Similar songs/artists
- Daily mixes
- Discover weekly
- Release radar
- Based on listening history
- Profile customization
- Avatar upload
- Bio and preferences
- Public profile page
- Listening statistics
- Followers/following
- Activity feed
- Account settings
- Playback quality
- Download settings
- Privacy settings
- Notification preferences
- Theme customization
- Language selection
- Follow/unfollow users
- Share songs/playlists
- See friends' activity
- Collaborative playlists
- Comments on playlists
Users
├── id (UUID)
├── email (unique)
├── username (unique)
├── password_hash
├── avatar
├── is_premium (boolean)
├── subscription_expires_at
├── created_at
└── updated_at
Songs
├── id (UUID)
├── title
├── artist_id (FK → Artists)
├── album_id (FK → Albums)
├── duration
├── audio_url
├── cover_url
├── genre
├── release_date
├── play_count
├── created_at
└── updated_at
Albums
├── id (UUID)
├── title
├── artist_id (FK → Artists)
├── cover_url
├── release_date
├── total_tracks
├── type (album/single/ep)
├── created_at
└── updated_at
Artists
├── id (UUID)
├── name
├── bio
├── image_url
├── followers_count
├── verified (boolean)
├── created_at
└── updated_at
Playlists
├── id (UUID)
├── user_id (FK → Users)
├── name
├── description
├── cover_url
├── is_public (boolean)
├── is_collaborative (boolean)
├── created_at
└── updated_at
PlaylistSongs (Junction Table)
├── playlist_id (FK → Playlists)
├── song_id (FK → Songs)
├── position (order)
└── added_at
Library (User's liked content)
├── id (UUID)
├── user_id (FK → Users)
├── song_id (FK → Songs, nullable)
├── album_id (FK → Albums, nullable)
├── artist_id (FK → Artists, nullable)
├── type (song/album/artist)
└── liked_at
Downloads
├── id (UUID)
├── user_id (FK → Users)
├── song_id (FK → Songs)
├── file_path
├── quality
├── status
├── downloaded_at
└── expires_at
RecognitionHistory
├── id (UUID)
├── user_id (FK → Users)
├── file_name
├── result (JSON)
├── confidence
├── recognized_at
└── song_id (FK → Songs, nullable)