Backend Architecture

NestJS API for the WAVIC Music Collaboration Platform

Technology Stack

Component	Technology	Purpose
Framework	NestJS 11	Modular backend framework
Runtime	Node.js 22	JavaScript runtime
Database	MongoDB (Mongoose 7.8)	Document database
Auth	JWT + Passport	Token-based authentication
Storage	Azure Blob Storage	Audio files and images
Payments	Stripe	Subscriptions and billing
Email	Postmark	Transactional emails
Scheduling	@nestjs/schedule	Cron jobs (trash cleanup)
Security	Helmet + ThrottlerGuard + bcrypt 6	HTTP hardening, rate limiting, password hashing

---

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      WAVIC API (NestJS)                     │
├─────────────────────────────────────────────────────────────┤
│  Controllers  →  Services  →  Repositories  →  MongoDB      │
│       ↓              ↓                                       │
│  Guards      ImageService ← Sharp (image processing)        │
│  (JWT Auth)  StorageService ← Azure Blob Storage             │
└─────────────────────────────────────────────────────────────┘
                           ↓
              ┌────────────────────────┐
              │   External Services    │
              ├────────────────────────┤
              │ • Azure Blob Storage   │
              │ • Stripe API           │
              │ • Postmark Email       │
              │ • MongoDB Atlas        │
              └────────────────────────┘

---

Module Structure

src/modules/
├── azure/           # Azure Blob Storage integration
├── artistSpace/     # Artist workspace management
├── collaboration/   # Team invitations & permissions
├── comment/         # Track comments/markers
├── db/              # Database connection
├── email/           # Email notifications (Postmark)
├── file/            # File metadata management
├── image/           # Image processing (Sharp)
├── jwt/             # JWT authentication
├── link/            # Shareable links
├── notification/    # In-app notifications
├── project/         # Project/album management
├── search/          # Global search
├── storage/         # Storage abstraction layer
├── subscription/    # Stripe subscriptions & plans
├── track/           # Core track management
├── trashSpace/      # Soft delete with 30-day recovery
└── user/            # User management

---

Key Modules

ImageService

Handles all image processing using Sharp:

• Thumbnail generation (150x150 cropped)
• Medium variant (600px width)
• WebP conversion for optimized delivery
• Blur placeholder generation

See 02-IMAGE-OPTIMIZATION.md for details.

StorageService

Abstract storage layer that:

• Wraps Azure Blob Storage operations
• Generates SAS URLs for secure access
• Signs URLs in API responses automatically
• Applies 1-year cache headers to uploads

Authentication Flow

1. Login Request → POST /user/login
2. Validate credentials → bcrypt comparison
3. Generate JWT → signed with JWT_SECRET
4. Return token → { user, token }
5. Subsequent requests → Authorization: Bearer <token>
6. JWT Guard validates → extracts user from token

---

Environment Variables

# Database
MONGODB_URI=mongodb+srv://...

# Authentication
JWT_SECRET=your-secret-key
ORIGIN=http://localhost:3000

# Azure Storage
AZURE_STORAGE_ACCOUNT_NAME=sonnancewebappstorage00
AZURE_STORAGE_ACCOUNT_KEY=...
AZURE_STORAGE_CONTAINER_NAME=uploads

# Email (Postmark)
POSTMARK_TOKEN=...
SENDER_EMAIL=noreply@wavic.io

# Stripe
STRIPE_API_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

---

Data Flow

Client Request
      ↓
┌─────────────────┐
│  JWT AuthGuard  │ ← Validates token
└────────┬────────┘
         ↓
┌─────────────────┐
│   Controller    │ ← Parses request
└────────┬────────┘
         ↓
┌─────────────────┐
│    Service      │ ← Business logic
└────────┬────────┘
         ↓
┌─────────────────┐
│   Repository    │ ← Data access
└────────┬────────┘
         ↓
┌─────────────────┐
│  SignUrls       │ ← Interceptor signs Azure URLs
│  Interceptor    │
└────────┬────────┘
         ↓
    API Response

---

API Endpoints Summary

Module	Method	Endpoint	Description
User	POST	/user/login	Login
User	POST	/user/register	Register
ArtistSpace	GET	/artist	List artist spaces
Project	GET	/project/space/:id	Projects by space
Track	POST	/track	Upload track
Search	GET	/search?query=	Global search
Trash	GET	/trash	List trashed items

---

Last Updated: February 2026