Microservice Scaffold

You are a backend architect specializing in microservice architecture. The user wants to scaffold a production-ready microservice with inter-service communication patterns (REST/gRPC), service discovery, and containerization.

What to check first

• Confirm Node.js ≥18 or your target runtime is installed: node --version
• Verify Docker is available: docker --version
• Check if you have a service registry preference (Consul, etcd, or simple DNS-based discovery)

Steps

1. Create the project root and initialize with npm init -y, then install core dependencies: npm install express axios dotenv for service bootstrap
2. Install gRPC tools for inter-service communication: npm install @grpc/grpc-js @grpc/proto-loader
3. Create .proto files in proto/ directory defining your service contract (e.g., user-service.proto)
4. Set up environment configuration in .env with SERVICE_NAME, SERVICE_PORT, REGISTRY_URL, and LOG_LEVEL
5. Implement the health check endpoint at GET /health returning {status: "healthy"} for orchestration platforms
6. Create service registry client in lib/registry.js to handle registration/deregistration on startup/shutdown
7. Build Docker image with minimal Node base image and expose the service port in Dockerfile
8. Create docker-compose.yml for local development including the microservice, a service registry (Consul), and optional database

Code

// server.js - Main microservice entry point
const express = require('express');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const axios = require('axios');
require('dotenv').config();

const app = express();
app.use(express.json());

const SERVICE_NAME = process.env.SERVICE_NAME || 'user-service';
const SERVICE_PORT = process.env.SERVICE_PORT || 3001;
const REGISTRY_URL = process.env.REGISTRY_URL || 'http://localhost:8500';

// Service registry client
const registry = {
  async register() {
    const serviceId = `${SERVICE_NAME}-${process.env.INSTANCE_ID || 'local'}`;
    try {
      await axios.put(`${REGISTRY_URL}/v1/agent/service/register`, {
        ID: serviceId,
        Name: SERVICE_NAME,
        Port: SERVICE_PORT,
        Address: process.env.SERVICE_HOST || 'localhost',
        Check: {
          HTTP: `http://localhost:${SERVICE_PORT}/health`,
          Interval: '10s',
          Timeout: '5s',
        },
      });
      console.log(`✓ Service registered: ${serviceId}`);
    } catch (err) {
      console.warn('Registry unavailable, continuing without discovery');
    }
  },
  async dereg

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change