VOLT API

Backend API for VOLT, built with TypeScript, Express, MongoDB (Mongoose), Socket.IO, and integrated services (Stripe, Firebase, Redis, AWS S3, Cloudflare Stream, OAuth providers).

What This Project Is About

VOLT API is the backend for a social live-streaming platform.
It powers user identity, profiles, social graph (follow/block), posts/reposts/comments, real-time streaming, chat, virtual gifts, feed delivery, moderation/reporting, notifications, and wallet top-ups.

The API is responsible for:

• Authentication and session/token lifecycle
• User and creator profile management
• Social interactions (follow, block, report)
• Content interactions (posts, comments, likes, reposts)
• Live stream lifecycle and participant/moderation operations
• Messaging and conversation inbox
• Admin moderation and analytics flows
• In-app economy support (coin packages, payments, gifts)

Project Status

This project is currently in active development.

• APIs and internals can change between commits.
• Some integrations are optional and enabled only when relevant environment variables are set.
• Expect occasional breaking changes while features stabilize.

Tech Stack

• TypeScript (strict), Node.js (ESM)
• Express 5
• MongoDB + Mongoose
• Socket.IO
• Redis (ioredis)
• JWT + Passport OAuth (Google/Facebook/Apple)
• Stripe webhooks and payments
• Firebase Admin (notifications)
• AWS S3, Cloudflare Stream
• Sentry monitoring

Getting Started

Prerequisites

• Node.js 18+ (Node.js 20+ recommended)
• npm
• MongoDB instance/connection string
• Redis (for full local parity)

Installation

npm install

Environment Setup

1. Copy config.env.example to config.env at the repository root.
2. Fill required values for your local setup.
3. Keep NODE_ENV=development for local development.

The application loads:

• config.env in development
• .env in production

Running Locally

Development

npm run start:dev

This starts the API with tsx watch and typecheck preflight (prestart:dev).

Health check:

• GET http://localhost:<PORT>/api/health

Production Build + Start

npm run build
npm run start

Scripts

For the full and up-to-date list of scripts, see:

• package.json -> scripts

The most common local commands are:

• npm run start:dev for development
• npm run build && npm run start for production-style run

Environment Variables

Do not hardcode env values in documentation or code.

Use these files as the source of truth:

• config.env.example for available keys and local template values
• src/config/config.ts for how variables are loaded and used at runtime

API Surface (High-Level)

Mounted route groups:

• /api/auth
• /api/users
• /api/posts
• /api/stream
• /api/admins
• /api/notifications
• /api/ads
• /api/conversations
• /api/pk
• /api/gifts
• /api/feed
• /api/coin-packages
• /api/payments

Stripe webhook endpoint:

• POST /api/payments/webhook (expects raw body)

Implemented Parts and Their Function

• Auth (/api/auth) - Sign up, login, password reset/OTP, token refresh, logout, and social OAuth login entry points.
• Users (/api/users) - Profile CRUD, profile media uploads, account support contact, user search, public profile access, user/post reporting, followers/following, and block/unblock.
• Posts (/api/posts) - Post engagement actions: comments, likes/unlikes, repost/unrepost.
• Streams (/api/stream) - Live stream start/end/join, participant listing, stream search, stream reporting, moderator and mute management, and stream gift sending.
• Conversations (/api/conversations) - Direct chat creation/inbox, mute/delete chat, send message (with optional image), fetch/search messages.
• Feed (/api/feed) - Reels feed retrieval for authenticated users.
• PK (/api/pk) - Returns currently available streamers for PK invite flows.
• Notifications (/api/notifications) - FCM token registration, notification preferences, read/unread operations, and notification deletion.
• Coin Packages (/api/coin-packages) - Lists active purchasable coin packages.
• Payments (/api/payments) - Payment intent creation and intent status checks for wallet top-ups.
• Payment Webhook (/api/payments/webhook) - Receives Stripe webhook events using raw request body.
• Gifts (/api/gifts) - Public gift catalog retrieval plus admin-only create/update/delete gift management.
• Ads (/api/ads) - Admin ad management (create/read/update/delete) with upload support; user-facing ad retrieval is exposed via users routes.
• Admin (/api/admins) - Admin-only analytics, moderation queues (reported users/posts/streams), stream control, and user lifecycle actions.

Project Structure

src/
  app.ts                  Express app setup, middleware, route mounting
  server.ts               Startup flow (DB, seed jobs, Socket.IO, HTTP server)
  socket.ts               Socket initialization
  config/                 Env, DB, third-party clients/config
  controllers/            HTTP handlers
  services/               Business logic
  models/                 Mongoose schemas/models
  routes/                 Route modules
  middleware/             Auth/validation/guards
  mappers/                DTO/data shaping
  DTOs/                   Data contracts
  utils/                  Shared utilities

Security Notes

• Never commit real secrets (config.env, .env, keys, service accounts).
• Use test credentials in development (especially payment providers).
• Rotate credentials immediately if accidental exposure occurs.

Contribution Notes

• Keep changes scoped and feature-focused.
• Follow existing route -> controller -> service -> model layering.
• Run checks before opening a PR:

npm run typecheck
npm run lint
npm run build