watermelon-music/watermelon-api

Purpose and entry points

Watermelon API is a Node.js/Express REST backend for an Android music app. It searches YouTube, derives audio stream/download URLs through yt-dlp, exposes radio and recommendation APIs, and supports subscription payments and app statistics. Runtime startup is server.js, which boots the Express application in src/app.js.

HTTP composition and cross-cutting boundary

src/app.js assembles the API: security/CORS/compression, request logging, IP rate limiting, route mounting, and centralized failure handling. The middleware boundary keeps controllers focused on request/response orchestration.

• src/middlewares/rateLimit.middleware.js

• src/middlewares/logger.middleware.js

• src/middlewares/error.middleware.js

Music discovery and extraction pipeline

Search, song metadata, direct streaming, and download requests enter route-specific handlers and converge on the yt-dlp integration. The service invokes the bundled/downloaded yt-dlp executable to query YouTube and extract playable audio URLs; controllers transform results into API responses.

• src/routes/search.routes.js

• src/controllers/song.controller.js

• src/services/ytdlp.service.js

The yt-dlp binary is provisioned at install/build time by scripts/download-ytdlp.js; the repository includes bin/yt-dlp.exe for Windows.

Content and client-facing API domains

Routes separate public API domains: search/song lookup, stream/download delivery, artists, radio, leaderboards, stats, authentication, and recommendations. This is an HTTP API rather than a web UI; the Android client is the primary consumer.

• src/routes/song.routes.js

• src/routes/stream.routes.js

• src/routes/download.routes.js

Radio search/station browsing depends on the external Radio Browser service; AI recommendations depend on Gemini, per the API contract.

Persistence, caching, and engagement

Supabase is the system of record, using the supplied service-role configuration for users, playlists/favorites, listening statistics, premium state, and documented gamification data. The schema lives in supabase_setup.sql. In-memory caching reduces repeated yt-dlp/search and metadata work; scheduled/background behavior is centralized separately.

• supabase_setup.sql

• src/services/cache.service.js

• src/services/cronService.js

Payments and asynchronous integrations

Payment endpoints create orders, present checkout, verify status, and receive server-to-server webhooks through Cashfree. Payment-specific controller logic is isolated from the provider adapter. Optional Telegram bot and notification services provide external control and outbound messaging.

• src/routes/payment.routes.js

• src/controllers/cashfree.controller.js

• src/services/razorpay.service.js

Note the repository names the available adapter razorpay.service.js while the README/API describe Cashfree; this provider mismatch is an integration point to validate.

Deployment/runtime boundaries

Node.js LTS (18+) runs the service. Deployments target Render through render.yaml, Docker through Dockerfile, or self-hosted environments. Required external configuration includes Supabase; Cashfree and Telegram are optional. Render/Docker build steps explicitly download yt-dlp before starting server.js.

• render.yaml

• Dockerfile

• .env.example