Skip to content

Kamea Libs

Kamea exposes a set of libraries that the platform's apps depend on. Their goal is to keep cross-cutting code (domain models, communication primitives, NestJS infrastructure, the management API itself) in one place, and to make that code reusable both inside the monorepo and outside (customer projects that build on top of Kamea).

There are two physical homes for libs:

  • core/libs/ — TypeScript / NestJS libraries. Each one is an npm workspace, published under the @kamea/* scope, built to its own dist/ folder by tsc. They are consumed by every backend app and can be published to a private registry (e.g. Artifactory) for customer projects.
  • core/shared/ — the historical Angular library, configured with ng-package.json. Consumed by the front-end apps. Same idea, different framework.

The rest of this page covers the core/libs/ libraries. For the canonical list of what's installed and at what version, look at each lib's package.json.

Libraries

Package Folder Role
@kamea/shared core/libs/shared Framework-agnostic domain models, DTOs, environment helpers.
@kamea/ingestion core/libs/ingestion Data ingestion building blocks.
@kamea/nestjs-shared core/libs/nestjs-shared NestJS-flavoured shared code (message bus, logger, Redis, common validators).
@kamea/api core/libs/api The Management API as a reusable library — see App and @kamea/api lib.

The exact contents of each lib (what it exports, which subpaths it exposes) live in its own source. Treat the package.json#exports field of each lib as the authoritative list of its public surface.

Dependency graph

The libs are layered. A lower-level lib knows nothing about higher-level ones:

graph TD
    A["@kamea/shared"]
    B["@kamea/ingestion"]
    C["@kamea/nestjs-shared"]
    D["@kamea/api"]
    E["management-api app"]
    F["other backend apps"]

    B --> A
    C --> A
    C --> B
    D --> A
    D --> B
    D --> C
    E --> D
    F --> A
    F --> B
    F --> C

Build order follows the arrows: lower-level libs build first. The root package.json exposes a build:libs:<name> script per lib, and each app's build script chains the lib builds it depends on. Look at the root package.json for the current set.

Public surface and stability

What each lib exposes is curated. Anything reachable from a public-api.ts (or a feature-level public-api.ts in libs that use per-feature subpaths) is considered contract. Anything else is internal and may be refactored without notice between minor versions.

Discipline:

  • Add new public exports to the relevant public-api.ts. Do not use export * from "./..." — those silently widen the public surface as new files are added.
  • When you add a brand-new subpath, add a matching entry to package.json#exports.
  • Rebuild the lib (npm run build:libs:<name>) before consumers see the new export.

Consumers should only import via paths declared in package.json#exports. Deep imports into a lib's dist/ internals work today but are not contract.

core/shared/ — the Angular lib

The historical home of the Angular library that the front-ends consume. It uses ng-package.json for its build configuration and public-api.ts as its entry point. The same discipline applies: only what's exported from public-api.ts is public.