@starci/skills 1.1.0

package/knowledge/patterns/be/error.md

@@ -0,0 +1,86 @@
+# Error
+
+This file answers one question: given a failure in the backend, how is it declared, thrown,
+wrapped, logged, and mapped onto HTTP and GraphQL?
+
+Sources: `modules/platform/exceptions/errors/abstract.ts`, `errors/ai/ai-quota-exhausted.ts`,
+`errors/courses/challenge-not-found.ts`, `errors/api/graphql.ts`,
+`modules/platform/exceptions/filters/abstract-exception-http.filter.ts`,
+`apps/core/src/app.module.ts`,
+`modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`,
+`modules/api/apollo/server/monolithic/monolithic-apollo-server.module.ts`,
+`modules/api/apollo/server/types/graphql-response.ts`,
+`features/api/core/graphql/mutations/courses/add-to-cart/add-to-cart.handler.ts`.
+
+Verified: 294 files under `errors/**` declare a class that `extends AbstractException`; the only
+class extending `Error` directly is `AbstractException` itself; lint `throw-abstract-exception`,
+`exception-extends-abstract` and `exception-in-errors-folder` are at error for `src/**` and off
+only under `src/tests/**` and `apps/*/test/**`.
+
+## BE-ERROR-1 — The base
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Shape | `export class AbstractException extends Error { readonly code: string; readonly metadata?: Record<string, unknown>; readonly httpStatus?: number; constructor(message: string, name: string, metadata?: Record<string, unknown>, httpStatus?: number) { super(message); this.code = name; this.name = name; this.metadata = metadata; this.httpStatus = httpStatus } … }` |
+| Case 2 | Serialisation | `toJSON(): string` → `{ message, code, metadata }`; `static fromJSON<T extends AbstractException>(…)` |
+| Case 3 | Cause | `getOriginalError(): Error { return this.metadata?.originalError as Error }`; `export interface AbstractExceptionMetadata { originalError?: Error }` |
+| Case 4 | Status | `httpStatus` is optional; undefined means 500 at both transports |
+
+## BE-ERROR-2 — Declaring one exception
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Metadata interface first | `export interface ChallengeNotFoundExceptionMetadata extends AbstractExceptionMetadata { id?: string }` |
+| Case 2 | Class | `export class ChallengeNotFoundException extends AbstractException { constructor({ id, originalError }: ChallengeNotFoundExceptionMetadata) { super("Challenge not found", "CHALLENGE_NOT_FOUND_EXCEPTION", { id, originalError }) } }` |
+| Case 3 | Interpolated message | `` super(`AI quota exhausted (${window})`, "AI_QUOTA_EXHAUSTED_EXCEPTION", { window, originalError }) `` |
+| Case 4 | With a status | fourth argument `HttpStatus.<X>` — set in 94 of 294 files, left undefined in the rest |
+| Case 5 | Single object argument | always one metadata object, even when empty: `throw new UserNotFoundException({})` (lint `require-exception-object-arg`) |
+
+## BE-ERROR-3 — Throwing
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Guard in a handler | `if (!courseExists) { throw new CourseNotFoundException({ id: courseId }) }` |
+| Case 2 | Conflict | `throw new CourseAlreadyEnrolledException({ courseId, userId: user.id })` |
+| Case 3 | Never encode failure in the return | a handler resolves to the entity or throws; `success: false` appears in 1 of 154 handlers (lint `no-handler-encoded-failure`) |
+| Case 4 | Never `new Error` | `NewExpression[callee.name="Error"]` is banned in `src/**` outside the test lanes |
+
+## BE-ERROR-4 — Wrapping a foreign error
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Crypto | `catch (error) { throw new DecryptionFailedException({ originalError: error instanceof Error ? error : new Error(String(error)) }) }` (25 non-exception files wrap this way) |
+| Case 2 | Cursor parsing | `catch (error) { throw new CourseCommunityCursorException({ originalError: error as Error }) }` |
+| Case 3 | At-least-once consumer | `catch (error) { const exception = new KafkaCdcMessageException({ topic, originalError: error instanceof Error ? error : undefined }); … log and continue }` |
+| Case 4 | Upstream GraphQL | `GraphQLDataNotFoundException({ query, variables, url, originalError })` |
+
+## BE-ERROR-5 — HTTP mapping
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | The filter | `@Catch(AbstractException) export class AbstractExceptionHttpFilter implements ExceptionFilter { catch(exception: AbstractException, host: ArgumentsHost): void { if (host.getType<string>() === "graphql") { throw exception } const status = exception.httpStatus ?? HttpStatus.INTERNAL_SERVER_ERROR; … response.status(status).json({ statusCode: status, code: exception.code, message: exception.message }) } }` |
+| Case 2 | Registration | `apps/core/src/app.module.ts`: `{ provide: APP_FILTER, useClass: AbstractExceptionHttpFilter }` |
+| Case 3 | Logged before responding | `this.winstonService.log(WinstonLog.HttpExceptionLogged, { op: "http.exception.logged", error: exception.message, meta: { code: exception.code, status } })` |
+| Case 4 | GraphQL host | rethrown untouched so Apollo's pipeline owns it |
+
+## BE-ERROR-6 — GraphQL mapping
+
+Two layers. The interceptor shapes the resolver's body; `formatError` shapes the GraphQL `errors`
+entry and the transport status.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Success envelope | `GraphQLTransformInterceptor` maps every resolver result to `{ data, message, success: true }` with `message` from `@GraphQLSuccessMessage({ [Locale.En]: "…", [Locale.Vi]: "…" })` resolved by locale |
+| Case 2 | Failure envelope | `catchError((err) => … observer.next({ success: false, message: err?.message ?? "Internal server error", error: err?.name ?? "Error" }))` — `error` carries the exception `code` because `AbstractException` sets `this.name = name` |
+| Case 3 | `formatError` | in `MonolithicApolloServerModule`: `if (original instanceof AbstractException) { return { ...formattedError, extensions: { ...formattedError.extensions, code: original.code, http: { status: original.httpStatus ?? 500 }, …retryAfterSeconds } } }` |
+| Case 4 | Everything else | `return { ...formattedError, extensions: { ...formattedError.extensions, http: { status: 500, ...(formattedError.extensions?.http as ApolloHttpExtension \| undefined) } } }` |
+| Case 5 | Transport status | `httpStatusFromExceptionsPlugin` reads `extensions.http.status` and sets the real HTTP status |
+| Case 6 | Client contract | `interface GraphQLResponse<T = unknown> { data?: T; message: string; success: boolean; error?: string }`; the FE matches on `error` code, not on status |
+
+## BE-ERROR-7 — Logging a failure
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Identity | an enum member: `WinstonLog.HttpExceptionLogged` (lint `no-interpolated-log-message`, `no-error-wording-as-log-identity`) |
+| Case 2 | Payload | `{ op: "http.exception.logged", error: exception.message, meta: { code, status } }` |
+| Case 3 | Never | `console.error`, Nest `Logger` |

package/knowledge/patterns/be/error.vi.md

@@ -0,0 +1,86 @@
+# Lỗi
+
+Tệp này trả lời một câu hỏi: cho một thất bại trong backend, nó được khai báo, ném, bọc, ghi log,
+và ánh xạ sang HTTP và GraphQL thế nào?
+
+Nguồn: `modules/platform/exceptions/errors/abstract.ts`, `errors/ai/ai-quota-exhausted.ts`,
+`errors/courses/challenge-not-found.ts`, `errors/api/graphql.ts`,
+`modules/platform/exceptions/filters/abstract-exception-http.filter.ts`,
+`apps/core/src/app.module.ts`,
+`modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`,
+`modules/api/apollo/server/monolithic/monolithic-apollo-server.module.ts`,
+`modules/api/apollo/server/types/graphql-response.ts`,
+`features/api/core/graphql/mutations/courses/add-to-cart/add-to-cart.handler.ts`.
+
+Đã kiểm chứng: 294 tệp dưới `errors/**` khai báo một lớp `extends AbstractException`; lớp duy nhất
+kế thừa thẳng `Error` là chính `AbstractException`; lint `throw-abstract-exception`,
+`exception-extends-abstract` và `exception-in-errors-folder` ở mức error cho `src/**` và chỉ tắt
+dưới `src/tests/**` và `apps/*/test/**`.
+
+## BE-ERROR-1 — Lớp gốc
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hình dạng | `export class AbstractException extends Error { readonly code: string; readonly metadata?: Record<string, unknown>; readonly httpStatus?: number; constructor(message: string, name: string, metadata?: Record<string, unknown>, httpStatus?: number) { super(message); this.code = name; this.name = name; this.metadata = metadata; this.httpStatus = httpStatus } … }` |
+| Case 2 | Tuần tự hóa | `toJSON(): string` → `{ message, code, metadata }`; `static fromJSON<T extends AbstractException>(…)` |
+| Case 3 | Nguyên nhân | `getOriginalError(): Error { return this.metadata?.originalError as Error }`; `export interface AbstractExceptionMetadata { originalError?: Error }` |
+| Case 4 | Mã trạng thái | `httpStatus` là tùy chọn; không định nghĩa nghĩa là 500 ở cả hai tầng vận chuyển |
+
+## BE-ERROR-2 — Khai báo một exception
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Interface metadata trước | `export interface ChallengeNotFoundExceptionMetadata extends AbstractExceptionMetadata { id?: string }` |
+| Case 2 | Lớp | `export class ChallengeNotFoundException extends AbstractException { constructor({ id, originalError }: ChallengeNotFoundExceptionMetadata) { super("Challenge not found", "CHALLENGE_NOT_FOUND_EXCEPTION", { id, originalError }) } }` |
+| Case 3 | Thông điệp nội suy | `` super(`AI quota exhausted (${window})`, "AI_QUOTA_EXHAUSTED_EXCEPTION", { window, originalError }) `` |
+| Case 4 | Có mã trạng thái | đối số thứ tư `HttpStatus.<X>` — được đặt ở 94 trên 294 tệp, bỏ trống ở phần còn lại |
+| Case 5 | Một đối số object duy nhất | luôn là một object metadata, kể cả khi rỗng: `throw new UserNotFoundException({})` (lint `require-exception-object-arg`) |
+
+## BE-ERROR-3 — Ném
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Chốt chặn trong handler | `if (!courseExists) { throw new CourseNotFoundException({ id: courseId }) }` |
+| Case 2 | Xung đột | `throw new CourseAlreadyEnrolledException({ courseId, userId: user.id })` |
+| Case 3 | Không bao giờ mã hóa thất bại vào giá trị trả về | handler trả entity hoặc ném; `success: false` xuất hiện ở 1 trên 154 handler (lint `no-handler-encoded-failure`) |
+| Case 4 | Không bao giờ `new Error` | `NewExpression[callee.name="Error"]` bị cấm trong `src/**` ngoài các làn kiểm thử |
+
+## BE-ERROR-4 — Bọc một lỗi bên ngoài
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Mã hóa | `catch (error) { throw new DecryptionFailedException({ originalError: error instanceof Error ? error : new Error(String(error)) }) }` (25 tệp ngoài cây exception bọc theo cách này) |
+| Case 2 | Phân tích con trỏ | `catch (error) { throw new CourseCommunityCursorException({ originalError: error as Error }) }` |
+| Case 3 | Bên tiêu thụ ít-nhất-một-lần | `catch (error) { const exception = new KafkaCdcMessageException({ topic, originalError: error instanceof Error ? error : undefined }); … ghi log và tiếp tục }` |
+| Case 4 | GraphQL thượng nguồn | `GraphQLDataNotFoundException({ query, variables, url, originalError })` |
+
+## BE-ERROR-5 — Ánh xạ HTTP
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Bộ lọc | `@Catch(AbstractException) export class AbstractExceptionHttpFilter implements ExceptionFilter { catch(exception: AbstractException, host: ArgumentsHost): void { if (host.getType<string>() === "graphql") { throw exception } const status = exception.httpStatus ?? HttpStatus.INTERNAL_SERVER_ERROR; … response.status(status).json({ statusCode: status, code: exception.code, message: exception.message }) } }` |
+| Case 2 | Đăng ký | `apps/core/src/app.module.ts`: `{ provide: APP_FILTER, useClass: AbstractExceptionHttpFilter }` |
+| Case 3 | Ghi log trước khi phản hồi | `this.winstonService.log(WinstonLog.HttpExceptionLogged, { op: "http.exception.logged", error: exception.message, meta: { code: exception.code, status } })` |
+| Case 4 | Host GraphQL | ném lại nguyên vẹn để đường ống của Apollo sở hữu nó |
+
+## BE-ERROR-6 — Ánh xạ GraphQL
+
+Hai lớp. Interceptor định hình thân trả về của resolver; `formatError` định hình mục `errors` của
+GraphQL và mã trạng thái vận chuyển.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Phong bì thành công | `GraphQLTransformInterceptor` ánh xạ mọi kết quả resolver thành `{ data, message, success: true }` với `message` lấy từ `@GraphQLSuccessMessage({ [Locale.En]: "…", [Locale.Vi]: "…" })` giải theo locale |
+| Case 2 | Phong bì thất bại | `catchError((err) => … observer.next({ success: false, message: err?.message ?? "Internal server error", error: err?.name ?? "Error" }))` — `error` mang `code` của exception vì `AbstractException` đặt `this.name = name` |
+| Case 3 | `formatError` | trong `MonolithicApolloServerModule`: `if (original instanceof AbstractException) { return { ...formattedError, extensions: { ...formattedError.extensions, code: original.code, http: { status: original.httpStatus ?? 500 }, …retryAfterSeconds } } }` |
+| Case 4 | Mọi thứ khác | `return { ...formattedError, extensions: { ...formattedError.extensions, http: { status: 500, ...(formattedError.extensions?.http as ApolloHttpExtension \| undefined) } } }` |
+| Case 5 | Mã trạng thái vận chuyển | `httpStatusFromExceptionsPlugin` đọc `extensions.http.status` và đặt mã HTTP thật |
+| Case 6 | Hợp đồng với client | `interface GraphQLResponse<T = unknown> { data?: T; message: string; success: boolean; error?: string }`; FE so khớp theo mã trong `error`, không theo mã trạng thái |
+
+## BE-ERROR-7 — Ghi log một thất bại
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Danh tính | một thành viên enum: `WinstonLog.HttpExceptionLogged` (lint `no-interpolated-log-message`, `no-error-wording-as-log-identity`) |
+| Case 2 | Payload | `{ op: "http.exception.logged", error: exception.message, meta: { code, status } }` |
+| Case 3 | Không bao giờ | `console.error`, `Logger` của Nest |

package/knowledge/patterns/be/folder.md

@@ -0,0 +1,87 @@
+# Folder
+
+This file answers one question: given a piece of backend code, which directory and which file
+name does it get?
+
+Sources: `src/features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`src/features/api/core/graphql/queries/courses/course/*`,
+`src/features/api/core/graphql/mutations/courses/courses.module.ts`,
+`src/modules/platform/{winston,throttler,exceptions}/`, `src/modules/ai/`,
+`src/modules/databases/postgresql/primary/{entities,enums}/`, `src/tests/`, `jest.config.ts`.
+
+## BE-FOLDER-1 — Two roots
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A door the outside world calls | `src/features/<door>/` — `api`, `socketio`, `cli`, `backup`, `mock`, `video-encoder` |
+| Case 2 | A capability doors compose | `src/modules/<capability>/` — `ai`, `api`, `bussiness`, `crypto`, `databases`, `filesystem`, `init`, `integrations`, `lib`, `membership`, `platform`, `playground-agent-core` |
+| Case 3 | Test infrastructure | `src/tests/{e2e,fixtures,harness,helpers,mocks}/` — e.g. `src/tests/mocks/entity-manager.mock.ts` |
+| Case 4 | Composition root | `apps/core/src/app.module.ts` (registers `AbstractExceptionHttpFilter` as `APP_FILTER`) |
+
+## BE-FOLDER-2 — One GraphQL unit
+
+A mutation or query is one kebab-case folder under its domain. The file set is fixed.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Mutation unit `mutations/courses/add-to-cart/` | `add-to-cart.command.ts` · `add-to-cart.handler.ts` · `add-to-cart.handler.spec.ts` · `add-to-cart.service.ts` · `add-to-cart.resolver.ts` · `add-to-cart.module.ts` · `add-to-cart.module-definition.ts` · `graphql-types/request.ts` · `graphql-types/response.ts` |
+| Case 2 | Query unit `queries/courses/course/` | `course.query.ts` · `course.handler.ts` · `course.handler.spec.ts` · `course.service.ts` · `course.resolver.ts` · `course.resolver.spec.ts` · `course.module.ts` · `course.module-definition.ts` · `graphql-types/request.ts` · `graphql-types/response.ts` |
+| Case 3 | Shared GraphQL objects | `features/api/core/graphql/shared/…` (`*.object.ts`, 14) |
+
+Counts under `features/api/core/graphql`: `.module.ts` 338, `.module-definition.ts` 336,
+`.resolver.ts` 305, `.service.ts` 203, `.handler.ts` 129, `.handler.spec.ts` 104, `.query.ts` 64,
+`.command.ts` 62, `.resolver.spec.ts` 59.
+
+## BE-FOLDER-3 — Domain aggregator
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | The domain folder | `mutations/courses/courses.module.ts` + `courses.module-definition.ts` beside the unit folders `add-to-cart/`, `clear-cart/`, `course-enroll/`, … |
+| Case 2 | Registration | `AddToCartSingleMutationModule.register({ … })` listed inside `courses.module.ts`; import alone is not registration |
+| Case 3 | Top aggregators | `mutations/mutations.module.ts`, `queries/queries.module.ts`, `graphql/graphql.module.ts`, `core/core.module.ts`, `api/api.module.ts`, each with a `.module-definition.ts` |
+
+## BE-FOLDER-4 — One capability module
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | `modules/platform/winston/` | `winston.module.ts` · `winston.module-definition.ts` · `winston.service.ts` · `winston.service.spec.ts` · `winston.providers.ts` · `winston.providers.spec.ts` · `winston.decorators.ts` · `config.ts` · `constants/` · `enums/` · `types/` · `utils/` |
+| Case 2 | `modules/platform/throttler/` | `throttler.module.ts` · `throttler.module-definition.ts` · `throttler.decorators.ts` · `config.ts` · `types.ts` · `enums/` · `guards/` · `types/` · `utils/` |
+| Case 3 | `modules/ai/` | `ai.module.ts` · `ai.module-definition.ts` · `ai-entitlement.service.ts` (+ `.spec.ts`) · `ai-invoke.service.ts` · `constants/ai-entitlement.constants.ts` · `balancer/` · `ping/` · `types/` · `utils/` |
+| Case 4 | Helper | `modules/bussiness/projections/user-stats/kpi-current.util.ts` (`.util.ts` beside its `types.ts`) |
+
+Counts under `src/modules`: `.service.ts` 396, `.service.spec.ts` 271, `.entity.ts` 197,
+`.module.ts` 116, `.module-definition.ts` 115, `.listener.ts` 18, `.providers.ts` 16,
+`.decorators.ts` 16, `.guard.ts` 11.
+
+## BE-FOLDER-5 — Exceptions have one home
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Any exception class | `src/modules/platform/exceptions/errors/<domain>/<name>.ts` — 294 files across `ai/ api/ backup/ bento4/ cache/ cli/ coding/ community/ courses/ …` (lint `exception-in-errors-folder`) |
+| Case 2 | The base | `errors/abstract.ts` |
+| Case 3 | Transport mapping | `exceptions/filters/abstract-exception-http.filter.ts` (+ `.spec.ts`) |
+| Case 4 | Enums used by exceptions | `exceptions/enums/ensure.ts`, `exceptions/enums/job.ts` |
+| Case 5 | Legacy suffix | five files still end in `.exception.ts` under `errors/mixin/`; the 289 others carry no suffix |
+
+## BE-FOLDER-6 — Data
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Entity | `modules/databases/postgresql/primary/entities/cart-item.entity.ts` (197 `.entity.ts`, 92 with `.entity.spec.ts`); base `entities/abstract.ts`, `abstract-projection.ts` |
+| Case 2 | Enum | `modules/databases/postgresql/primary/enums/locale.ts`, `enums/action-type.ts` (76 files export an enum here) |
+| Case 3 | Migration | `<timestamp>-<PascalCaseName>.ts`, e.g. `1719200000000-AddIsEnrolledToEnrollments.ts` — the only PascalCase file names in `src/` (95) |
+
+## BE-FOLDER-7 — Tests
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Unit | `<name>.spec.ts` beside `<name>.ts` (875) |
+| Case 2 | Integration | `<name>.int-spec.ts` beside its subject (7), e.g. `graphql/schema-builds.int-spec.ts` |
+| Case 3 | End-to-end and harness | `src/tests/e2e/`, `src/tests/harness/` (`*.e2e-spec.ts`, `*.harness-spec.ts`; `jest-harness.json`) |
+| Case 4 | Shared mocks | `src/tests/mocks/entity-manager.mock.ts` imported as `@tests/mocks/entity-manager.mock` |
+
+## Open question
+
+One class per exception file holds in 275 of 294 files; 19 files hold two to eight classes
+(`errors/api/graphql.ts`, `errors/community/*.ts`, `errors/users/user.ts`). The single-class form
+dominates and is what new files follow; the multi-class files are not declared wrong here.

package/knowledge/patterns/be/folder.vi.md

@@ -0,0 +1,86 @@
+# Thư mục
+
+Tệp này trả lời một câu hỏi: cho một mẩu mã backend, nó nằm ở thư mục nào và mang tên tệp gì?
+
+Nguồn: `src/features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`src/features/api/core/graphql/queries/courses/course/*`,
+`src/features/api/core/graphql/mutations/courses/courses.module.ts`,
+`src/modules/platform/{winston,throttler,exceptions}/`, `src/modules/ai/`,
+`src/modules/databases/postgresql/primary/{entities,enums}/`, `src/tests/`, `jest.config.ts`.
+
+## BE-FOLDER-1 — Hai gốc
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một cánh cửa thế giới bên ngoài gọi vào | `src/features/<door>/` — `api`, `socketio`, `cli`, `backup`, `mock`, `video-encoder` |
+| Case 2 | Một năng lực mà các cánh cửa ghép lại | `src/modules/<capability>/` — `ai`, `api`, `bussiness`, `crypto`, `databases`, `filesystem`, `init`, `integrations`, `lib`, `membership`, `platform`, `playground-agent-core` |
+| Case 3 | Hạ tầng kiểm thử | `src/tests/{e2e,fixtures,harness,helpers,mocks}/` — ví dụ `src/tests/mocks/entity-manager.mock.ts` |
+| Case 4 | Gốc ghép nối | `apps/core/src/app.module.ts` (đăng ký `AbstractExceptionHttpFilter` làm `APP_FILTER`) |
+
+## BE-FOLDER-2 — Một đơn vị GraphQL
+
+Một mutation hay query là một thư mục kebab-case dưới miền của nó. Bộ tệp là cố định.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đơn vị mutation `mutations/courses/add-to-cart/` | `add-to-cart.command.ts` · `add-to-cart.handler.ts` · `add-to-cart.handler.spec.ts` · `add-to-cart.service.ts` · `add-to-cart.resolver.ts` · `add-to-cart.module.ts` · `add-to-cart.module-definition.ts` · `graphql-types/request.ts` · `graphql-types/response.ts` |
+| Case 2 | Đơn vị query `queries/courses/course/` | `course.query.ts` · `course.handler.ts` · `course.handler.spec.ts` · `course.service.ts` · `course.resolver.ts` · `course.resolver.spec.ts` · `course.module.ts` · `course.module-definition.ts` · `graphql-types/request.ts` · `graphql-types/response.ts` |
+| Case 3 | Đối tượng GraphQL dùng chung | `features/api/core/graphql/shared/…` (`*.object.ts`, 14) |
+
+Số đếm dưới `features/api/core/graphql`: `.module.ts` 338, `.module-definition.ts` 336,
+`.resolver.ts` 305, `.service.ts` 203, `.handler.ts` 129, `.handler.spec.ts` 104, `.query.ts` 64,
+`.command.ts` 62, `.resolver.spec.ts` 59.
+
+## BE-FOLDER-3 — Bộ gom theo miền
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Thư mục miền | `mutations/courses/courses.module.ts` + `courses.module-definition.ts` bên cạnh các thư mục đơn vị `add-to-cart/`, `clear-cart/`, `course-enroll/`, … |
+| Case 2 | Đăng ký | `AddToCartSingleMutationModule.register({ … })` liệt kê trong `courses.module.ts`; import suông không phải đăng ký |
+| Case 3 | Các bộ gom cấp trên | `mutations/mutations.module.ts`, `queries/queries.module.ts`, `graphql/graphql.module.ts`, `core/core.module.ts`, `api/api.module.ts`, mỗi cái có `.module-definition.ts` |
+
+## BE-FOLDER-4 — Một module năng lực
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | `modules/platform/winston/` | `winston.module.ts` · `winston.module-definition.ts` · `winston.service.ts` · `winston.service.spec.ts` · `winston.providers.ts` · `winston.providers.spec.ts` · `winston.decorators.ts` · `config.ts` · `constants/` · `enums/` · `types/` · `utils/` |
+| Case 2 | `modules/platform/throttler/` | `throttler.module.ts` · `throttler.module-definition.ts` · `throttler.decorators.ts` · `config.ts` · `types.ts` · `enums/` · `guards/` · `types/` · `utils/` |
+| Case 3 | `modules/ai/` | `ai.module.ts` · `ai.module-definition.ts` · `ai-entitlement.service.ts` (+ `.spec.ts`) · `ai-invoke.service.ts` · `constants/ai-entitlement.constants.ts` · `balancer/` · `ping/` · `types/` · `utils/` |
+| Case 4 | Helper | `modules/bussiness/projections/user-stats/kpi-current.util.ts` (`.util.ts` cạnh `types.ts` của nó) |
+
+Số đếm dưới `src/modules`: `.service.ts` 396, `.service.spec.ts` 271, `.entity.ts` 197,
+`.module.ts` 116, `.module-definition.ts` 115, `.listener.ts` 18, `.providers.ts` 16,
+`.decorators.ts` 16, `.guard.ts` 11.
+
+## BE-FOLDER-5 — Exception có một nhà duy nhất
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Mọi lớp exception | `src/modules/platform/exceptions/errors/<domain>/<name>.ts` — 294 tệp trong `ai/ api/ backup/ bento4/ cache/ cli/ coding/ community/ courses/ …` (lint `exception-in-errors-folder`) |
+| Case 2 | Lớp gốc | `errors/abstract.ts` |
+| Case 3 | Ánh xạ vận chuyển | `exceptions/filters/abstract-exception-http.filter.ts` (+ `.spec.ts`) |
+| Case 4 | Enum mà exception dùng | `exceptions/enums/ensure.ts`, `exceptions/enums/job.ts` |
+| Case 5 | Hậu tố cũ | năm tệp vẫn kết thúc bằng `.exception.ts` dưới `errors/mixin/`; 289 tệp còn lại không có hậu tố |
+
+## BE-FOLDER-6 — Dữ liệu
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Entity | `modules/databases/postgresql/primary/entities/cart-item.entity.ts` (197 `.entity.ts`, 92 có `.entity.spec.ts`); gốc `entities/abstract.ts`, `abstract-projection.ts` |
+| Case 2 | Enum | `modules/databases/postgresql/primary/enums/locale.ts`, `enums/action-type.ts` (76 tệp export enum ở đây) |
+| Case 3 | Migration | `<timestamp>-<PascalCaseName>.ts`, ví dụ `1719200000000-AddIsEnrolledToEnrollments.ts` — tên tệp PascalCase duy nhất trong `src/` (95) |
+
+## BE-FOLDER-7 — Kiểm thử
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đơn vị | `<name>.spec.ts` cạnh `<name>.ts` (875) |
+| Case 2 | Tích hợp | `<name>.int-spec.ts` cạnh đối tượng của nó (7), ví dụ `graphql/schema-builds.int-spec.ts` |
+| Case 3 | Đầu cuối và harness | `src/tests/e2e/`, `src/tests/harness/` (`*.e2e-spec.ts`, `*.harness-spec.ts`; `jest-harness.json`) |
+| Case 4 | Mock dùng chung | `src/tests/mocks/entity-manager.mock.ts` import dưới tên `@tests/mocks/entity-manager.mock` |
+
+## Câu hỏi để ngỏ
+
+Một lớp cho một tệp exception đúng ở 275 trên 294 tệp; 19 tệp chứa từ hai đến tám lớp
+(`errors/api/graphql.ts`, `errors/community/*.ts`, `errors/users/user.ts`). Dạng một lớp chiếm ưu
+thế và là điều tệp mới đi theo; các tệp nhiều lớp không bị tuyên là sai ở đây.

package/knowledge/patterns/be/function.md

@@ -0,0 +1,80 @@
+# Function
+
+This file answers one question: given a backend handler, service, resolver, module or helper, what
+shape does it take, what does it receive, and what does it return?
+
+Sources: `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/course.handler.ts`,
+`modules/platform/cqrs/icqrs-handler.ts`, `features/api/core/types/execute.ts`,
+`modules/bussiness/projections/user-stats/kpi-current.util.ts`,
+`modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`.
+
+## BE-FUNCTION-1 — Handler: extend the template, override `process`
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Class head | `@CommandHandler(AddToCartCommand) @Injectable() export class AddToCartHandler extends ICQRSHandler<AddToCartCommand, CartItemEntity> implements ICommandHandler<AddToCartCommand, CartItemEntity>` (140 handlers extend `ICQRSHandler`; 138 also implement the Nest interface) |
+| Case 2 | Query variant | `@QueryHandler(CourseQuery) @Injectable() export class CourseHandler extends ICQRSHandler<CourseQuery, CourseEntity> implements IQueryHandler<CourseQuery, CourseEntity>` |
+| Case 3 | The one method | `protected override async process(command: AddToCartCommand): Promise<CartItemEntity> { … }` (140/140; lint `handler-overrides-process`) |
+| Case 4 | The public door | inherited: `async execute(params: TParams): Promise<TResponse> { return await this.process(params) }` in `ICQRSHandler` |
+| Case 5 | First statement | `const { request, user } = command.params` then guards |
+
+## BE-FUNCTION-2 — Message: an inert envelope
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Command | `export class AddToCartCommand { constructor(readonly params: ExecuteParams<AddToCartRequest>) {} }` |
+| Case 2 | Query | `export class CourseQuery { constructor(readonly params: ExecuteParams<CourseRequest>) {} }` |
+| Case 3 | The envelope type | `interface ExecuteParams<T> { request: T; locale?: Locale; user?: UserEntity; enrollmentId?: string; keycloakToken?: KeycloakTokenIntrospectResponse }` |
+| Case 4 | Nothing else | no methods, no derived fields (lint `message-carries-params-only`) |
+
+## BE-FUNCTION-3 — Service: forward to the bus
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Shape | `@Injectable() export class AddToCartService { constructor(private readonly commandBus: CommandBus) {} async execute(params: ExecuteParams<AddToCartRequest>): Promise<CartItemEntity> { return this.commandBus.execute(new AddToCartCommand(params)) } }` |
+| Case 2 | Query variant | same with `QueryBus` and `new CourseQuery(params)` |
+
+## BE-FUNCTION-4 — Resolver: decorate the door, build the envelope
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Method decorators, in this order | `@UseThrottler(ThrottlerConfig.Medium)` · `@UseGuards(KeycloakAuthGraphQLGuard)` · `@GraphQLSuccessMessage({ [Locale.En]: "…", [Locale.Vi]: "…" })` · `@UseInterceptors(GraphQLTransformInterceptor)` · `@Mutation(() => AddToCartResponse, { name: "addToCart", description: "…" })` |
+| Case 2 | Parameters | `@KeycloakGraphQLUser() user: UserEntity, @Args("request", { description: "…" }) request: AddToCartRequest, @GraphQLLocale() locale: Locale` |
+| Case 3 | Body | `return this.addToCartService.execute({ request, user, locale })` — one call, no logic |
+| Case 4 | Return type | the entity or object the `Response.data` field declares: `Promise<CartItemEntity>` |
+
+## BE-FUNCTION-5 — Constructor injection
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Required dependency | `constructor(private readonly s3ReadService: S3ReadService, private readonly s3NameResolverService: S3NameResolverService) { super() }` (2489 `private readonly` against 26 `private` without `readonly`) |
+| Case 2 | Entity manager | `@InjectPrimaryPostgreSQLEntityManager() private readonly entityManager: EntityManager` — never a repository (lint `must-inject-entity-manager`, `no-injected-repository`) |
+| Case 3 | Optional dependency | `@Optional() private readonly mountFilesystemService?: MountFilesystemService` |
+| Case 4 | Handler | calls `super()` because `ICQRSHandler` is an abstract class |
+
+## BE-FUNCTION-6 — Guards, then work, then return
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Authentication | `if (!user) { throw new UserNotFoundException({}) }` before any query |
+| Case 2 | Existence | `const courseExists = await this.entityManager.exists(CourseEntity, { where: { id: courseId } }); if (!courseExists) { throw new CourseNotFoundException({ id: courseId }) }` |
+| Case 3 | Idempotent read-before-write | `const existing = await this.entityManager.findOne(CartItemEntity, { where: { course: { id: courseId }, user: { id: user.id } } }); if (existing) { return existing }` |
+| Case 4 | Persist | `const cartItem = this.entityManager.create(CartItemEntity, { user: { id: user.id }, course: { id: courseId } }); return this.entityManager.save(cartItem)` |
+
+## BE-FUNCTION-7 — Helpers
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Pure mapping shared by two callers | `export const getKpiCurrentValues = (stats: UserStatsResult): Record<KpiKey, number> => ({ [KpiKey.Lessons]: stats.weeklyLessons, … })` in `kpi-current.util.ts` (245 exported arrow consts against 20 `export function` under `src/modules`) |
+| Case 2 | Decorator factory | `export const GraphQLSuccessMessage = (message: GraphQLSuccessMessage) => SetMetadata(SUCCESS_MESSAGE_METADATA, message)` |
+| Case 3 | Parameter list | a named interface, not an inline object (lint `no-inline-param-type`); single primitive params stay positional |
+| Case 4 | Where it lives | beside its consumer as `<name>.util.ts`, or under the module's `utils/` |
+
+## BE-FUNCTION-8 — Module
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Definition file | `export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = new ConfigurableModuleBuilder().setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal })).build()` |
+| Case 2 | Module file | `@Module({ providers: [AddToCartService, AddToCartResolver, AddToCartHandler] }) export class AddToCartSingleMutationModule extends ConfigurableModuleClass {}` |
+| Case 3 | Registration by the parent | `AddToCartSingleMutationModule.register({ … })` in `courses.module.ts` |

package/knowledge/patterns/be/function.vi.md

@@ -0,0 +1,80 @@
+# Hàm
+
+Tệp này trả lời một câu hỏi: cho một handler, service, resolver, module hay helper backend, nó có
+hình dạng gì, nhận gì, và trả về gì?
+
+Nguồn: `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/course.handler.ts`,
+`modules/platform/cqrs/icqrs-handler.ts`, `features/api/core/types/execute.ts`,
+`modules/bussiness/projections/user-stats/kpi-current.util.ts`,
+`modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`.
+
+## BE-FUNCTION-1 — Handler: kế thừa khuôn, ghi đè `process`
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đầu lớp | `@CommandHandler(AddToCartCommand) @Injectable() export class AddToCartHandler extends ICQRSHandler<AddToCartCommand, CartItemEntity> implements ICommandHandler<AddToCartCommand, CartItemEntity>` (140 handler kế thừa `ICQRSHandler`; 138 đồng thời implement giao diện của Nest) |
+| Case 2 | Biến thể query | `@QueryHandler(CourseQuery) @Injectable() export class CourseHandler extends ICQRSHandler<CourseQuery, CourseEntity> implements IQueryHandler<CourseQuery, CourseEntity>` |
+| Case 3 | Phương thức duy nhất | `protected override async process(command: AddToCartCommand): Promise<CartItemEntity> { … }` (140/140; lint `handler-overrides-process`) |
+| Case 4 | Cửa công khai | kế thừa: `async execute(params: TParams): Promise<TResponse> { return await this.process(params) }` trong `ICQRSHandler` |
+| Case 5 | Câu lệnh đầu tiên | `const { request, user } = command.params` rồi các chốt chặn |
+
+## BE-FUNCTION-2 — Thông điệp: một phong bì trơ
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Command | `export class AddToCartCommand { constructor(readonly params: ExecuteParams<AddToCartRequest>) {} }` |
+| Case 2 | Query | `export class CourseQuery { constructor(readonly params: ExecuteParams<CourseRequest>) {} }` |
+| Case 3 | Kiểu phong bì | `interface ExecuteParams<T> { request: T; locale?: Locale; user?: UserEntity; enrollmentId?: string; keycloakToken?: KeycloakTokenIntrospectResponse }` |
+| Case 4 | Không gì khác | không phương thức, không trường suy diễn (lint `message-carries-params-only`) |
+
+## BE-FUNCTION-3 — Service: chuyển tiếp lên bus
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hình dạng | `@Injectable() export class AddToCartService { constructor(private readonly commandBus: CommandBus) {} async execute(params: ExecuteParams<AddToCartRequest>): Promise<CartItemEntity> { return this.commandBus.execute(new AddToCartCommand(params)) } }` |
+| Case 2 | Biến thể query | tương tự với `QueryBus` và `new CourseQuery(params)` |
+
+## BE-FUNCTION-4 — Resolver: trang trí cánh cửa, dựng phong bì
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Decorator phương thức, theo thứ tự này | `@UseThrottler(ThrottlerConfig.Medium)` · `@UseGuards(KeycloakAuthGraphQLGuard)` · `@GraphQLSuccessMessage({ [Locale.En]: "…", [Locale.Vi]: "…" })` · `@UseInterceptors(GraphQLTransformInterceptor)` · `@Mutation(() => AddToCartResponse, { name: "addToCart", description: "…" })` |
+| Case 2 | Tham số | `@KeycloakGraphQLUser() user: UserEntity, @Args("request", { description: "…" }) request: AddToCartRequest, @GraphQLLocale() locale: Locale` |
+| Case 3 | Thân | `return this.addToCartService.execute({ request, user, locale })` — một lời gọi, không logic |
+| Case 4 | Kiểu trả về | entity hoặc object mà trường `Response.data` khai báo: `Promise<CartItemEntity>` |
+
+## BE-FUNCTION-5 — Tiêm qua constructor
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Phụ thuộc bắt buộc | `constructor(private readonly s3ReadService: S3ReadService, private readonly s3NameResolverService: S3NameResolverService) { super() }` (2489 `private readonly` so với 26 `private` không `readonly`) |
+| Case 2 | Entity manager | `@InjectPrimaryPostgreSQLEntityManager() private readonly entityManager: EntityManager` — không bao giờ là repository (lint `must-inject-entity-manager`, `no-injected-repository`) |
+| Case 3 | Phụ thuộc tùy chọn | `@Optional() private readonly mountFilesystemService?: MountFilesystemService` |
+| Case 4 | Handler | gọi `super()` vì `ICQRSHandler` là lớp trừu tượng |
+
+## BE-FUNCTION-6 — Chốt chặn, rồi việc, rồi trả về
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Xác thực | `if (!user) { throw new UserNotFoundException({}) }` trước mọi truy vấn |
+| Case 2 | Tồn tại | `const courseExists = await this.entityManager.exists(CourseEntity, { where: { id: courseId } }); if (!courseExists) { throw new CourseNotFoundException({ id: courseId }) }` |
+| Case 3 | Đọc-trước-ghi lũy đẳng | `const existing = await this.entityManager.findOne(CartItemEntity, { where: { course: { id: courseId }, user: { id: user.id } } }); if (existing) { return existing }` |
+| Case 4 | Lưu | `const cartItem = this.entityManager.create(CartItemEntity, { user: { id: user.id }, course: { id: courseId } }); return this.entityManager.save(cartItem)` |
+
+## BE-FUNCTION-7 — Helper
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Ánh xạ thuần dùng chung bởi hai bên gọi | `export const getKpiCurrentValues = (stats: UserStatsResult): Record<KpiKey, number> => ({ [KpiKey.Lessons]: stats.weeklyLessons, … })` trong `kpi-current.util.ts` (245 arrow const được export so với 20 `export function` dưới `src/modules`) |
+| Case 2 | Nhà máy decorator | `export const GraphQLSuccessMessage = (message: GraphQLSuccessMessage) => SetMetadata(SUCCESS_MESSAGE_METADATA, message)` |
+| Case 3 | Danh sách tham số | một interface có tên, không phải object nội tuyến (lint `no-inline-param-type`); tham số nguyên thủy đơn lẻ giữ dạng vị trí |
+| Case 4 | Nơi sống | cạnh bên tiêu thụ dưới tên `<name>.util.ts`, hoặc dưới `utils/` của module |
+
+## BE-FUNCTION-8 — Module
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Tệp định nghĩa | `export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = new ConfigurableModuleBuilder().setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal })).build()` |
+| Case 2 | Tệp module | `@Module({ providers: [AddToCartService, AddToCartResolver, AddToCartHandler] }) export class AddToCartSingleMutationModule extends ConfigurableModuleClass {}` |
+| Case 3 | Đăng ký bởi cha | `AddToCartSingleMutationModule.register({ … })` trong `courses.module.ts` |

package/knowledge/patterns/be/imports.md

@@ -0,0 +1,79 @@
+# Imports
+
+This file answers one question: given a backend file, what may it import, through which path, in
+which style, and in which order?
+
+Sources: `tsconfig.json` (`paths`), `jest.config.ts` (`moduleNameMapper`), `eslint.config.mjs`,
+`features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/course.handler.ts`,
+`modules/platform/exceptions/errors/ai/ai-quota-exhausted.ts`,
+`modules/platform/exceptions/filters/abstract-exception-http.filter.ts`.
+
+## BE-IMPORTS-1 — Aliases
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A capability | `@modules/<capability>/<deep path to file>` — `import { ICQRSHandler } from "@modules/platform/cqrs/icqrs-handler"` |
+| Case 2 | A door | `@features/<door>/…` (used from `apps/` and tests) |
+| Case 3 | Test helpers | `import { makeEntityManagerMock } from "@tests/mocks/entity-manager.mock"` |
+| Case 4 | Inside one unit | `./add-to-cart.command`, `./graphql-types/request`, `./add-to-cart.service` |
+| Case 5 | Up the same door | `import { ExecuteParams } from "../../../../types/execute"` — 290 files under `features` use this relative path; 0 use `@features/api/core/types/execute` (lint `no-self-module-alias`) |
+| Case 6 | Inside the exceptions tree | `import { AbstractException } from "../abstract"` |
+
+## BE-IMPORTS-2 — Brace style
+
+Every import is multi-line, one binding per line, trailing comma. Lint `object-curly-newline`
+with `ImportDeclaration: "always"` enforces it.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | One binding | `import {\n    Injectable,\n} from "@nestjs/common"` |
+| Case 2 | Several | `import {\n    CommandHandler,\n    ICommandHandler,\n} from "@nestjs/cqrs"` |
+| Case 3 | Type only | `import type {\n    EntityManager,\n} from "typeorm"`; `import type {\n    AbstractExceptionMetadata,\n} from "../abstract"` (1388 of 4463 files use `import type`) |
+
+## BE-IMPORTS-3 — Order
+
+Not lint-enforced. The dominant first import in GraphQL unit files is the Nest framework.
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Framework first | `@nestjs/graphql`, `@nestjs/common`, `@nestjs/cqrs` (first import in 303 of 398 sampled GraphQL files) |
+| Case 2 | Then capabilities | `@modules/api/…`, `@modules/integrations/…`, `@modules/platform/…`, `@modules/databases/…` (46 files start here) |
+| Case 3 | Then relative | `../../../../types/execute` (41 start here), then `./…` last (7) |
+| Case 4 | Deviation | `add-to-cart.handler.ts` opens with `@modules/platform/cqrs/icqrs-handler` and interleaves `@nestjs/common` after several `@modules` imports; the order above is dominant, not universal |
+
+## BE-IMPORTS-4 — Layering direction
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | `features` → `modules` | always allowed: a handler imports entities, exceptions, decorators from `@modules/…` |
+| Case 2 | `modules` → `features` | not allowed (lint `no-capability-imports-features`); 6 non-spec files under `modules/bussiness/{daily-quest,flashcard,kpi-reward,streak,weekly-challenge}` still do — recorded debt, not a pattern |
+| Case 3 | `modules/**/*.module.ts` → another in-repo module | not imported; capability modules are registered `isGlobal: true` at the app root (lint `no-non-global-module-import`, error in both `src/modules` and `src/features`) |
+| Case 4 | Folder barrel | none exist to import; every import names a file (lint `must-deep-module-import`, `no-folder-reexport`) |
+| Case 5 | Relative escape across capabilities | `from "../../modules/…"` occurs in 0 files (lint `no-relative-capability-escape`) |
+
+## BE-IMPORTS-5 — What a GraphQL unit imports
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Handler | `@modules/platform/cqrs/icqrs-handler`, entities from `@modules/databases/postgresql/primary/entities/*.entity`, exceptions from `@modules/platform/exceptions/errors/<domain>/<name>`, `@nestjs/common`, `@nestjs/cqrs`, `typeorm` (type), `./<name>.command` |
+| Case 2 | Resolver | `@nestjs/graphql`, `@nestjs/common`, `@modules/api/apollo/server/decorators/locale.decorators`, `@modules/api/apollo/server/interceptors/graphql-transform.interceptor`, `@modules/integrations/keycloak/guards/keycloak-auth-graphql.guard`, `@modules/integrations/keycloak/keycloak.decorators`, `@modules/platform/throttler/*`, `./graphql-types/request`, `./graphql-types/response`, `./<name>.service` |
+| Case 3 | Response | `@nestjs/graphql`, `@modules/api/apollo/server/graphql-types/object-types/graphql-response`, `@modules/api/apollo/server/types/graphql-response`, the entity |
+| Case 4 | Module | `@nestjs/common` and the four sibling files |
+
+## BE-IMPORTS-6 — Forbidden
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Default export | none (lint `no-default-export`; Jest lifecycle entries carved out) |
+| Case 2 | `process.env` | only `src/modules/platform/env/utils/parse-env.ts`; everyone else calls `envConfig()` |
+| Case 3 | `console.*` | lint error in `src/**`; 188 files log through `WinstonService`, 12 residual `console.` sites |
+| Case 4 | Nest `Logger` | not used (lint `no-nest-logger`, `no-framework-logger`) |
+| Case 5 | Raw cache tokens outside the cache module | lint `must-use-cache-service` |
+
+## BE-IMPORTS-7 — Jest sees the same aliases
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | `jest.config.ts` | `moduleNameMapper: { "^@modules/(.*)$": "<rootDir>/src/modules/$1", "^@features/(.*)$": "<rootDir>/src/features/$1", "^@tests/(.*)$": "<rootDir>/src/tests/$1" }` |
+| Case 2 | Spec mocking a module path | `jest.mock("@modules/platform/env/config", () => ({ envConfig: () => ({ … }) }))` |