Architecture

graph TD
    A[Client] -->|HTTP Request| B[Express Server]
    B --> C[Middleware Layer]
    C --> D[CORS]
    C --> E[Body Parser]
    C --> F[User Agent]
    C --> G[Error Handler]
    B --> H[Route Layer]
    H --> I[Common Routes]
    H --> J[Dogs Routes]
    I --> K[Health Check Controller]
    J --> L[Dogs Controller]
    K --> M[Redis Client]
    L --> M
    M --> N[(Redis Database)]
    B --> O[Health Monitor]
    O -->|Every 5s| K

Architecture Principles

1. Separation of Concerns: Modular design separating routes, controllers, and services
2. Single Responsibility: Each module handles a specific feature or domain
3. Resilience: Automatic reconnection and error recovery mechanisms
4. Observability: Comprehensive logging and health monitoring
5. Standardization: Consistent coding patterns and project structure

Design Patterns

• Module Pattern: Organized features into self-contained modules
• Middleware Pattern: Cross-cutting concerns handled via Express middleware
• Singleton Pattern: Managed shared resources like the Redis client
• Error Object Pattern: Standardized error classes for predictable handling

Best Practices

• Type Safety: Leverage TypeScript's strict mode for robust code
• Modularization: Keep features isolated in their respective modules
• Testing: Maintain high coverage for both unit and integration tests
• Logging: Use structured logs for better searchability and monitoring
• Configuration: Never hardcode secrets; use environment variables

Getting Started

Prerequisites

• Node.js (v14 or higher)
• npm or yarn
• Redis server (local or remote)

Installation

1. Clone the repository:

git clone https://github.com/orassayag/node-microservice-boilerplate.git
cd node-microservice-boilerplate

2. Install dependencies:

npm install

3. Configure Redis connection in config/env.json:

{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "expiration": 3600
  }
}

4. Build the project:

npm run tsc

5. Start the server:

npm start

The server will start at http://localhost:3000

Usage

Verify Service Health

You can check the service status using curl:

curl http://localhost:3000/health

Available Scripts

Development

# Start in development mode with hot reload
npm run dev

Production

# Build and start the server
npm start

Testing

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

Code Quality

# Check for linting errors and fix
npm run eslint

# Format code with Prettier
npm run prettier

# Run both ESLint and Prettier
npm run beautify

Build

# Compile TypeScript to JavaScript
npm run tsc

API Endpoints

Health Check

GET /health

Returns the health status of the server and Redis connection.

Response:

{
  "status": "ok"
}

Get Dogs

GET /getDogs?hash=<hash>

Retrieves all dogs stored under the specified hash key.

Query Parameters:

• hash (required): Hash key to retrieve data from Redis

Response:

{
  "dogs": {
    "buddy": "dog123",
    "max": "dog456"
  }
}

Set Dog

GET /setDog?hash=<hash>&dog=<dogName>&dogId=<dogId>

Stores a dog name and ID under the specified hash key.

Query Parameters:

• hash (required): Hash key to store data in Redis
• dog (required): Dog name
• dogId (required): Dog ID

Response:

Status: 200 OK

Project Structure

node-microservice-boilerplate/
├── src/
│   ├── modules/              # Feature modules
│   │   ├── common/           # Common features
│   │   │   ├── controllers/  # Health check controller
│   │   │   ├── routes/       # Common routes
│   │   │   └── __tests__/    # Common tests
│   │   └── dog/              # Dog module (example)
│   │       ├── controllers/  # Dog controllers
│   │       ├── routes/       # Dog routes
│   │       └── __tests__/    # Dog tests
│   ├── middlewares/          # Express middleware
│   │   └── error-handling-middleware.ts
│   ├── redis/                # Redis client configuration
│   │   └── connect.ts
│   ├── logger/               # Pino logger setup
│   │   └── index.ts
│   ├── error/                # Custom error classes
│   │   └── custom-error.ts
│   ├── types/                # TypeScript type definitions
│   └── app.ts                # Main application entry
├── config/                   # Configuration files
│   ├── env.ts                # Environment configuration
│   └── env.json              # Default configuration
├── dist/                     # Compiled JavaScript output
├── declarations/             # TypeScript declaration files
├── tsconfig.json             # TypeScript configuration
├── package.json              # Dependencies and scripts
├── README.md                 # This file
├── INSTRUCTIONS.md           # Detailed setup instructions
├── CONTRIBUTING.md           # Contribution guidelines
└── LICENSE                   # MIT License

Directory Structure

src/
├── modules/              # Feature-based modules
│   ├── common/           # Health checks and common routes
│   └── dog/              # Example domain logic
├── middlewares/          # Express request/response middlewares
├── redis/                # Database connection and client
├── logger/               # Pino logging configuration
├── error/                # Custom error types and handling
├── types/                # Global TypeScript declarations
└── app.ts                # Application entry point

Configuration

Configuration is managed through config/env.json with environment variable overrides:

Environment Variables:

• PORT - Server port (default: 3000)
• HOST - Server host (default: localhost)
• REDIS_HOST - Redis server host (default: localhost)
• REDIS_PORT - Redis server port (default: 6379)
• REDIS_EXPIRATION - Redis key expiration in seconds (default: 3600)

Redis Integration

The application uses Redis for data storage with the following features:

• Automatic reconnection with 3-second intervals
• Connection event logging
• Health check monitoring every 5 seconds
• Configurable key expiration
• Hash-based data structure for efficient storage

Logging

Structured logging is provided by Pino with pretty printing in development:

• Info level: General application flow
• Warn level: Health check results and warnings
• Error level: Exceptions and failures

Error Handling

All errors are caught and processed through a centralized error handling middleware:

• Consistent error response format
• Detailed error logging
• Prevention of application crashes
• Proper HTTP status codes

Testing

The project uses Jest for testing:

• Unit tests for controllers
• Integration tests for routes
• Test configuration in package.json
• TypeScript support with ts-jest

Development

See CONTRIBUTING.md for development guidelines and INSTRUCTIONS.md for detailed setup instructions.

Built With

• Node.js - JavaScript runtime
• TypeScript - Type-safe JavaScript
• Express.js - Web framework
• Redis - In-memory data store
• Pino - Fast logging library
• Jest - Testing framework
• ESLint - Code linting
• Prettier - Code formatting

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Support

For questions, issues, or contributions:

• GitHub Issues: https://github.com/orassayag/node-microservice-boilerplate/issues
• Email: orassayag@gmail.com

Author

• Or Assayag - Initial work - orassayag
• Or Assayag orassayag@gmail.com
• GitHub: https://github.com/orassayag
• StackOverflow: https://stackoverflow.com/users/4442606/or-assayag?tab=profile
• LinkedIn: https://linkedin.com/in/orassayag

License

This application has an MIT license - see the LICENSE file for details.

Acknowledgments

• Built for educational and research purposes
• Respects robots.txt and implements rate limiting
• Uses user-agent rotation to avoid detection
• Implements polite crawling practices