Skip to main content

Template Service

Template microservice skeleton for Helix platform backend services.

Overview​

This service provides:

  • Health check endpoints (/health, /heartbeat, /info)
  • Central database connection
  • CLS (Context Local Storage) for request context
  • Environment-based configuration
  • Docker containerization
  • Unit tests with Jest

Endpoints​

Health Endpoints (Unauthenticated)​

  • GET /health - Comprehensive health check with dependency status
  • GET /heartbeat - Lightweight liveness check
  • GET /info - Service metadata

Environment Variables​

See .env.example in the project root for required configuration:

  • SERVICE_NAME - Service name
  • SERVICE_PORT - Port to run on
  • NODE_ENV - Environment (development/staging/production)
  • CENTRAL_DATABASE_URL - PostgreSQL connection string

Development​

# Install dependencies
npm install

# Run in development
npx nx serve template-service

# Run tests
npx nx test template-service

# Build
npx nx build template-service

Docker​

# Build image
docker build -t template-service -f apps/template-service/Dockerfile .

# Run container
docker run -p 3000:3000 --env-file apps/template-service/.env template-service

Architecture​

This service follows the Helix platform patterns:

  • Central DB: Connects to platform database on boot
  • Health Checks: Unauthenticated endpoints for load balancers
  • CLS Context: Request-scoped storage for auth/tenant context
  • TypeScript Strict: Fully typed codebase
  • Shared Libraries: Uses @helix/shared/* packages

Testing​

Unit tests cover all health endpoints with >80% coverage requirement.

npx nx test template-service --coverage