pos-system/services/auth-service/README.md

Auth Service

Authentication and Authorization microservice.

Features

• User registration and login
• JWT token management (access + refresh tokens)
• Password change
• User management (admin)
• Role-based access control (RBAC)
• Health checks

API Endpoints

Auth

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Login user
• POST /api/v1/auth/refresh - Refresh access token
• POST /api/v1/auth/logout - Logout user
• PUT /api/v1/auth/password - Change password

Users

• GET /api/v1/users/me - Get current user
• GET /api/v1/users - List users (admin)
• GET /api/v1/users/:id - Get user by ID (admin)
• PUT /api/v1/users/:id - Update user (admin)
• DELETE /api/v1/users/:id - Delete user (admin)

Health

• GET /health - Health check
• GET /health/ready - Readiness probe
• GET /health/live - Liveness probe

Development

Setup Environment Variables

This service uses Hybrid Environment Configuration:

Step 1: Setup shared environment (from project root)

# Copy shared environment template
cp deployments/local/env.local.example deployments/local/.env.local

# Edit and add JWT secrets (must be same across all services)
# JWT_SECRET, JWT_REFRESH_SECRET, REDIS_HOST, etc.

Step 2: Setup service-specific environment

# Copy service environment template
cp env.local.example .env.local

# Edit and add:
# - DATABASE_URL: Your Neon database connection string
# - PORT: 5001
# - REDIS_HOST: localhost (for native dev)

Environment structure:

• deployments/local/.env.local → Shared configs (JWT, Redis, common)
• services/auth-service/.env.local → Service-specific (DATABASE_URL, PORT)

Run Development Server

# From project root
pnpm --filter @goodgo/auth-service dev

# Or from this directory
pnpm dev

The service will load env from both files automatically.

Database Setup

# Generate Prisma client
pnpm prisma:generate

# Run migrations
pnpm prisma:migrate

# Seed database (optional)
pnpm prisma:seed

# Open Prisma Studio
pnpm prisma studio

Testing

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage

Build

# Build for production
pnpm build

# Start production server
pnpm start

Environment Variables

Shared Environment (deployments/local/.env.local)

• JWT_SECRET - JWT signing secret (must be same across services)
• JWT_REFRESH_SECRET - Refresh token secret
• REDIS_HOST - Redis hostname (redis for Docker)
• NODE_ENV - development/production
• LOG_LEVEL - debug/info/warn/error

Service-Specific Environment (.env.local)

• DATABASE_URL - Neon PostgreSQL connection string
• PORT - Service port (default: 5001)
• SERVICE_NAME - auth-service
• REDIS_HOST - localhost (override for native dev)

See env.local.example for complete list.