Node API Skeleton

Production-ready Node.js API skeleton built with Hexagonal Architecture, Fastify, TypeScript, DDD, and modern best practices. Perfect starting point for scalable, maintainable API projects.

Status

🎉 Architecture Status: PRODUCTION READY

Version 2.0 - Migration to Hexagonal Architecture + Fastify COMPLETED!

All 8 migration stages completed ✅

• ✅ Stage 0: SWC compiler, Fastify dependencies, path aliases
• ✅ Stage 1: Hexagonal folder structure, Zod validation, Fastify server
• ✅ Stage 2: Domain layer (entities, value objects, ports)
• ✅ Stage 3: Application layer (use cases, DTOs, mappers)
• ✅ Stage 4: Infrastructure layer (controllers, routes, repositories)
• ✅ Stage 5: Dependency Injection with Awilix
• ✅ Stage 6: Observability (Winston logging + Prometheus metrics)
• ✅ Stage 7: Testing (Vitest + k6 performance tests)
• ✅ Stage 8: Cleanup, documentation, Docker production setup

📋 Table of Contents

1. Highlights
2. Features
3. Architecture
4. Folder Structure
5. Quick Start
6. Docker
7. API Endpoints
8. Testing
9. Observability
10. Documentation

✨ Highlights

🏗️ Modern Architecture

• Hexagonal Architecture (Ports & Adapters) for clean separation of concerns
• Onion Architecture with dependency inversion
• Screaming Architecture - folder structure reflects business capabilities
• DDD (Domain-Driven Design) with entities, value objects, and aggregates
• Vertical Slice organization by bounded contexts

⚡ Performance

• Fastify - 2x faster than Express
• SWC - Ultra-fast TypeScript compiler (20x faster than tsc)
• Build time: ~56ms (was ~2-3s with tsc)
• Production-ready with Docker multi-stage builds

🧪 Testing & Quality

• Vitest - Lightning-fast unit & integration tests
• k6 - Performance/load testing with thresholds
• 98%+ coverage - 244 comprehensive tests across all layers
• Type-safe validation with Zod
• ESLint + Prettier - Code quality enforcement

📊 Observability

• Winston - Structured JSON logging
• Prometheus - Metrics collection (requests, latency, errors)
• Grafana - Metrics visualization
• Health checks - Liveness & readiness probes
• OpenAPI - Interactive API documentation

🐳 DevOps Ready

• Docker multi-stage builds (minimal Alpine images)
• Docker Compose stacks for dev & production
• Non-root user for security
• Health checks integrated
• Prometheus + Grafana stack included

⚙️ Features

Core Stack

• ✅ Fastify - High-performance web framework
• ✅ TypeScript - Type-safe JavaScript
• ✅ SWC - Ultra-fast TypeScript compiler
• ✅ Zod - Runtime schema validation
• ✅ Awilix - Dependency injection

Testing

• ✅ Vitest - Fast unit & integration tests
• ✅ Supertest - HTTP endpoint testing
• ✅ k6 - Load & performance testing
• ✅ Pact - Contract testing framework
• ✅ Coverage reports with v8

Observability

• ✅ Winston - Structured logging
• ✅ Prometheus - Metrics collection
• ✅ prom-client - Prometheus client
• ✅ Health checks (liveness/readiness)
• ✅ Swagger/OpenAPI - API documentation

Security & Best Practices

• ✅ @fastify/helmet - Security headers
• ✅ @fastify/cors - CORS support
• ✅ @fastify/rate-limit - Rate limiting
• ✅ Environment validation with Zod
• ✅ Docker non-root user
• ✅ Immutable domain entities
• ✅ ADRs (Architecture Decision Records)

Development Tools

• ✅ ESLint - Code linting
• ✅ Prettier - Code formatting
• ✅ Husky - Git hooks
• ✅ lint-staged - Pre-commit checks
• ✅ Nodemon - Dev server auto-reload

🏗️ Architecture

Hexagonal Architecture

The application follows Hexagonal Architecture (Ports & Adapters):

┌─────────────────────────────────────────┐
│  Infrastructure (Adapters)              │  ← Fastify, DB, External APIs
├─────────────────────────────────────────┤
│  Application (Use Cases)                │  ← Business orchestration
├─────────────────────────────────────────┤
│  Domain (Business Logic)                │  ← Pure business rules
└─────────────────────────────────────────┘

Dependency Rule: Dependencies point inward only

• Infrastructure → Application → Domain
• Domain has zero framework dependencies

Vertical Slice by Contexts

Each bounded context is a complete vertical slice:

@contexts/greetings/
├── domain/            # Entities, Value Objects, Business Rules
├── application/       # Use Cases, DTOs, Mappers, Ports
└── infrastructure/    # Controllers, Routes, Repositories

Benefits:

• High cohesion - related code lives together
• Easy to navigate - no jumping between layers
• Scalable - add new contexts without touching existing ones
• Microservices-ready - easy to extract contexts

See ARCHITECTURE.md for complete documentation.

📁 Folder Structure

src/
├── @contexts/                 # Business Features (Bounded Contexts)
│   └── greetings/
│       ├── domain/            # Business Logic (framework-independent)
│       │   ├── entities/      # Greeting entity
│       │   ├── value-objects/ # Message value object
│       │   └── exceptions/    # Domain exceptions
│       ├── application/       # Use Cases & Orchestration
│       │   ├── v1/            # API version 1
│       │   │   ├── use-cases/ # GetGreetingUseCase
│       │   │   ├── dtos/      # Request/Response DTOs
│       │   │   ├── mappers/   # Domain ↔ DTO transformation
│       │   │   └── ports/     # Interfaces (inbound/outbound)
│       │   └── v2/            # API version 2 (enhanced)
│       └── infrastructure/    # Adapters (HTTP, DB, External)
│           ├── http/          # Controllers & Routes (v1, v2)
│           └── persistence/   # Repository implementations
│
├── @shared/                   # Cross-Cutting Concerns
│   ├── domain/                # Shared domain concepts
│   ├── infrastructure/
│   │   ├── config/            # Environment, DI container
│   │   ├── http/              # Fastify app, plugins
│   │   └── observability/     # Winston, Prometheus
│   ├── types/                 # Common types
│   ├── utils/                 # Pure utility functions
│   └── constants/             # HTTP status codes, etc.
│
├── @app/                      # Application Bootstrap
│   └── server/                # Fastify configuration
│
└── main.ts                    # Entry point

🚀 Quick Start

Prerequisites

• Node.js >= 20
• npm >= 10
• Docker (optional, for containerized setup)
• k6 (optional, for performance tests)

Installation

# Clone repository
git clone https://github.com/Proskynete/node-api-skeleton.git
cd node-api-skeleton

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Start development server
npm run dev

The API will be running at http://localhost:3000

Available Scripts

# Development
npm run dev              # Start dev server with hot reload (SWC)
npm run build            # Build production bundle (SWC)
npm start                # Run production server

# Testing
npm run test             # Run all tests (Vitest)
npm run test:watch       # Run tests in watch mode
npm run test:ui          # Run tests with UI dashboard
npm run test:coverage    # Generate coverage report

# Performance Testing (k6)
npm run test:performance:v1    # Test v1 endpoint
npm run test:performance:v2    # Test v2 endpoint
npm run test:performance:load  # Full load test

# Code Quality
npm run lint             # Check linting
npm run lint:fix         # Fix linting issues
npm run format           # Format code with Prettier
npm run format:check     # Check formatting

🐳 Docker

The project uses Docker Compose profiles for managing development and production environments in a single configuration file.

Production Environment

# Start production stack (API + Prometheus + Grafana)
docker-compose --profile production up -d

# View logs
docker-compose logs -f api-prod

# Stop services
docker-compose --profile production down

Development Environment

# Start dev environment with hot reload
docker-compose --profile dev up -d

# View logs
docker-compose logs -f api-dev

# Stop services
docker-compose --profile dev down

Services

• API: http://localhost:3000
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3001 (admin/admin)

See DOCKER.md for complete documentation.

📡 API Endpoints

Health & Metrics

• Liveness: GET /health/live - Is the app running?
• Readiness: GET /health/ready - Can it serve traffic?
• Metrics: GET /metrics - Prometheus metrics
• Docs: GET /docs - Swagger UI

Greetings API (v1)

• Get Greeting: GET /api/v1/greetings

Greetings API (v2)

• Get Greeting (enhanced): GET /api/v2/greetings

API Versioning: Multiple versions coexist, sharing the same domain layer but with different use cases.

🧪 Testing

Comprehensive Test Suite

The project includes 244 tests across all layers with excellent coverage:

Coverage Stats (as of v2.1.0):

• ✅ Statements: 98.42%
• ✅ Branches: 84.00%
• ✅ Functions: 96.87%
• ✅ Lines: 98.38%

Coverage Thresholds: 80% minimum for all metrics

Unit Tests

Test business logic in isolation:

npm run test             # Run all tests
npm run test:watch       # Watch mode
npm run test:ui          # Interactive UI dashboard
npm run test:coverage    # Generate coverage report

Test Coverage by Layer:

Domain Layer (Pure business logic):

• DomainEvent.spec.ts - Base domain event class (12 tests)
• GreetingCreatedEvent.spec.ts - Greeting domain event (21 tests)
• Greeting.spec.ts - Greeting entity
• Message.spec.ts - Message value object

Application Layer (Use cases & orchestration):

• GetGreetingUseCase.spec.ts (v1 and v2) - Business workflows (19 tests each)
• GreetingMapper.spec.ts (v1 and v2) - Data transformations (29 tests v2)
• GreetingCreatedEventHandler.spec.ts - Event handling (13 tests)
• InMemoryDomainEventPublisher.spec.ts - Event publishing (29 tests)

Infrastructure Layer (Repositories):

• InMemoryGreetingRepository.spec.ts - Data persistence (19 tests)

Architecture Principle: Infrastructure adapters (controllers, middlewares, plugins, route loaders) are excluded from unit test coverage as they're validated through integration/E2E tests. This aligns with Hexagonal Architecture best practices.

Integration Tests

Test HTTP endpoints and infrastructure:

describe("GET /api/v1/greetings", () => {
  it("should return greeting", async () => {
    const response = await request(app.server)
      .get("/api/v1/greetings")
      .expect(200);
    expect(response.body.message).toBe("Hello World!");
  });
});

Integration Test Coverage:

• HTTP endpoints (v1 and v2)
• Rate limiting
• Health checks
• Metrics collection
• Error handling

Performance Tests (k6)

Load testing with strict performance thresholds:

npm run test:performance:v1     # Test v1 endpoint
npm run test:performance:v2     # Test v2 endpoint
npm run test:performance:load   # Full load test

Performance Thresholds:

• p95 latency < 500ms
• p99 latency < 1000ms
• Error rate < 1%
• Request rate > 50 req/s

See test/performance/README.md

Contract Tests (Pact)

Consumer-driven contract testing ensures API compatibility:

npm run test:contract:provider

See test/contract/README.md

📊 Observability

Logging (Winston)

Structured JSON logging in production, pretty logs in development:

logger.info("Processing request", {
  requestId: request.id,
  version: "v1",
});

Metrics (Prometheus)

Available at /metrics:

• http_request_duration_seconds - Request latency
• http_requests_total - Total requests
• http_requests_in_progress - Active requests

Health Checks

• Liveness: /health/live - Basic health check
• Readiness: /health/ready - Dependency health (memory, DB, etc.)

OpenAPI Documentation

Interactive API docs at:

• Swagger UI: http://localhost:3000/docs

📚 Documentation

Core Documentation

• ARCHITECTURE.md - Complete architecture guide (Hexagonal + DDD + Vertical Slices)
• DOCKER.md - Docker setup, multi-stage builds, and Docker Compose
• GITHUB_ACTIONS.md - CI/CD pipeline, workflows, and automation
• CLAUDE.md - Development guide for Claude Code AI assistant

Architecture Decision Records (ADRs)

Document key architectural decisions with context and consequences:

• ADR Index - Complete list of architectural decisions
• ADR-0001 - Hexagonal Architecture adoption
• ADR-0007 - Bounded Contexts organization
• ADR-0009 - OOP + FP hybrid approach

View all ADRs →

Testing Guides

• Performance Testing - k6 load testing, thresholds, and automated test runner
• Contract Testing - Provider - Pact provider tests for HTTP inbound adapters
• Contract Testing - Consumer - Pact consumer tests reference (HTTP outbound adapters)
• Contract Tests README - Contract testing overview and execution

Integration Guides

• Database Integration - Prisma setup and repository implementation guide

Utility Scripts

• Scripts README - Automated performance test runner documentation

🎯 Design Patterns

• Dependency Injection (Awilix)
• Factory Pattern (Entity creation)
• Mapper Pattern (Domain ↔ DTO)
• Repository Pattern (Data access)
• Strategy Pattern (API versioning)

🔒 Security

• Helmet security headers
• CORS configuration
• Input validation with Zod
• Non-root Docker user
• Environment variable validation

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

📝 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Built with ❤️ using modern Node.js best practices
• Inspired by Clean Architecture, DDD, and Hexagonal Architecture principles

---

Version: 2.1.0 Status: Production Ready Architecture: Hexagonal + Onion + Screaming Last Updated: December 2024

(⬆️ Back to top)