🎧 SonicApi Backend (Core Engine)

A high-performance, edge-deployed backend API powering the entire Sonic ecosystem.

🌟 Overview

SonicApi-B is the highly advanced, heavily optimized backend engine for the Sonic ecosystem. Deployed on the edge using Cloudflare Workers, it ensures near-zero latency globally.

What makes this backend truly unique is its "Edge-Vault" architecture: it uses the Telegram Bot API as a limitless, free Content Delivery Network (CDN) to store and stream high-quality audio and video seamlessly to the frontend, bypassing traditional expensive storage solutions.

✨ Deep Dive: Features & Architecture

1. 🚀 Multi-Layered Edge Caching (L1 to L4)

To achieve sub-millisecond response times and drastically reduce database hits, the engine uses a 4-tier cache:

• L1 (RAM): Isolate-level memory caching for instantaneous hits.
• L2 (Cloudflare KV): Global edge caching for frequently requested data (1-year TTL).
• L3 (Upstash Redis): High-speed, centralized caching for search semaphores and active streams.
• L4 (Cloudflare D1): Edge SQL cache for rapid Telegram file_id lookups.
• Fallback: MongoDB is used for permanent storage of rich metadata and API keys.

2. 🗄️ "Edge-Vault" & Telegram CDN

Instead of storing gigabytes of media on expensive AWS S3 buckets, SonicApi-B orchestrates a massive background "Vaulting" process:

• When a user requests a song, the API fetches it and securely uploads it to a private Telegram channel via a bot.
• The Telegram file_id and raw CDN paths are cached.
• Subsequent requests instantly pipe the stream directly from Telegram's incredibly fast servers directly to the user.

3. ⚙️ Asynchronous Processing & Proxies

• Upstash QStash: Used to handle background tasks asynchronously. If a song needs to be downloaded and uploaded to the Telegram Vault, QStash handles it in the background so the user's API request doesn't timeout.
• HuggingFace (HF) Proxies: For heavy tasks (videos or files > 3 minutes), the worker offloads the downloading and streaming to a custom MTProto proxy hosted on HuggingFace Spaces.

4. 🛡️ Security & DDoS Protection

• API Key Authentication: Strictly enforced API key checks stored in MongoDB and cached in KV.
• Admin-Priority Routes: Special bypasses and unlimited rate-limits for admin keys.
• DDoS & Rate Limiting: Powered by Upstash Redis, the API enforces strict quotas (e.g., 50 requests/hour) and detects aggressive bursts to automatically block abusive traffic.

5. 🔍 Multi-Strategy Scraping

If a track isn't found in the database, the API dynamically falls back through multiple scraping strategies to ensure a 99.9% uptime and success rate, including oEmbed lookups, robust internal HTML scrapers, and external Vercel APIs.

🚀 Tech Stack

• Platform: Cloudflare Workers (Hono / TypeScript)
• Primary Database: MongoDB
• Edge SQL: Cloudflare D1
• Cache & Queue: Upstash Redis & QStash
• Storage / CDN: Telegram Bot API
• Proxy: HuggingFace Spaces

⚙️ Local Setup & Configuration

1. Clone the repository:

   git clone https://github.com/urstark/SonicApi-B.git
   cd SonicApi-B

2. Install dependencies:

   npm install

3. Environment Variables: Rename sample.env to .env or configure your wrangler secrets:

   # Add your specific configurations here
   MONGO_URL=...
   REDIS_URL=...
   REDIS_TOKEN=...
   TELEGRAM_BOT_TOKEN=...
   TELEGRAM_CHAT_ID=...
   QSTASH_TOKEN=...
   # (Refer to sample.env for the full list)

4. Run the development server:

   npm run dev

⚖️ License

This project is licensed under the GNU General Public License v3.0 (GPLv3).

This means you are free to use, modify, and distribute this software, but any modifications or derivative works must also be open-sourced under the same GPLv3 license, and proper credit must be given to the original author.

---

Built with passion by Stark.