soundscape

Music social platform with real-time listening, calibrated ratings, lane-based discovery, and a simulated music market.

Features

• Real-time Listening — See what friends are playing (3-tier tracker: webhooks → client detection → adaptive polling)
• Album Ratings — Rate albums 0-10, build your catalog
• Music Stock Market — Invest in artists, albums, songs with real risk/reward
• Smart Queue — Albums you've heard but haven't rated
• Discovery Lanes — Start Here, Just Dropped, Deep Cuts, Genre Essentials, Rising This Week, Because You Loved, People Like You, Expand Your Taste, Your Friends Into
• Social Feed — Unified feed with type/source filters
• Insights — Data-driven rating analytics

What's New (Q1 2026)

• Wrapped 2025 — reels, rewards, notifications, and shareable cards
• Deep Dive Analytics — lane-level aggregation and tabbed UI
• Share Studio — generates post/share cards with export flows
• Profile Customization — themes, avatars, badges plus Target Card selector & odds transparency for collectibles
• Multi-platform Split — new @soundscape/core, @soundscape/platform-web, and @soundscape/ui packages to serve web + future mobile

Tech Stack

Layer	Technology
Frontend	Next.js 14, React 18, TailwindCSS
API	tRPC v10, Zod validation
Database	PostgreSQL, Prisma ORM
Auth	Clerk
Caching	Redis (ioredis)
Jobs	BullMQ
Logging	Pino
Testing	Vitest

Architecture Pillars

This project follows FAANG-level engineering standards:

1. Security First

• Auth on every protected route via Clerk
• Input validation with Zod on all endpoints
• Rate limiting middleware (sliding window)
• Protected procedures for authenticated actions

2. Fail Fast

• Early validation before processing
• Typed errors with meaningful codes
• Assertion helpers (assertOrThrow)

3. Scalable

• Stateless API design
• Redis for caching and rate limiting
• Connection pooling for database
• 3-tier listening tracker (webhooks → client-side → polling)

4. Observable

• Structured JSON logging (Pino)
• Request ID tracing
• Health check endpoints (/health/live, /health/ready)
• Performance logging on every request

5. Tested

• Unit tests for business logic
• Integration tests for API routes
• Test database isolation

6. Clean Architecture

• Monorepo with clear package boundaries
• SOLID principles
• Reusable utilities and middleware
• Consistent error handling patterns

Getting Started

Prerequisites

• Node.js 18+
• pnpm 8+
• Docker (for local DB/Redis)

Setup

1. Clone and install:

   git clone <repo>
   cd soundscape
   pnpm install

2. Start databases:

   docker compose -f docker/docker-compose.yml up -d

3. Configure environment:

   cp .env.example .env
   # Edit .env with your Clerk keys, music service credentials, etc.

4. Initialize database:

   pnpm db:generate
   pnpm db:migrate    # applies dev migrations
   pnpm db:seed       # baseline data
   # Optional demo/comprehensive datasets
   pnpm --filter @soundscape/db seed:demo
   pnpm --filter @soundscape/db seed:comprehensive

5. Run development server:

   pnpm dev

Visit http://localhost:3000

Project Structure

soundscape/
├── packages/
│   ├── core/          # Platform-agnostic business logic, schemas, utilities
│   ├── platform-web/  # Browser/Next.js adapters (storage, config, auth)
│   ├── ui/            # Shared UI primitives (web + mobile stubs)
│   ├── shared/        # Cross-package helpers usable in any runtime
│   ├── web/           # Next.js frontend (routes, components, hooks)
│   ├── api/           # tRPC API layer (routers, services, middleware)
│   └── db/            # Prisma schema & client
├── docker/           # Docker configs
│   ├── docker-compose.yml
│   └── Dockerfile
├── .github/          # CI/CD workflows
│   └── workflows/
│       └── ci.yml
├── .env.example
├── package.json
├── turbo.json
└── README.md

Key Design Decisions

Market Price Engine

• Logarithmic scaling - 1K→100K streams matters more than 1M→1.1M
• Entity-specific models:
  • Songs: High volatility (±30%/day), TikTok-driven, 2%/day decay
  • Albums: Medium volatility (±20%/day), rating-driven
  • Artists: Low volatility (±10%/day), career-trajectory based
• Real downside risk via time decay and momentum death (not just streaming drops)

No Taxes/Profit Caps

• It's play money - let people win big or lose it all
• Risk comes from price mechanics, not artificial limits

Private Investments by Default

• Trades are hidden until user explicitly shares
• Prevents social pressure and copycat behavior

3-Tier Listening Tracker

• Tier 1: Webhooks (40% users) - zero polling
• Tier 2: Client-side detection (45%) - batched syncs
• Tier 3: Adaptive polling (15%) - rate-limited fallback

Scripts

# Development
pnpm dev              # Start all packages in dev mode
pnpm build            # Build all packages
pnpm test             # Run all tests
pnpm test:coverage    # Run tests with coverage
pnpm lint             # Lint all packages
pnpm typecheck        # TypeScript check (strict mode)
pnpm typecheck:packages # TypeScript check across packages

# Database
pnpm db:generate      # Generate Prisma client
pnpm db:migrate       # Create and apply migration
pnpm db:seed          # Seed database with test data
pnpm db:setup         # Full setup: generate + migrate + seed
pnpm db:studio        # Open Prisma Studio
pnpm db:reset         # Reset database (drops all data)
pnpm dev:fresh        # Reset DB + seed + start dev
pnpm --filter @soundscape/db seed:demo            # Demo dataset
pnpm --filter @soundscape/db seed:comprehensive   # Large showcase dataset

# Code Quality
pnpm audit:dead-code  # Generate dead code audit report
pnpm audit:types      # Scan for type safety violations
pnpm audit:types:check # Check against baseline (regression gate)
pnpm repair:types     # Fix type build issues

# E2E / Ops
pnpm e2e:smoke        # Critical path smoke tests
pnpm e2e:full         # Full Playwright suite
pnpm e2e:ui           # Playwright UI mode
pnpm e2e:debug        # Debug a specific spec interactively
pnpm execute <plan>   # Execute a phase plan script

Music Service Integration

Live Listening & Metadata:

• ✅ Last.fm (primary) — OAuth, real-time scrobbles, metadata search, Redis caching with rate limits
• 🚧 Spotify — On hold (provider-side security issues, monitored for reopen)
• 🔜 Apple Music — Planned post-v1 (Phase 7.x roadmap)

Multi-service roadmap keeps Last.fm as source of truth until Spotify/Apple are re-enabled.

Environment Variables

See .env.example for all required variables:

Variable	Description
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection string
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Clerk frontend key
CLERK_SECRET_KEY	Clerk backend key
LASTFM_API_KEY	Last.fm API key (primary music service)
LASTFM_API_SECRET	Last.fm API secret
LASTFM_REDIRECT_URI	Last.fm OAuth callback URL
SPOTIFY_CLIENT_ID	Spotify OAuth client ID (optional)
SPOTIFY_CLIENT_SECRET	Spotify OAuth secret (optional)

Deployment

Docker

docker build -f docker/Dockerfile -t soundscape .
docker run -p 3000:3000 --env-file .env soundscape

Vercel (Frontend)

vercel --prod

Railway/Render (Full Stack)

Use the included Dockerfile with PostgreSQL and Redis addons.

Quality Gates & Health (Feb 2026)

• Type Safety — Phase 34 strict-mode burndown complete; current baseline: 789 tracked violations (pnpm audit:types:check enforces no regressions).
• Dead Code — pnpm audit:dead-code generates .planning/phases/done/10.6-maintainability-check/DEAD_CODE_AUDIT.md (knip).
• Reliability — Phase 40 hardened tRPC routing, rate limits, and Last.fm primary elevation; kill-switch drills documented in KILL-SWITCH-INVENTORY.md.

Contributing

1. Create a feature branch
2. Make changes with tests
3. Ensure pnpm test and pnpm typecheck pass
4. Submit PR

License

MIT