# Core

## What it is responsible for

Core manages route-oriented execution through `RouterExplorer`, `RouterExecutionContext`, and `RouterProxy`. Its routing vocabulary includes `Routes`, `RouteTree`, `RouteDefinition`, `PathsExplorer`, `RoutePathFactory`, `RouteParamsFactory`, and `IRouteParamsFactory`; its exception-filter vocabulary includes `RouterExceptionFilters` and `ExceptionsFilter`. The subsystem also has `REQUEST`, `REQUEST_CONTEXT_ID`, and `requestProvider` among its named members. For SSE, its documented behavior transforms “messages” to W3C event stream content. Work enters through `moduleKey`, `moduleName`, `handler`, and `metatype`.

## What it refuses

Core refuses the following stated conditions:

- `ForbiddenException` when `!canActivate`.
- `UnknownRequestMappingException` when `isUndefined(path)`.
- `InternalServerErrorException` when `!next`.
- “You must return an Observable stream to use Server-Sent Events (SSE).” when `!isObservable(value)`.
- `InvalidExceptionFilterException` when `!Array.isArray(filters)`.
- `InvalidClassScopeException` when `wrapperRef.scope` is `Scope.REQUEST` or `Scope.TRANSIENT`, or when `!wrapperRef…`.
- `UnknownElementException` when `!instance`.

## What it needs, and who needs it

Core depends on `Common`, `Websockets`, and `Microservices`. The named dependent side includes integration, integration/inspector/src/[common](subsystem-packages-common), sample/01-cats-app/src/common, sample/10-fastify/src/common, sample/19-auth-jwt/src/auth, sample/36-hmr-esm/src/common, integration/graphql-code-first/src/recipes, integration/injector/src/scoped, integration/inspector/src/core, integration/inspector/src/durable, integration/inspector/src/request-chain, and integration/scopes/src/durable. These projects and areas depend on Core itself. Core, in turn, depends on all three: `Common`, `Websockets`, and `Microservices`. Without Core, the listed dependents have an unsatisfied dependency; without those three, Core has unsatisfied dependencies.

## Notable members

`RouterExplorer` carries the route-exploration side indicated by its name and sits alongside `PathsExplorer`, `Routes`, and `RouteTree`. `RouterExecutionContext` carries the execution-context side, while `RouterProxy` marks proxy work around that execution. `RouterExceptionFilters` carries exception-filter work, paired with `ExceptionsFilter`. `RouteParamsFactory` and `IRouteParamsFactory` identify parameter-factory work, and `RoutePathFactory` identifies path-factory work. `RouteDefinition`, `RoutePathMetadata`, `ExcludeRouteMetadata`, `LegacyRouteConverter`, and `RouterModule` show the related route-definition, metadata, conversion, and module surface. `RouterProxyCallback` names the callback counterpart to the proxy. `Resolver`, `ParamProperties`, `ROUTES`, and `targetModulesByContainer` extend the explicitly named routing and module-related surface of Core in this subsystem.

284 entities in `packages/core`. **5 other subsystems depend on it**, which makes it the 2nd most depended-upon part of this codebase.

## What it is made of

Its 284 entities sit in 157 files under `packages/core`: 106 classes, 44 functions, 41 interfaces, 29 doc comments and 64 more.
`messages.ts` holds 14 of them — more than any other file here.
`AbstractHttpAdapter` declares 50 methods, the widest surface here.

## Where work enters

It publishes 7 HTTP endpoints — 5 `GET` and 2 `ALL`. None of them declares a guard.

- [`moduleKey`](api-endpoint-modulekey) — `packages/core/middleware/container.ts`:27
- [`moduleName`](api-endpoint-modulename) — `packages/core/middleware/container.ts`:68
- [`handler`](api-endpoint-handler-2) — `packages/core/middleware/middleware-module.ts`:94
- [`metatype`](api-endpoint-metatype) — `packages/core/middleware/middleware-module.ts`:202
- [`handler`](api-endpoint-handler-2) — `packages/core/middleware/middleware-module.ts`:287
- [`handler`](api-endpoint-handler-3) — `packages/core/middleware/resolver.ts`:18

## How it refuses and fails

56 of its components record a refusal or a failure handler.
51 of them refuse work outright, under a condition written into the component itself.
Their `catch` blocks handle a failure that already happened in 16 places.
Of those 16, 7 log it and continue, 6 let it reach the caller and 3 turn it into a return value.

## Boundaries

**5 other subsystems depend on this one** — `Microservices`, `Platform Express`, `Platform Fastify`, `Testing`, `Websockets`. Changing what it exposes changes them.

Those 5 hold 130 edges between them, unevenly: `Microservices` reaches in across 61 edges, against 2 from `Platform Fastify`. 473 edges leave it against 130 arriving — it reads more of this repository than this repository reads of it. What they reach is narrower than the folder: 42 of its 284 members carry every inbound edge — `RuntimeException` (11), `NestContainer` (9) and `ApplicationConfig` (8), plus 39 more. Of the 473 it sends out, 471 go to `Common` — more than to any other.

It depends on `Common`, `Websockets`, `Microservices`, 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 | 19 | `edge.interface.ts`, `node.interface.ts`, `routes.interface.ts`, `extras.interface.ts` |
| `*.exception.ts` | `core/errors/exceptions/` | 17 | `runtime.exception.ts`, `invalid-class.exception.ts`, `invalid-module.exception.ts`, `unknown-export.exception.ts` |
| `*.hook.ts` | `packages/core/hooks/` | 5 | `on-module-init.hook.ts`, `on-app-shutdown.hook.ts`, `on-app-bootstrap.hook.ts`, `on-module-destroy.hook.ts` |
| `call*` | exported symbols | 5 | `callModuleInitHook`, `callAppShutdownHook`, `callModuleDestroyHook`, `callModuleBootstrapHook` |