CTRL Audio API - Backend Analysis

NestJS Backend for CTRL Audio Music Collaboration Platform

This document analyzes the ctrl-audio-back repository, comparing the master and dev branches to understand available features and pending merges.

---

📊 Branch Status Summary

Branch	Status	Description
master	Production	Current stable version
dev	Development	56 files changed, significant new features
emran/search	Feature	Merged into dev - search functionality

Commits Ahead on dev

The dev branch is significantly ahead of master with these major features:

• ✅ Global search functionality
• ✅ Trash/Recycle bin with 30-day auto-delete
• ✅ Subscription tier enforcement
• ✅ Onboarding flow
• ✅ Track notes field
• ✅ Free plan limitations
• ✅ Soft delete recovery

---

🏗️ Tech Stack

Component	Technology
Framework	NestJS 9.x
Language	TypeScript
Database	MongoDB (Mongoose)
Auth	JWT + Passport
Storage	AWS S3
Payments	Stripe
Email	Postmark
Scheduling	@nestjs/schedule (Cron jobs)

---

📁 Module Structure

src/modules/
├── artistSpace/       # Artist workspace management
├── aws/               # S3 file storage
├── collaboration/     # Team invitations & permissions
├── comment/           # Track comments/markers
├── db/                # Database connection
├── email/             # Email notifications (Postmark)
├── file/              # File management
├── jwt/               # JWT authentication
├── link/              # Shareable links
├── notification/      # In-app notifications
├── project/           # Project/album management
├── search/            # 🆕 Global search (dev only)
├── subscription/      # Stripe subscriptions & plans
├── track/             # Core track management
├── trashSpace/        # 🆕 Trash/recycle bin (dev only)
└── user/              # User management

---

🆕 New Features on dev Branch

1. Search Module

Location: src/modules/search/

Global search across all resources:

// Searches across:
// - Artist Spaces (by name)
// - Projects (by name)
// - Tracks (by name)

async search(userId: string, query: string) {
  const artistSpaces = await this.artistService.findByQuery(userId, query);
  const projects = await this.projectService.findByQuery(userId, query);
  const tracks = await this.trackService.findByQuery(userId, query);
  // Returns unified SearchItem[] array
}

2. Trash Space Module

Location: src/modules/trashSpace/

Soft delete with 30-day recovery:

// Features:
// - Soft delete for all resources
// - List all trashed items
// - Restore items
// - Auto-delete after 30 days (Cron job)

@Cron(cronScheduleTime)
async deleteOldItems() {
  // Permanently deletes items older than 30 days
}

3. Subscription Tiers & Limits

Location: src/modules/subscription/models/subscription.data.ts

Plan	Storage	Seats	Tracks	Versions/Track
Free	50 GB	1	15	2
Explorer	200 GB	3	-	-
Pro	1 TB	4	Unlimited	Unlimited
Diamond	4 TB	Unlimited	-	-

4. Track Enhancements

New fields added to Track schema:

// New fields on dev:
notes?: string;              // Track notes
label?: string;              // Record label
genre?: string;              // Music genre
releaseDate?: Date;          // Release date
releaseStatus?: ReleaseStatus;  // Publishing status
ISRC?: string;               // International Standard Recording Code
isFinalName: boolean;        // Name finalized
finalNameUpdatedAt: Date;    // When name was finalized

Release status types:

enum TrackReleaseStatus {
  NOT_APPROVED = 'Not approved',
  UNDER_REVIEW = 'Under review', 
  NO_STATUS = 'No status',
}

5. User Enhancements

New user fields:

// New fields on dev:
recentAccess: string[];      // Recently accessed resources
recentSearches: string[];    // Search history
subscription: SubscriptionPlanTemplate;  // User's plan

6. Onboarding Flow

New endpoints for user onboarding:

• GET /track/onboarding - Get onboarding track
• POST /track/onboarding - Create first track during onboarding

7. Enhanced Collaboration Roles

enum Role {
  Owner = 'owner',
  Admin = 'admin',
  Editor = 'editor',
  Viewer = 'viewer',
}

---

🔌 API Endpoints Summary

Existing Endpoints (master)

Module	Method	Endpoint	Description
User	POST	/user/register	Register user
User	POST	/user/login	Login
User	POST	/user/auth/google	Google OAuth
ArtistSpace	GET	/artist-space	List spaces
ArtistSpace	POST	/artist-space	Create space
Project	GET	/project	List projects
Project	GET	/project/space/:id	Projects by space
Track	GET	/track	User's tracks
Track	GET	/track/project/:id	Tracks by project
Track	POST	/track	Upload track
Collaboration	POST	/collaboration/invite/*	Send invitations

New Endpoints (dev only)

Module	Method	Endpoint	Description
Search	GET	/search?query=	Global search
Track	GET	/track/all-tracks	All tracks by user
Track	GET	/track/count	Count tracks
Track	GET	/track/onboarding	Onboarding track
Track	POST	/track/onboarding	Create onboarding track
Trash	GET	/trash	List trashed items
Trash	POST	/trash/restore/:id	Restore item
Trash	DELETE	/trash/:id	Permanent delete

---

🔐 Environment Variables

# Database
MONGODB_URI=mongodb://...

# Auth
JWT_SECRET=
ORIGIN=http://localhost:3000

# Google OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URL=

# Email (Postmark)
POSTMARK_TOKEN=
SPACE_INVITATION_TEMPLATE_ID=
PROJECT_INVITATION_TEMPLATE_ID=
TRACK_INVITATION_TEMPLATE_ID=
SENDER_EMAIL=
RESET_TEMPLATE_ID=
WELCOME_TEMPLATE_ID=

# AWS S3
AWS_REGION=
BUCKET_NAME=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

# Stripe
STRIPE_API_KEY=
STRIPE_WEBHOOK_SECRET=
PRO_MONTHLY_PRICE_ID=    # New on dev
PRO_YEARLY_PRICE_ID=     # New on dev

---

📋 Merge Recommendation

Priority: HIGH - Merge dev → master

Reason: The dev branch contains production-ready features that significantly enhance the platform:

1. Search - Critical UX improvement for finding content
2. Trash Recovery - Safety net for accidental deletions
3. Subscription Limits - Necessary for monetization
4. Onboarding - Better new user experience

Pre-merge Checklist

• [ ] Review all 56 changed files
• [ ] Test subscription tier limits
• [ ] Verify Stripe webhook handling
• [ ] Test soft delete → restore flow
• [ ] Verify search indexes on MongoDB
• [ ] Update client to support new endpoints
• [ ] Update environment variables in production
• [ ] Database migration for new schema fields

---

Last Updated: January 2026