🚀 RatesSpot API - Developer Onboarding

Welcome to the RatesSpot team! This guide will get you up and running with our comprehensive booking API platform.

📋 Pre-requisites

Required Software

• Node.js 18+ - Download here
• PostgreSQL 14+ - Download here
• Git - Download here
• Docker (optional) - Download here

Recommended Tools

• VS Code with extensions:
  • Prisma
  • TypeScript and JavaScript Language Features
  • ESLint
  • GitLens
• Postman - For API testing
• TablePlus or pgAdmin - Database GUI

🛠️ Local Setup

1. Clone the Repository

git clone https://github.com/your-org/ratesspot-api.git
cd ratesspot-api

2. Install Dependencies

npm install
cd website && npm install && cd ..

3. Environment Configuration

cp .env.example .env

Edit .env with your local configuration:

• Database URL for local PostgreSQL
• Get Clerk keys from team admin
• Optional: Stripe test keys, Twilio, etc.

4. Database Setup

# Generate Prisma client
npm run db:generate

# Run migrations
npm run db:migrate

# Seed test data (optional)
npm run db:seed

5. Start Development Server

npm run dev

The API will be running at http://localhost:3001

6. Generate Documentation

npm run docs:generate
npm run docs:serve

Documentation available at http://localhost:3001/docs

🏗️ Project Architecture

Directory Structure

ratesspot-api/
├── src/
│   ├── controllers/     # API request handlers
│   ├── middleware/      # Express middleware
│   ├── routes/         # API route definitions
│   ├── services/       # Business logic
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Helper functions
│   └── app.ts          # Express app setup
├── prisma/
│   ├── schema.prisma   # Database schema
│   └── migrations/     # Database migrations
├── scripts/            # Build and utility scripts
├── website/            # Docusaurus documentation site
├── tests/              # Test files
└── docs/               # Auto-generated API docs

Tech Stack

• Runtime: Node.js + TypeScript
• Framework: Express.js
• Database: PostgreSQL + Prisma ORM
• Authentication: Clerk
• Payments: Stripe
• Documentation: Auto-generated + Docusaurus
• Testing: Jest + Supertest
• Deployment: Railway

🔄 Development Workflow

Branch Naming Convention

feature/add-loyalty-system
fix/booking-validation-bug
hotfix/critical-payment-issue
chore/update-dependencies
docs/api-reference-update

Git Workflow

1. Create branch from develop

   git checkout develop
   git pull origin develop
   git checkout -b feature/your-feature-name

2. Make changes and commit

   git add .
   git commit -m "Add loyalty points calculation"

3. Push and create PR

   git push origin feature/your-feature-name

   Create PR targeting develop branch

4. Code review → Merge → Deploy

Pre-commit Hooks

Our Husky setup automatically:

• ✅ Regenerates API documentation
• ✅ Runs linting and type checking
• ✅ Stages updated docs

📝 Development Guidelines

Code Style

# Lint your code
npm run lint

# Auto-fix issues
npm run lint:fix

# Type check
npm run type-check

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

API Development

1. Routes: Define in src/routes/
2. Controllers: Handle requests in src/controllers/
3. Services: Business logic in src/services/
4. Types: TypeScript definitions in src/types/

Example new endpoint:

// src/routes/newFeature.ts
router.post('/api/new-feature', clerkAuthMiddleware, createNewFeature);

// src/controllers/newFeatureController.ts
export const createNewFeature = async (req: Request, res: Response) => {
  // Controller logic
};

// src/services/newFeatureService.ts
export class NewFeatureService {
  // Business logic
}

Database Changes

# 1. Update schema.prisma
# 2. Generate migration
npx prisma migrate dev --name add_new_feature

# 3. Generate client
npm run db:generate

🧪 Testing Your Changes

API Testing

# Download Postman collection
curl -o ratesspot.json https://api.ratesspot.com/docs/download/postman

# Or use local docs
npm run docs:serve
# Visit http://localhost:3001/docs

Database Testing

# View data
npm run db:studio

# Reset database
npm run db:reset

# Re-seed data
npm run db:seed

📊 Understanding the Codebase

Key Features

• 431 API endpoints across all business domains
• Multi-location support with location-specific pricing
• Advanced payment flows with Stripe integration
• Team management with role-based permissions
• Customer loyalty programs
• Real-time analytics and monitoring

Important Files

• src/app.ts - Express app configuration
• src/middleware/auth.ts - Authentication middleware
• src/services/bookingService.ts - Core booking logic
• src/services/paymentService.ts - Payment processing
• prisma/schema.prisma - Database schema

Auto-Generated Documentation

Our docs are generated automatically from:

• Route definitions
• API usage metrics
• Response schemas
• Test collections

🚀 Deployment

Staging Environment

• URL: https://staging-api.ratesspot.com
• Deployment: Automatic on develop branch push
• Database: Staging PostgreSQL instance

Production Environment

• URL: https://api.ratesspot.com
• Deployment: Automatic on main branch push
• Database: Production PostgreSQL instance

CI/CD Pipeline

1. PR Creation → Quality checks run
2. Merge to develop → Deploy to staging
3. Merge to main → Deploy to production
4. Documentation updates automatically

🆘 Getting Help

Team Communication

• Slack: #ratesspot-dev channel
• Daily Standups: 9:00 AM EST
• Code Reviews: Required for all PRs

Common Issues

Database connection error:

# Check PostgreSQL is running
brew services start postgresql

# Verify connection string in .env

Prisma client out of sync:

npm run db:generate

TypeScript errors:

npm run type-check
# Fix type issues before committing

Tests failing:

npm test -- --verbose
# Check specific test failures

Resources

• API Documentation: api.ratesspot.com/docs
• Postman Collection: Auto-downloads from docs
• Prisma Docs: prisma.io/docs
• Stripe API: stripe.com/docs/api

🎯 Your First Task

Quick Win: Add Your Info

1. Update team page in documentation
2. Add your photo to website/static/img/team/
3. Create PR following our workflow
4. Get familiar with code review process

Suggested Learning Path

1. Week 1: Set up environment, understand architecture
2. Week 2: Make small bug fixes, add tests
3. Week 3: Implement new feature end-to-end
4. Week 4: Work on larger project with mentorship

📚 Additional Resources

External Learning

• TypeScript Handbook
• Express.js Guide
• Prisma Tutorial
• Testing with Jest

Internal Knowledge Base

• Architecture Decisions: /docs/architecture/
• API Design Guidelines: /docs/api-guidelines.md
• Database Patterns: /docs/database-patterns.md
• Security Guidelines: /docs/security.md

Welcome to the team! 🎉

Questions? Reach out in #ratesspot-dev or schedule time with your mentor.