🚀 Run Way API - Building a Modern SaaS Backend

A production-ready NestJS REST API with multi-tenant architecture, enterprise-grade RBAC, and scalable infrastructure.

📖 About This Project

Run Way is a comprehensive backend API designed for modern SaaS applications. Built with NestJS 11 and TypeScript, it provides a solid foundation for building multi-tenant applications with role-based access control, secure authentication, and scalable architecture patterns.

Why This Stack?

After 3+ years of full-stack development, I've learned that the best projects start with a solid foundation. This API demonstrates:

• Enterprise patterns: Multi-tenancy, RBAC, and organization-scoped data isolation
• Modern tooling: Prisma ORM, Redis caching, BullMQ queues, PostgreSQL RLS
• Security first: JWT auth, rate limiting, email verification, row-level security
• Developer experience: TypeScript, Swagger docs, Docker setup, clean architecture

---

Tech Stack

Core Framework

• NestJS 11 - Progressive Node.js framework
• TypeScript - Type-safe development
• Prisma ORM - Modern database toolkit
• PostgreSQL 15 - Robust relational database

Infrastructure

• Redis - Caching & session storage
• BullMQ - Job queue for background tasks
• Docker - Containerization
• Row-Level Security (RLS) - Database-level multi-tenancy

Security & Auth

• JWT - Access & refresh tokens
• Passport - Authentication strategies
• Bcrypt - Password hashing
• Helmet - Security headers
• Rate Limiting - DDoS protection

Communication

• Nodemailer - Email service
• Handlebars - Email templates
• Resend - Email delivery

Developer Experience

• Swagger/OpenAPI - API documentation
• ESLint - Code linting
• Prettier - Code formatting
• Jest - Testing framework

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Client Applications                   │
│              (Web, Mobile, Desktop Apps)                 │
└────────────────────┬──────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    API Gateway Layer                      │
│  • Authentication (JWT)                                  │
│  • Rate Limiting                                         │
│  • Request Validation                                    │
│  • Organization Context                                  │
└────────────────────┬──────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  Business Logic Layer                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Auth       │  │ Organizations│  │   Projects    │ │
│  │   Users      │  │   Roles      │  │   Tasks      │ │
│  │   Permissions│  │   Billing    │  │   Billing   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└────────────────────┬──────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Data Access Layer                      │
│  • Prisma ORM                                            │
│  • Row-Level Security (RLS)                              │
│  • Transaction Management                                │
└────────────────────┬──────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Infrastructure Layer                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  PostgreSQL  │  │    Redis     │  │   BullMQ     │ │
│  │  (Database)  │  │   (Cache)    │  │   (Queue)    │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘

Key Architectural Decisions

1. Multi-Tenancy via RLS

   • Database-level isolation using PostgreSQL RLS
   • Organization context enforced at query level
   • Prevents data leakage between organizations

2. Modular Architecture

   • Feature-based modules (auth, users, organizations, etc.)
   • Clear separation of concerns
   • Easy to scale and maintain

3. Permission-Based Access Control

   • Fine-grained permissions
   • Organization-scoped permissions
   • Dynamic role-permission assignments

4. Queue-Based Processing

   • Async email sending via BullMQ
   • Scalable background job processing
   • Retry mechanisms for failed jobs

---

📋 Current Features

✅ Authentication & Authorization

• User registration with email verification
• JWT-based authentication (access + refresh tokens)
• Password reset flow
• Rate limiting on sensitive endpoints
• Session management

✅ Multi-Tenant Organizations

• Create and manage organizations
• Organization membership management
• Member invitations with role assignment
• Organization-scoped data isolation
• Soft delete support

✅ Role-Based Access Control (RBAC)

• Create custom roles per organization
• Define granular permissions
• Assign permissions to roles
• Assign roles to users
• Dynamic permission checking

✅ User Management

• User profile management
• User CRUD operations
• Soft delete support
• Email verification workflow

✅ Email Services

• Email verification
• Password reset emails
• Queue-based email processing
• Handlebars email templates
• Resend integration

✅ Security Features

• Row-Level Security (RLS) in PostgreSQL
• Organization context guards
• Permission-based access control
• Request validation
• Security headers (Helmet)
• CORS configuration
• CSRF protection

---

🚀 Quick Start

Prerequisites

• Node.js (v18 or higher)
• pnpm (or npm/yarn)
• Docker and Docker Compose
• PostgreSQL 15 (via Docker)
• Redis (via Docker)

Installation

1. Clone the repository

   git clone <repository-url>
   cd run-way

2. Install dependencies

   pnpm install

3. Set up environment variables

   Create a .env file in the root directory:

   # Application
   APP_NAME=Run Way
   PORT=3000
   FRONTEND_URL=http://localhost:3000
   
   # Database
   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_USER=app_user
   DATABASE_PASSWORD=app_password
   DATABASE_NAME=mydatabase
   
   # JWT
   JWT_SECRET=your-secret-key-change-in-production
   JWT_EXPIRE_IN=3600
   JWT_REFRESH_SECRET=your-refresh-secret-key-change-in-production
   JWT_REFRESH_EXPIRE_IN=604800
   
   # Redis
   REDIS_HOST=localhost
   REDIS_PORT=6379
   
   # Email (Resend)
   RESEND_API_KEY=your-resend-api-key
   FROM_NAME=Run Way
   FROM_EMAIL=noreply@example.com
   VERIFICATION_DELAY=5000

4. Start Docker services

   docker-compose up -d

   This starts:

   • PostgreSQL (port 5432)
   • Shadow PostgreSQL (port 5433)
   • Redis (port 6379)
   • Adminer (port 8080) - Database admin UI

5. Run database migrations

   pnpm prisma migrate deploy

6. Generate Prisma Client

   pnpm prisma generate

7. Start the development server

   pnpm run start:dev

The API will be available at http://localhost:3000

Access Points

• API: http://localhost:3000
• Swagger Documentation: http://localhost:3000/api (if configured)
• Adminer (Database UI): http://localhost:8080
  • System: PostgreSQL
  • Server: db
  • Username: app_user
  • Password: app_password
  • Database: mydatabase

---

📚 API Endpoints

Authentication (/auth)

Method	Endpoint	Description	Auth Required
POST	/auth/register	Register a new user	❌
POST	/auth/login	Login user	❌
GET	/auth/profile	Get current user profile	✅
POST	/auth/refresh-token	Refresh access token	❌
POST	/auth/forget-password	Request password reset	❌
POST	/auth/reset-password	Reset password with token	❌

Users (/users)

Method	Endpoint	Description	Auth Required
GET	/users	List all users	✅
GET	/users/:id	Get user by ID	✅
POST	/users/create	Create a new user	✅
DELETE	/users/:id	Delete user	✅

Organizations (/organizations)

Method	Endpoint	Description	Auth Required	Permission Required
POST	/organizations	Create organization	✅	-
GET	/organizations/:id	Get organization by ID	✅	ORGANIZATIONS.READ
GET	/organizations/user/organizations	Get user's organizations	✅	ORGANIZATIONS.READ
DELETE	/organizations/:id	Delete organization	✅	ORGANIZATIONS.DELETE
POST	/organizations/invite-member	Invite member to organization	✅	ORGANIZATIONS.INVITE_MEMBER
GET	/organizations/:id/members	Get organization members	✅	ORGANIZATIONS.GET_MEMBERS

Roles (/roles)

Method	Endpoint	Description	Auth Required	Permission Required
GET	/roles	Get all roles	✅	ROLES.READ
POST	/roles	Create role	✅	ROLES.CREATE
PATCH	/roles/:id	Update role	✅	ROLES.UPDATE
DELETE	/roles/:id	Delete role	✅	ROLES.DELETE

Permissions (/permissions)

Method	Endpoint	Description	Auth Required	Permission Required
GET	/permissions	Get all permissions	✅	PERMISSIONS.READ
POST	/permissions	Create permission	✅	PERMISSIONS.CREATE
PUT	/permissions/:id	Update permission	✅	PERMISSIONS.UPDATE
DELETE	/permissions/:id	Delete permission	✅	PERMISSIONS.DELETE

Email (/email)

Method	Endpoint	Description	Auth Required
GET	/email/verify	Verify email with token	❌
POST	/email/resend-email-verification	Resend verification email	❌

---

🗄️ Database Schema

Core Models

• User: User accounts with email verification
• Organization: Multi-tenant organizations
• OrganizationMember: User-organization relationships with status
• Role: Organization-scoped roles
• Permission: Organization-scoped permissions
• RolePermission: Many-to-many relationship between roles and permissions
• OrganizationMemberRole: Many-to-many relationship between members and roles

Supporting Models

• EmailVerification: Email verification tokens
• PasswordReset: Password reset tokens

Security

• Row-Level Security (RLS): Database-level security for multi-tenant data isolation
• Soft Delete: deletedAt fields on User, Organization, OrganizationMember, and Role
• Indexes: Optimized indexes on foreign keys and frequently queried fields

---

🔐 Security Features

• ✅ Row-Level Security (RLS): Database-level security for multi-tenant data isolation
• ✅ JWT Authentication: Secure token-based authentication with refresh tokens
• ✅ Rate Limiting: Protection against brute force attacks
• ✅ Email Verification: Required for account activation
• ✅ Password Hashing: Bcrypt for secure password storage
• ✅ Helmet: Security headers
• ✅ CORS: Configurable cross-origin resource sharing
• ✅ Input Validation: class-validator for request validation
• ✅ Organization Context Guards: Ensure users can only access their organization's data
• ✅ Permission Guards: Fine-grained access control

---

📦 Available Scripts

# Development
pnpm run start:dev      # Start in watch mode
pnpm run start:debug    # Start in debug mode

# Production
pnpm run build          # Build for production
pnpm run start:prod     # Start production server

# Database
pnpm prisma migrate dev  # Create and apply migration
pnpm prisma generate    # Generate Prisma Client
pnpm prisma studio      # Open Prisma Studio

# Code Quality
pnpm run lint           # Run ESLint
pnpm run format         # Format code with Prettier

# Testing
pnpm run test           # Run unit tests
pnpm run test:e2e       # Run E2E tests
pnpm run test:cov       # Run tests with coverage

---

🐳 Docker Services

The docker-compose.yaml includes:

• PostgreSQL: Main database (port 5432)
• Shadow PostgreSQL: For Prisma migrations (port 5433)
• Redis: Cache and queue (port 6379)
• Adminer: Database administration UI (port 8080)

---

📖 Learning Resources

• NestJS Documentation
• Prisma Documentation
• BullMQ Documentation
• PostgreSQL RLS
• Swagger/OpenAPI

---

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Add tests if applicable
4. Ensure all tests pass
5. Submit a pull request

---

📄 License

UNLICENSED - Private project

---

Last updated: January 2025