# watermelon-music/watermelon-api architecture

> Architecture diagram of the GitHub repository watermelon-music/watermelon-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/watermelon-music/watermelon-api
- Repository: https://github.com/watermelon-music/watermelon-api

## Overview

#### 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`

Main entry points: [`src/app.js`](https://github.com/watermelon-music/watermelon-api/blob/main/src/app.js) (Express app), [`src/controllers/song.controller.js`](https://github.com/watermelon-music/watermelon-api/blob/main/src/controllers/song.controller.js) (Song controller), [`bin/yt-dlp.exe`](https://github.com/watermelon-music/watermelon-api/blob/main/bin/yt-dlp.exe) (yt-dlp executable), [`server.js`](https://github.com/watermelon-music/watermelon-api/blob/main/server.js) (Server startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_app["Express app<br/>HTTP composition<br/>[app.js]"]
  node_middleware["Middleware boundary<br/>security and errors"]
  node_api_routes["API route domains<br/>Express routes"]
  node_song_controller["Song controller<br/>request controller<br/>[song.controller.js]"]
  node_payment_routes["Payment routes<br/>Express routes<br/>[payment.routes.js]"]
  node_cashfree_controller["Payment controller<br/>payment orchestration"]
end

subgraph group_music["Music pipeline"]
  node_ytdlp_service{{"yt-dlp service<br/>media extraction<br/>[ytdlp.service.js]"}}
  node_ytdlp_binary["yt-dlp executable<br/>bundled binary<br/>[yt-dlp.exe]"]
  node_youtube(("YouTube<br/>external media source"))
  node_cache[("In-memory cache<br/>cache service<br/>[cache.service.js]")]
end

subgraph group_integrations["External integrations"]
  node_supabase[("Supabase<br/>system of record")]
  node_schema["Supabase schema<br/>SQL schema<br/>[supabase_setup.sql]"]
  node_radio_browser(("Radio Browser<br/>external radio API"))
  node_gemini(("Gemini<br/>recommendation API"))
  node_payment_adapter{{"Razorpay adapter<br/>payment provider adapter"}}
  node_cashfree(("Cashfree<br/>payment provider"))
end

subgraph group_runtime["Runtime and deployment"]
  node_server["Server startup<br/>Node entry point<br/>[server.js]"]
  node_cron["Scheduled jobs<br/>background service<br/>[cronService.js]"]
  node_ytdlp_provision["yt-dlp provisioning<br/>build script<br/>[download-ytdlp.js]"]
  node_deploy["Render / Docker<br/>deployment targets"]
end

node_android_client(("Android client<br/>API consumer"))

node_android_client -->|"HTTPS requests"| node_server
node_server -->|"boots"| node_app
node_app -->|"applies"| node_middleware
node_middleware -->|"passes requests"| node_api_routes
node_app -->|"mounts"| node_api_routes
node_api_routes -->|"music requests"| node_song_controller
node_song_controller -->|"reads and writes"| node_cache
node_song_controller -->|"searches and extracts"| node_ytdlp_service
node_ytdlp_service -->|"executes"| node_ytdlp_binary
node_ytdlp_binary -->|"queries"| node_youtube
node_api_routes -->|"users and engagement"| node_supabase
node_schema -->|"defines"| node_supabase
node_api_routes -->|"radio browsing"| node_radio_browser
node_api_routes -->|"recommendations"| node_gemini
node_api_routes -->|"payment endpoints"| node_payment_routes
node_payment_routes -->|"dispatches"| node_cashfree_controller
node_cashfree_controller -->|"uses"| node_payment_adapter
node_payment_adapter -.->|"provider target to validate"| node_cashfree
node_cron -->|"background work"| node_supabase
node_deploy -->|"build step"| node_ytdlp_provision
node_ytdlp_provision -->|"downloads"| node_ytdlp_binary
node_deploy -->|"starts"| node_server

click node_server "https://github.com/watermelon-music/watermelon-api/blob/main/server.js"
click node_app "https://github.com/watermelon-music/watermelon-api/blob/main/src/app.js"
click node_song_controller "https://github.com/watermelon-music/watermelon-api/blob/main/src/controllers/song.controller.js"
click node_payment_routes "https://github.com/watermelon-music/watermelon-api/blob/main/src/routes/payment.routes.js"
click node_cashfree_controller "https://github.com/watermelon-music/watermelon-api/blob/main/src/controllers/cashfree.controller.js"
click node_ytdlp_service "https://github.com/watermelon-music/watermelon-api/blob/main/src/services/ytdlp.service.js"
click node_ytdlp_binary "https://github.com/watermelon-music/watermelon-api/blob/main/bin/yt-dlp.exe"
click node_cache "https://github.com/watermelon-music/watermelon-api/blob/main/src/services/cache.service.js"
click node_schema "https://github.com/watermelon-music/watermelon-api/blob/main/supabase_setup.sql"
click node_payment_adapter "https://github.com/watermelon-music/watermelon-api/blob/main/src/services/razorpay.service.js"
click node_cron "https://github.com/watermelon-music/watermelon-api/blob/main/src/services/cronService.js"
click node_ytdlp_provision "https://github.com/watermelon-music/watermelon-api/blob/main/scripts/download-ytdlp.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_middleware,node_api_routes,node_song_controller,node_payment_routes,node_cashfree_controller toneBlue
class node_ytdlp_service,node_ytdlp_binary,node_youtube,node_cache toneAmber
class node_supabase,node_schema,node_radio_browser,node_gemini,node_payment_adapter,node_cashfree toneMint
class node_server,node_cron,node_ytdlp_provision,node_deploy toneRose
class node_android_client toneNeutral
```

## Components

### HTTP API

Express routes, controllers, and middleware.

- [Express app](https://github.com/watermelon-music/watermelon-api/blob/main/src/app.js): HTTP composition · Mounts routes and centralized middleware. · `src/app.js`
- **Middleware boundary**: security and errors · Rate limiting, request logging, and failure handling.
- **API route domains**: Express routes · Search, songs, streams, downloads, artists, radio, stats, auth, and recommendations.
- [Song controller](https://github.com/watermelon-music/watermelon-api/blob/main/src/controllers/song.controller.js): request controller · Transforms music lookup and extraction results into responses. · `src/controllers/song.controller.js`
- [Payment routes](https://github.com/watermelon-music/watermelon-api/blob/main/src/routes/payment.routes.js): Express routes · `src/routes/payment.routes.js`
- [Payment controller](https://github.com/watermelon-music/watermelon-api/blob/main/src/controllers/cashfree.controller.js): payment orchestration · `src/controllers/cashfree.controller.js`

### Music pipeline

YouTube discovery and audio extraction.

- [yt-dlp service](https://github.com/watermelon-music/watermelon-api/blob/main/src/services/ytdlp.service.js): media extraction · Invokes yt-dlp for YouTube metadata and playable audio URLs. · `src/services/ytdlp.service.js`
- [yt-dlp executable](https://github.com/watermelon-music/watermelon-api/blob/main/bin/yt-dlp.exe): bundled binary · `bin/yt-dlp.exe`
- **YouTube**: external media source
- [In-memory cache](https://github.com/watermelon-music/watermelon-api/blob/main/src/services/cache.service.js): cache service · Avoids repeated search and metadata extraction. · `src/services/cache.service.js`

### External integrations

Persistence and provider boundaries.

- **Supabase**: system of record · Stores users, music data, engagement, and premium state.
- [Supabase schema](https://github.com/watermelon-music/watermelon-api/blob/main/supabase_setup.sql): SQL schema · `supabase_setup.sql`
- **Radio Browser**: external radio API
- **Gemini**: recommendation API
- [Razorpay adapter](https://github.com/watermelon-music/watermelon-api/blob/main/src/services/razorpay.service.js): payment provider adapter · Named adapter differs from the documented Cashfree integration. · `src/services/razorpay.service.js`
- **Cashfree**: payment provider · Checkout, status, and webhook integration target.

### Runtime and deployment

Service startup and yt-dlp provisioning.

- [Server startup](https://github.com/watermelon-music/watermelon-api/blob/main/server.js): Node entry point · `server.js`
- [Scheduled jobs](https://github.com/watermelon-music/watermelon-api/blob/main/src/services/cronService.js): background service · `src/services/cronService.js`
- [yt-dlp provisioning](https://github.com/watermelon-music/watermelon-api/blob/main/scripts/download-ytdlp.js): build script · Downloads the executable during install or build. · `scripts/download-ytdlp.js`
- **Render / Docker**: deployment targets · Builds provision yt-dlp before starting Node.

### Other components

- **Android client**: API consumer

## Connections

- Android client → Server startup: HTTPS requests
- Server startup → Express app: boots
- Express app → Middleware boundary: applies
- Middleware boundary → API route domains: passes requests
- Express app → API route domains: mounts
- API route domains → Song controller: music requests
- Song controller → In-memory cache: reads and writes
- Song controller → yt-dlp service: searches and extracts
- yt-dlp service → yt-dlp executable: executes
- yt-dlp executable → YouTube: queries
- API route domains → Supabase: users and engagement
- Supabase schema → Supabase: defines
- API route domains → Radio Browser: radio browsing
- API route domains → Gemini: recommendations
- API route domains → Payment routes: payment endpoints
- Payment routes → Payment controller: dispatches
- Payment controller → Razorpay adapter: uses
- Razorpay adapter → Cashfree: provider target to validate
- Scheduled jobs → Supabase: background work
- Render / Docker → yt-dlp provisioning: build step
- yt-dlp provisioning → yt-dlp executable: downloads
- Render / Docker → Server startup: starts