# Microservices

## What it is responsible for

Microservices manages work entering through `normalizedPattern`, `route`, and `ClientsModule` for the Nest framework, whose authors describe Nest as a framework for building Node.js server-side applications. It owns the subsystem boundary implied by those entry points and by its use from integration and sample code, including TCP/TLS, gRPC, Kafka, MQTT, NATS, and Redis paths. Its work depends on [Common](subsystem-packages-common), [Core](subsystem-packages-core), and [Websockets](subsystem-packages-websockets).

## What it refuses

The subsystem rejects an absent gRPC client reference with `InvalidGrpcServiceException` when `!clientRef`. It rejects Kafka topic handling with `InvalidKafkaClientTopicException` when `isUndefined(minimumPartition)`. When `!this._consumer`, it says: “No consumer initialized. Please, call the "connect" method first.” When `!this._producer`, it says: “No producer initialized. Please, call the "connect" method first.” When `!this.client`, it says: “Not initialized. Please call the "connect" method first.” When `!this.mqttClient`, it says: “Not initialized. Please call the "connect" method first.”

## What it needs, and who needs it

Microservices needs Common, Core, and Websockets. Without it, the named dependents—integration, the TCP/TLS microservices integration, sample math, sample hero, inspector external service, and the gRPC, Kafka, MQTT, NATS, and Redis integrations—lose their declared dependency on this subsystem. This evidence names dependency relationships; it does not state a more specific failure mode.

## Notable members

`ClientsModule`, `normalizedPattern`, and `route` are notable because the supplied evidence names all three as places where work enters. They share the strongest directly stated role in this subsystem: accepting incoming work at its boundary. The evidence does not distinguish their individual internal behavior, lifecycle, or relationship to the client, consumer, producer, gRPC, Kafka, or MQTT checks. Accordingly, no member-specific implementation claim is warranted beyond their shared entry-point status.

429 entities in `packages/microservices`. **1 other subsystem depends on it**, which makes it the 4th most depended-upon part of this codebase.

## What it is made of

Its 429 entities sit in 117 files under `packages/microservices`: 99 interfaces, 98 type aliases, 97 classes, 52 constants and 83 more.
`kafka.interface.ts` holds 156 of them — more than any other file here.
`Server` declares 24 methods, the widest surface here.

## Where work enters

It publishes 2 `GET` endpoints. None of them declares a guard.

- [`normalizedPattern`](api-endpoint-normalizedpattern) — `packages/microservices/server/server.ts`:150
- [`route`](api-endpoint-route) — `packages/microservices/server/server.ts`:168
- [`ClientsModule`](module-clientsmodule) — `packages/microservices/module/clients.module.ts`:17

## How it refuses and fails

33 of its components record a refusal or a failure handler.
31 of them refuse work outright, under a condition written into the component itself.
Their `catch` blocks handle a failure that already happened in 29 places.
Of those 29, 13 turn it into a return value, 10 log it and continue, 5 let it reach the caller and 1 discards it without recording anything.

## Boundaries

**1 other subsystem depends on this one** — `Core`. Changing what it exposes changes them.

They hold 1 edge into it between them. 185 edges leave it against 1 arriving — it reads more of this repository than this repository reads of it. What they reach is narrower than the folder: 1 of its 429 members carries every inbound edge — `MicroservicesModule` (1). Of the 185 it sends out, 123 go to `Common` — more than to any other.

It depends on `Common`, `Core`, `Websockets`, and on nothing else in this repository.

## How this code is named

These conventions cover most of the codebase. Learning them is faster than reading an index —
each one lets you find any member of its family without looking it up.

| Pattern | Where | Count | Examples |
|---|---|---|---|
| `*.interface.ts` | across the repository | 20 | `kafka.interface.ts`, `redis.interface.ts`, `packet.interface.ts`, `rmq-url.interface.ts` |
| `*.exception.ts` | `packages/microservices/errors/` | 14 | `empty-response.exception.ts`, `invalid-message.exception.ts`, `net-socket-closed.exception.ts`, `invalid-json-format.exception.ts` |
| `*.context.ts` | `packages/microservices/ctx-host/` | 7 | `rmq.context.ts`, `tcp.context.ts`, `mqtt.context.ts`, `nats.context.ts` |
| `*.deserializer.ts` | `packages/microservices/deserializers/` | 7 | `identity.deserializer.ts`, `kafka-request.deserializer.ts`, `kafka-response.deserializer.ts`, `incoming-request.deserializer.ts` |