GitHunt
YO

yoni-crypto/NodeStack

Production-ready, tenant-aware microservices platform built with Node.js and TypeScript.

fullstackmicroservicemicroservice-kickstartermicroservices-architecturemultitenancymultitenantnodejsorganizationtemplete

NodeStack

Production-ready, tenant-aware microservices platform built with Node.js and TypeScript.

Overview

NodeStack is a complete microservices platform that provides authentication, user management, tenant management, audit logging, and notifications out of the box. It's designed to be single-tenant by default but can scale to multi-tenant SaaS applications.

Architecture

Client → API Gateway (:3000) → Services → Event Bus → Workers

Services

Service Port Description
API Gateway 3000 Single entry point with auth, routing, and documentation
Auth Service 4001 Authentication, JWT tokens, user registration
User Service 4002 User profile management, roles, permissions
Tenant Service 4003 Multi-tenant management, settings
Audit Service 4004 Compliance logging, activity tracking
Notification Worker N/A Background notifications via email/SMS

Tech Stack

  • Runtime: Node.js + TypeScript
  • Framework: Fastify (high-performance, typed)
  • Database: PostgreSQL with Prisma ORM
  • Caching: Redis
  • Message Bus: NATS
  • Monorepo: Turborepo + pnpm
  • Containerization: Docker + Docker Compose

Prerequisites

Before starting, ensure you have:

  • Node.js 18+ - JavaScript runtime
  • pnpm - Package manager (faster than npm)
  • Docker - Container platform
  • Docker Compose - Multi-container orchestration
  • Git - Version control

Install Prerequisites

Node.js and pnpm

# Install Node.js (use nvm for version management)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Install pnpm
npm install -g pnpm

Docker

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose

# macOS (using Homebrew)
brew install docker docker-compose

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

Quick Start

1. Clone and Install

git clone https://github.com/yoni-crypto/NodeStack
cd nodestack
pnpm install

2. Environment Setup

Copy environment files for each service:

# Root environment
cp .env.example .env

# Service environments
cp apps/auth-service/.env.example apps/auth-service/.env
cp apps/user-service/.env.example apps/user-service/.env
cp apps/tenant-service/.env.example apps/tenant-service/.env
cp apps/audit-service/.env.example apps/audit-service/.env
cp apps/api-gateway/.env.example apps/api-gateway/.env
cp apps/notification-worker/.env.example apps/notification-worker/.env

3. Configure Environment Variables

Generate JWT Secrets

# Generate secure JWT secrets
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Update Environment Files

Edit the .env files with your specific values:

Database Configuration:

DATABASE_URL=postgresql://nodestack:password@localhost:5434/nodestack

JWT Secrets:

JWT_SECRET=your-generated-secret-here
JWT_REFRESH_SECRET=your-generated-refresh-secret-here

Service URLs:

NATS_URL=nats://localhost:4223
REDIS_URL=redis://localhost:6380

Email Service (Resend) - Optional:

RESEND_API_KEY=your-resend-api-key
RESEND_FROM=NodeStack <noreply@yourdomain.com>

SMS Service (Twilio) - Optional:

TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
TWILIO_PHONE_NUMBER=+1234567890

4. Start Infrastructure

# Start PostgreSQL, Redis, and NATS
docker-compose up -d

# Verify services are running
docker-compose ps

5. Database Setup

# Generate Prisma client and run migrations
cd packages/database
npx prisma generate
npx prisma db push
cd ../..

6. Build and Start Services

# Build all services
pnpm build

# Start all services in development mode
pnpm dev

7. Verify Setup

Health Checks

# Check API Gateway
curl http://localhost:3000/health

# Check individual services
curl http://localhost:4001/health  # Auth Service
curl http://localhost:4002/health  # User Service
curl http://localhost:4003/health  # Tenant Service
curl http://localhost:4004/health  # Audit Service

API Documentation

Open your browser and visit: http://localhost:3000/documentation

8. Test the Setup

Register a User

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123",
    "firstName": "Test",
    "lastName": "User"
  }'

Login

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

Save the returned JWT token for authenticated requests.

Get User Profile

curl -X GET http://localhost:3000/users/{userId}/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Development

Project Structure

nodestack/
├── apps/                    # Microservices
│   ├── api-gateway/        # API Gateway with routing
│   ├── auth-service/       # Authentication service
│   ├── user-service/       # User management
│   ├── tenant-service/     # Tenant management
│   ├── audit-service/      # Audit logging
│   └── notification-worker/ # Background notifications
├── packages/               # Shared packages
│   ├── core/              # Shared utilities
│   └── database/          # Database schema and client
└── docker-compose.yml     # Infrastructure services

Development Workflow

Running Individual Services

# Run specific service
pnpm dev --filter=@nodestack/auth-service

# Run multiple services
pnpm dev --filter=@nodestack/auth-service --filter=@nodestack/user-service

Database Changes

cd packages/database

# Edit schema.prisma file
# Then apply changes:
npx prisma db push
npx prisma generate

# Restart services to pick up changes

Adding New Services

  1. Create service directory in apps/
  2. Copy structure from existing service
  3. Update package.json and dependencies
  4. Add service routes to API Gateway proxy
  5. Update environment configurations

Building for Production

# Build all services
pnpm build

# Build specific service
pnpm build --filter=@nodestack/auth-service

API Documentation

Interactive API documentation is available at:
http://localhost:3000/documentation

The documentation includes:

  • All endpoints grouped by service
  • Request/response schemas
  • Authentication requirements
  • Try-it-out functionality

Authentication

Register User

POST /auth/register
{
  "email": "user@example.com",
  "password": "password123",
  "firstName": "John",
  "lastName": "Doe"
}

Login

POST /auth/login
{
  "email": "user@example.com",
  "password": "password123"
}

Using JWT Token

# Add to request headers
Authorization: Bearer <your-jwt-token>

Multi-Tenant Setup

To enable multi-tenant mode:

  1. Set MULTI_TENANT=true in environment
  2. Create tenants via API
  3. Assign users to tenants
  4. All data becomes tenant-scoped

Monitoring

Health Checks

  • /health - Service health status
  • /health/ready - Readiness probe

Audit Logs

All API requests are automatically logged for compliance.

Correlation Tracking

Each request gets a correlation ID for distributed tracing.

Notifications

The platform supports:

  • Email notifications via Resend
  • SMS notifications via Twilio
  • Event-driven delivery
  • Multiple notification channels

Email Setup (Optional)

  1. Sign up at https://resend.com
  2. Get your API key
  3. Update .env files with RESEND_API_KEY

SMS Setup (Optional)

  1. Sign up at https://twilio.com
  2. Get your credentials
  3. Update .env files with Twilio credentials

Security Features

  • JWT-based authentication
  • Role-based access control (RBAC)
  • Tenant isolation
  • Request validation
  • Rate limiting
  • Audit logging
  • Correlation ID tracking

Troubleshooting

Common Issues

Port Already in Use

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

Database Connection Issues

# Check PostgreSQL is running
docker-compose ps

# Check database logs
docker-compose logs postgres

NATS Connection Issues

# Check NATS is running
docker-compose ps

# Check NATS logs
docker-compose logs nats

Logs and Debugging

# View service logs
pnpm dev  # Shows all service logs

# View specific service logs
docker-compose logs <service-name>

# Enable debug logging
LOG_LEVEL=debug pnpm dev

Deployment

Docker Production Build

# Build production images
docker build -t nodestack/api-gateway apps/api-gateway
docker build -t nodestack/auth-service apps/auth-service
# ... repeat for other services

Environment Variables

See individual .env.example files for required environment variables.

Production Considerations

  • Use proper secrets management
  • Set NODE_ENV=production
  • Use production database URLs
  • Configure proper logging levels
  • Set up monitoring and alerting
  • Implement backup strategies

Using NodeStack for New Projects

What You Get Out of the Box

  • Complete authentication system
  • User management with roles
  • Multi-tenant support
  • API Gateway with documentation
  • Event-driven notifications
  • Audit logging
  • Clean architecture
  • Production-ready structure

Customization Points

  • Add business-specific services
  • Extend existing services with new endpoints
  • Customize notification templates
  • Add new event types
  • Modify database schema
  • Add new authentication providers

Getting Started with Your Project

  1. Fork/clone this repository
  2. Follow the setup instructions above
  3. Start building your business logic
  4. Add new services as needed
  5. Customize the existing services

Contributing

  1. Fork the repository
  2. Create feature branch
  3. Make changes
  4. Add tests
  5. Submit pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

  • Create GitHub issue
  • Check documentation
  • Review API docs at /documentation

Languages

TypeScript100.0%

Contributors

YO
Created January 6, 2026
Updated March 7, 2026