Offer Availability Service

A production grace Node.js microservice demonstrating how enterprise java spring boot patterns translate cleanly into a typescript + express stack.

Architecture

graph TD
  Client[HTTP Client] --> Routes
  Routes --> AuthMW[Auth Middleware]
  AuthMW --> ValidMW[Validation Middleware]
  ValidMW --> Controllers
  Controllers --> Services
  Services --> Repositories
  Repositories --> Store[In-Memory Store]
  Services --> BL[Business Logic<br/>isActive Computation]
  ErrMW[Error Handler Middleware] -.-> Client

Loading

Layered Architecture

graph LR
  subgraph Presentation
    R[Routes] --> C[Controllers]
  end
  subgraph Domain
    S[Services] --> M[Models]
  end
  subgraph Persistence
    Repo[Repositories]
  end
  C --> S
  S --> Repo

Loading

Layer	Spring Boot Equivalent	Responsibility
routes/	@RequestMapping	HTTP Verb + Path binding
controllers/	@RestController	Request/Responses Handling
services/	@Service	Business logic, orchestration
repositories/	@Repository	Data access architecture
middleware/	@ControllerAdvice / Filters	Cross-cutting concerns
validators/	@Valid + JSR-380	Request Body Validation
config/	@Configuration	Environment + logger setup

Request Flow

sequenceDiagram
  participant C as Client
  participant R as Router
  participant A as Auth Middleware
  participant V as Validator
  participant Ctrl as Controller
  participant S as Service
  participant Repo as Repository

  C->>R : GET /api/offers
  R->>A : Check Bearer Token
  A->>A : Validate Token in memory store
  A->>Ctrl : Attach username to request
  Ctrl->>S : findAll()
  S->>Repo : findAll()
  Repo->>S : Offer[]
  S->>S : enrichWithActive(now)
  S-->>Ctrl : OfferResponse[]
  Ctrl-->>C: 200 JSON

Loading

Key Design Decisions

• No ORM - Repositories abstract storage
• Computed active field - never stored, always derived from startDate/endDate vs current time
• Manual constructor injection - explicit wiring in app.ts, no magic DI Container
• Zod Validation - schema-first request validation with type inference
• Structured logging - winston with json format, ready for ELK/Datadog ingestion
• Token based auth - stateless UUID tokens in an in-memory map; no JWT Complexity for internal services

Tech stack

Concern	Tool
Runtime	Node.js 20+
Language	TypeScript 5.x
Framework	Express 4
Validation	Zod
Logging	Winston
Config	dotenv
Testing	Jest + Supertest
Linting	ESLint + Prettier

Quick Start

npm install

# Development (hot reload)
npm run dev

# Production build
npm run build && npm start

# Run all Tests
npm test

# Lint & format
npm run lint
npm run format

API reference

Authentication

Method	EndPoint	Body	Description
POST	api/auth/login	{ username, password }	Returns bearer token
POST	api/auth/logout	-	Invalidates current token

Offers (Requires Authorization : Bearer <token>)

Method	EndPoint	Description
GET	api/offers	List all offers with computed active flag
GET	api/offers/:id	Get single offer
POST	api/offers	Create offer
DELETE	api/offers/:id	Delete Offer

Health

Method	EndPoint	Description
GET	/health	Liveness probe

Testing Strategy

graph BT
  Unit[Unit Tests<br/>OfferService.isActive logic] --> Integration[Integration Tests<br/> Full HTTP lifecycle via Supertest]

Loading

• Unit tests - pure business logic validation (isActive boundary cases)
• Integration Tests - end-to-end HTTP with auth flow, validation errors, CRUD Operations

Why this Architecture ?

This service is designed for teams with spring boot experience transistioning to node.js. The patterns are intentionally familiar:

• Constructor injection -> Same concept, no framework magic
• Repository pattern -> swappable data layer
• Service layer -> testable business logic in isolation
• Middleware -> equivalent to servlet filters / @ControllerAdvice
• Zod Schemas -> type-safe validation like Bean validation (JSR-380)

The goal is Zero Cognitive overhead for backend engineers already comfortable with layered enterprise architecture.