Mixtape API (@mixtapelabs/api)

Express MVC service that fronts @mixtapelabs/engine and exposes REST endpoints for the Next.js frontend.

Structure

src/
 ├─ config/         # env + prisma config
 ├─ clients/        # metadata/analysis/http/stub clients
 ├─ controllers/    # HTTP controllers (e.g., SessionController)
 ├─ middleware/     # cross-cutting middleware (Cerberus/JWT auth)
 ├─ repositories/   # Prisma persistence helpers
 ├─ routes/         # Express routers
 ├─ services/       # Orchestration between engine + repo
 └─ server.ts       # Bootstrap entrypoint

Requirements

• Node.js ≥ 18
• Access to the private @mixtapelabs/engine package (local file:../engine or GitHub Packages)
• PostgreSQL database (DATABASE_URL="postgresql://user:password@localhost:5432/mixtapelabs_api").
• Cerberus IAM tenant (base URL + OAuth2 client credentials) or a fallback JWT_SECRET for local testing.

Installation

npm install
npx prisma generate

Environment variables

Variable	Description
PORT	HTTP port (default 4001)
DATABASE_URL	PostgreSQL connection string (e.g., postgresql://user:pass@localhost:5432/mixtapelabs_api)
CORS_ORIGIN	Allowed origins for CORS (e.g., https://app.example.com or comma-separated list). If not set, reflects the request origin (allows all origins with credentials)
CERBERUS_BASE_URL	Cerberus IAM host (e.g., https://cerberus.example.com)
CERBERUS_CLIENT_ID	OAuth2 client ID used for token introspection
CERBERUS_CLIENT_SECRET	OAuth2 client secret used for token introspection
JWT_SECRET	Optional local fallback; enables Bearer JWT auth when Cerberus is unavailable
METADATA_SERVICE_URL / ANALYSIS_SERVICE_URL	External services when not using stubs
METADATA_SERVICE_API_KEY / ANALYSIS_SERVICE_API_KEY	Shared secrets passed via x-api-key for the respective microservices
FEEDBACK_SERVICE_URL / FEEDBACK_SERVICE_API_KEY	Required when FEEDBACK_MODE=service
FEEDBACK_MODE	openai, stub, or service
OPENAI_API_KEY	Required when FEEDBACK_MODE=openai
USE_STUB_CLIENTS	Force stub clients even if service URLs provided

Scripts

npm run dev         # ts-node-dev hot reload
npm run lint        # eslint
npm run typecheck   # tsc --noEmit
npm test            # vitest + supertest
npm run build       # tsup -> dist/
npm start           # node dist/server.js
npm run format      # prettier src/ and test/
npm run ci          # lint + typecheck + test + build
npm run docs:dev    # (from repo root) run VitePress docs

Database

• prisma/schema.prisma defines a simple Session model storing engine state JSON.
• Run migrations as needed (npx prisma migrate dev --name init).

API

POST /api/auth/login

Proxy to Cerberus IAM /v1/auth/login. Confirms credentials/MFA and returns user + organisation info (no tokens).

POST /api/auth/token

Unified token helper that proxies Cerberus /oauth2/token.

• Authorization Code (PKCE): provide grantType: "authorization_code" along with code, redirectUri, and codeVerifier.
• Client Credentials: supply grantType: "client_credentials" and an optional scope to mint machine-to-machine tokens (no end-user interaction). The API fills clientId/clientSecret from env unless you override them in the payload.

Response mirrors Cerberus (access_token, refresh_token, etc.).

GET /api/auth/me

Requires Authorization: Bearer <token>. Uses Cerberus token introspection, returns the verified user payload.

POST /api/sessions

Creates a new audio analysis session. Requires authentication.

Important: The uploadUrl must point to a publicly accessible audio file hosted on cloud storage (S3, CDN, etc.). The API does not handle file uploads directly - users must upload their files separately and provide the URL.

Body:

{
  "sessionId": "mix-42",
  "uploadUrl": "https://cdn.example.com/mix.wav",  // Must be publicly accessible HTTPS URL
  "userContext": { "daw": "Ableton Live", "genre": "House", "experienceLevel": "intermediate" }
}

The API will:

1. Extract metadata (duration, format, sample rate) via metadata service
2. Perform audio analysis (loudness, dynamics, spectrum, stereo) via analysis service
3. Generate AI feedback via feedback service (OpenAI GPT-4)
4. Store complete results in database

Response: EngineState from @mixtapelabs/engine with all analysis results. Include Authorization: Bearer <token> or authenticate via httpOnly cookie.

Security & Release

• API key middleware protects endpoints when API_KEY is set.
• Prisma client handles DB writes; sanitize tokens via environment variables.
• CI/CD should run npm run ci and npx prisma migrate deploy before npm start.

Docker Build

Build the API service for Railway deployment:

# Build with npm token for private @mixtapelabs/engine package
docker build --build-arg NPM_TOKEN=$NPM_TOKEN -t mixtapelabs-api .
docker run -p 8080:8080 --env-file .env mixtapelabs-api

The Dockerfile handles:

• GitHub Packages Authentication: Requires NPM_TOKEN build arg to install private @mixtapelabs/engine package
• Prisma Client Generation: Runs npx prisma generate during build
• Database Migrations: Runs npm run db:deploy on container start
• TypeScript Compilation: Builds to dist/ directory

::: tip Railway Deployment When deploying to Railway as a standalone repository:

1. Ensure Dockerfile exists in repo root (Railway auto-detects it)
2. Set NPM_TOKEN environment variable in Railway with your GitHub Personal Access Token (with read:packages scope)
3. Add database reference: DATABASE_URL=${{Postgres.DATABASE_URL}}
4. Configure service references for internal networking:
   • METADATA_SERVICE_URL=https://metadata.railway.internal
   • ANALYSIS_SERVICE_URL=https://analysis.railway.internal
5. Generate and set API keys for service authentication

The Dockerfile ensures Prisma Client is generated before runtime, preventing @prisma/client did not initialize errors. :::

Contributing & Support

• Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before submitting changes.
• Use the provided GitHub issue templates (bug/feature) and PR template to streamline reviews.
• Default CODEOWNERS: @mixtapelabs/maintainers.