Atmosphere API v2

Node.js/TypeScript API migration from Rails, built with Fastify, Prisma, and PostgreSQL.

Tech Stack

• Runtime: Node.js 18+
• Framework: Fastify
• ORM: Prisma
• Database: PostgreSQL
• Language: TypeScript
• Authentication: JWT + API Keys

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• PostgreSQL database
• Environment variables configured (see .env)

Setup

1. Install dependencies:

   npm install

2. Configure environment variables: Create a .env file in the root directory:

   DATABASE_URL="postgresql://user:password@localhost:5432/theatmosphere_db"
   JWT_SECRET="replace-with-a-long-random-secret"
   PORT=3000

3. Generate Prisma Client:

   npm run prisma:generate

Quick Reference

Most Common Commands:

# Initial setup for a new empty database (migrate + seed) — preferred
npm run db:setup

# Reset with migrations (⚠️ deletes all data)
npm run db:reset:migrate

# Quick push without migration history (dev escape hatch)
npm run db:init

# Run seeds only
npm run prisma:seed

# View database in browser
npm run prisma:studio

# Create a new migration after schema.prisma changes
npm run prisma:migrate

Database Management

Schema bootstrap is driven by Prisma migrations under prisma/migrations/ (currently a single 20260730000000_init baseline that matches schema.prisma, including the vector extension and audio-embedding HNSW index). You do not need to copy a production database to stand up a fresh dev environment.

Initial Setup

Option 1: Using Migrations (Recommended)

# Apply baseline migration + seed
npm run db:setup

Equivalent to prisma migrate deploy followed by seed. Requires an empty Postgres database and the pgvector extension available on the host.

Option 2: Using db push (Quick Development Escape Hatch)

# Push schema directly (no migration history)
npm run db:init

Prefer migrations for anything you want to share across environments.

If a database already has the full schema (e.g. from an older db push) but no migration history, mark the baseline as applied instead of re-running it:

npx prisma migrate resolve --applied 20260730000000_init

Common Database Operations

Reset Database (Drop, Create, Push Schema, Seed):

npm run db:reset

This will:

• Drop the database
• Recreate it
• Push schema directly (no migration history)
• Seed with initial data

Reset Database with Migrations:

npm run db:reset:migrate

This will:

• Drop the database
• Recreate it
• Apply migrations from prisma/migrations
• Seed with initial data

Deploy Migrations (Production / shared envs):

npm run prisma:migrate:deploy

Pull Schema from Database:

npm run prisma:db:pull

Useful when the database schema has been changed externally.

View Database in Browser:

npm run prisma:studio

Opens Prisma Studio at http://localhost:5555

Manual Database Operations

Drop Database:

# Connect to PostgreSQL and drop the database
psql -U postgres -c "DROP DATABASE IF EXISTS theatmosphere_db;"

Create Database:

psql -U postgres -c "CREATE DATABASE theatmosphere_db;"

Reset Migrations:

# This will drop the database, recreate it, and apply all migrations
npm run prisma:migrate:reset

Create a New Migration:

npm run prisma:migrate
# Follow the prompts to name your migration

Development

Start Development Server:

npm run dev

Start with Nodemon:

npm run server

Type Check:

npm run typecheck

Build for Production:

npm run build

Start Production Server:

npm start

Seeding

Run All Seeds:

npm run prisma:seed

Seed File Structure: Seeds are organized in chunks following the Rails seed order:

• Chunk 1: Users, User Images, User Videos
• Chunk 2: Relationships, Friendships, Posts, Chat, Reactions
• Chunk 3: Music, Song Profiles, Album Profiles, Queue Songs, User Libraries, Song Plays
• Chunk 4: Atmo Radio Stations, Addresses, Accomplishments, Notifications
• Chunk 5: Ads, Contests, Directory, Events, Ops Pages, Plans
• Chunk 6: Products, Orders, Invoices, Transactions, Venues, AMI, Points Transactions, Dashboards

Seed Data Location: Seed JSON files are located in lib/seed_data/dev/

Idempotent Seeds: All seeds are designed to be idempotent - you can run them multiple times without creating duplicates. They check for existing records before creating new ones.

Seed Helpers: Use prisma/seedHelpers.ts for idempotent seed operations:

import { findOrCreate } from '../seedHelpers';

const user = await findOrCreate(
  prisma.users,
  { email: '[email protected]' },
  { email: '[email protected]', name: 'User Name' },
  'User'
);

Testing

Run Tests:

npm test

Run Tests in Watch Mode:

npm run test:watch

Project Structure

theatmosphere_v2/
├── prisma/
│   ├── schema.prisma          # Database schema
│   ├── seed.ts                # Main seed orchestrator
│   ├── seeds/                 # Individual seed files
│   └── migrations/            # Database migrations
├── src/
│   ├── routes/                 # API route handlers
│   ├── controllers/           # Controller classes
│   ├── middleware/            # Middleware (auth, etc.)
│   ├── plugins/               # Fastify plugins
│   └── server.ts              # Main server file
├── lib/
│   └── seed_data/             # JSON seed data files
└── dist/                      # Compiled TypeScript output

API Documentation

API endpoints follow the Rails API structure:

• Base URL: http://localhost:3000/api/v1
• Authentication: JWT token in Authorization header or API key in x-api-key header

Troubleshooting

Database Connection Issues:

• Verify DATABASE_URL in .env is correct
• Ensure PostgreSQL is running
• Check database exists: psql -U postgres -l

Migration Issues:

• Fresh empty DB: npm run db:setup (requires pgvector on Postgres)
• Existing schema without migration history: npx prisma migrate resolve --applied 20260730000000_init
• If migrations are badly out of sync, use npm run db:reset:migrate (⚠️ deletes all data)
• To pull schema from existing database: npm run prisma:db:pull
• Note: the baseline migration adds an HNSW index on song_profiles.audio_embedding that is not expressed in schema.prisma; leave it alone when generating new migrations

Seed Issues:

• Seeds are idempotent - safe to run multiple times
• If seed fails, check error message for specific model/field issues
• Verify JSON files exist in lib/seed_data/dev/

Type Errors:

• Run npm run prisma:generate after schema changes
• Run npm run typecheck to verify TypeScript compilation

Environment Variables

Required environment variables:

• DATABASE_URL - PostgreSQL connection string
• JWT_SECRET - Secret key for JWT token signing
• PORT - Server port (default: 3000)

Optional environment variables:

• NODE_ENV - Environment (development, production, test)
• AD_PORTAL_URL - Ad Portal API URL
• MONGODB_URI - MongoDB connection for AMI apps

License

ISC