@gennext/lb-infra 0.2.3 → 0.3.0

package/README.md

@@ -1,298 +1,578 @@
-# 📘 Cẩm nang Kĩ thuật: @gennext/lb-infra
+# @gennext/lb-infra
 
-Hạ tầng Backend Hybrid chuẩn Gennex: Kết hợp sức mạnh kiến trúc của **LoopBack 4** và hiệu năng của **Hono/Drizzle**.
+Gennex Technology - LoopBack 4 infrastructure framework.
 
----
+`@gennext/lb-infra` provides shared base classes, components, helpers, datasources, model mixins, repositories and controller generators for building backend services on top of LoopBack 4.
 
-## 🏗 1. Tổng quan kiến trúc & Cài đặt
+## Requirements
 
-### 1.1 Hybrid Platform
+- Node.js `>= 18`
+- Bun `>= 1.3.2`
+- TypeScript
 
-Thư viện cung cấp hai lộ trình phát triển:
+Install dependencies from the repository root:
 
-- **Hono Path (Modern):** Cho các service yêu cầu tốc độ cao, hỗ trợ OpenAPI native qua Zod.
-- **LoopBack Path (Standard):** Cho các ứng dụng phức tạp cần DI (Dependency Injection) và tính tương thích ngược.
+```bash
+bun install
+```
 
-### 1.2 Cấu trúc Export (Sub-paths)
+## Package Scripts
 
-Được cấu hình trong `package.json`, giúp developer import sạch sẽ:
+Run commands from the repository root:
 
-- `@gennext/lb-infra`: Entry chính (Hono, Drizzle, Utilities).
-- `@gennext/lb-infra/lb-core`: LoopBack Core (Binding, Context, Metadata).
-- `@gennext/lb-infra/lb-rest`: LoopBack Rest (Decorators, Sequence).
-- `@gennext/lb-infra/lb-repo`: LoopBack Repository (Juggler, Filter).
-- `@gennext/lb-infra/socket-io`: WebSocket component.
-- `@gennext/lb-infra/grpc`: gRPC component.
+```bash
+bun run --filter "@gennext/lb-infra" build
+bun run --filter "@gennext/lb-infra" clean
+bun run --filter "@gennext/lb-infra" rebuild
+bun run --filter "@gennext/lb-infra" lint
+bun run --filter "@gennext/lb-infra" test
+```
 
-### 1.3 Pin Dependencies (Không cần cài thêm)
+Root shortcut:
 
-Thư viện đã đóng gói sẵn và re-export các "vũ khí" sau:
+```bash
+bun run rebuild:lb-infra
+```
 
-- **Framework:** `Hono`, `@hono/zod-openapi`, `zod`.
-- **Database:** `Drizzle ORM` (core + pg), `pg` (node-postgres).
-- **Utilities:** `axios`, `lodash`, `dayjs` (thông qua `date.utility`).
+The build script compiles TypeScript, resolves aliases with `tsc-alias`, then copies runtime assets into `dist`:
 
----
+- `src/components/authenticate/views`
+- `static`
+- `tsconfig.json` as `dist/tsconfig.base.json`
 
-## 🚀 2. Application Kernel
+## CLI
 
-### 2.1 Khởi tạo với `BaseApplication`
+After the package is installed, the `lb-infra` binary can scaffold the default consumer-app folder structure:
 
-Mọi ứng dụng phải kế thừa từ class này.
+```bash
+lb-infra init
+```
 
-**Interface `IApplicationConfigs`:**
+Or target another directory:
 
-- `port`: (Bắt buộc) Cổng chạy server.
-- `host?`: Hostname (Mặc định `0.0.0.0`).
-- `path?`: `{ base: string, isStrict?: boolean }` - Prefix cho API.
-- `debug?`: `{ shouldShowRoutes?: boolean }` - In ra danh sách route khi startup.
+```bash
+lb-infra init ./apps/api
+```
 
-**Vòng đời (Lifecycle) trong `start()`:**
+Generated structure:
+
+```text
+src
+├── components
+├── controllers
+├── datasources
+├── interceptors
+├── middlewares
+├── migrations
+├── models
+├── protos
+├── repositories
+├── services
+└── types
+public
+```
 
-1. `preConfigure()`: Thiết lập biến môi trường, kết nối DB sớm.
-2. `setupMiddlewares()`: Đăng ký Logger, CORS, v.v.
-3. `boot()`: Tự động đăng ký Controllers/Services (khi dùng `bootMixin`).
-4. `postConfigure()`: Chạy các tác vụ sau khi server đã lắng nghe.
+The command creates `index.ts` placeholders for TypeScript folders and `.gitkeep` files for asset/proto/migration folders. Existing placeholder files are not overwritten unless `--force` is passed:
 
-### 2.2 Dependency Injection (DI)
+```bash
+lb-infra init ./apps/api --force
+```
 
-Hệ thống sử dụng Map-based Binding:
+## Main Imports
+
+```ts
+import {
+  BaseApplication,
+  DefaultRestApplication,
+  defineCrudController,
+  defineKVController,
+  TzCrudRepository,
+  SearchableTzCrudRepository,
+} from '@gennext/lb-infra';
+```
 
-- **Bind:** `app.bind({ key: 'services.UserService' }).toClass(UserService)`
-- **Get:** `const service = app.get<UserService>({ key: 'services.UserService' })`
-- **Namespaces:** Nên dùng `BindingNamespaces.SERVICE`, `.CONTROLLER`, `.REPOSITORY`, `.DATASOURCE`.
+LoopBack re-export aliases:
 
----
+```ts
+import {inject, injectable, BindingScope} from '@gennext/lb-infra/lb-core';
+import {api, get, post, param, requestBody} from '@gennext/lb-infra/lb-rest';
+import {model, property, repository} from '@gennext/lb-infra/lb-repo';
+import {authenticate, TokenServiceBindings} from '@gennext/lb-infra/lb-auth';
+```
 
-## 🪵 3. Hệ thống Logger & Context
+Optional feature exports:
 
-### 3.1 Logger nâng cao
+```ts
+import {SocketIOComponent} from '@gennext/lb-infra/socket-io';
+import {GrpcServerComponent} from '@gennext/lb-infra/grpc';
+```
 
-Được xây dựng trên Winston, hỗ trợ ghi log đa kênh.
+## Project Layout
+
+```text
+src
+├── base          # base application, sequence, models, repositories, controllers
+├── common        # constants, environment keys, shared types
+├── components    # auth, authorize, migration, mail, socket.io, grpc, health check
+├── datasources   # postgres, redis, memory datasources
+├── helpers       # logger, queue, redis, network, crypto, storage, testing
+├── interceptors  # global interceptors
+├── middlewares   # request middleware
+├── migrations    # migration helpers
+├── mixins        # model mixins
+└── utilities     # shared utility functions
+```
 
-**Các Method:**
+## Base Application
 
-- `debug(msg, ...args)`: ⚠️ Chỉ hoạt động nếu `NODE_ENV` là local/dev/alpha... **VÀ** biến `DEBUG=true`.
-- `withScope(scope)`: Gắn prefix cho log.
-- `for(method)`: Child logger cho từng hàm cụ thể (có cache để tối ưu).
+Use `BaseApplication` when you want full control over configuration:
 
-**UDP Logging (`DgramTransport`):**
-Gửi log qua socket UDP (ví dụ đến Logstash/Graylog).
-Cấu hình qua `IDgramTransportOptions`: `host`, `port`, `levels` (các mức log muốn gửi đi).
+```ts
+import {BaseApplication} from '@gennext/lb-infra';
+import {ApplicationConfig} from '@gennext/lb-infra/lb-core';
 
-### 3.2 RequestContext & HttpAccessLogger
+export class MyApplication extends BaseApplication {
+  constructor(options: ApplicationConfig = {}) {
+    super({
+      scope: 'MyApplication',
+      serverOptions: options,
+    });
+  }
 
-Dùng để theo vết request ID xuyên suốt các tầng.
+  staticConfigure(): void {
+    // Bind components, datasources, repositories, services and controllers.
+  }
 
-- **Tự động hóa:** Middleware tự lấy `x-request-id` từ header hoặc tự sinh mới.
-- **Data Masking:** Tự động ẩn thông tin nhạy cảm trong log: `authorization`, `cookie`, `session`, `password`.
+  getProjectRoot(): string {
+    return __dirname;
+  }
 
----
+  validateEnv() {
+    return {result: true};
+  }
 
-## 🗄️ 4. Data Layer (Drizzle ORM)
+  declareModels(): Set<string> {
+    return new Set([]);
+  }
 
-### 4.1 Schema Helpers (`column-defs.ts`)
+  preConfigure(): void {}
 
-Giúp định nghĩa bảng chuẩn Gennex:
+  postConfigure(): void {}
+}
+```
 
-- `generateIdColumnDefs()`: Cột `id` (Serial hoặc UUID).
-- `generateTzColumnDefs()`: Cột `created_at`, `modified_at` tự động cập nhật.
-- `generateSoftDeleteColumnDefs()`: Cột `deleted_at`.
+Use `DefaultRestApplication` when you want the standard setup with environment validation, PostgreSQL, in-memory KV datasource, migration component, content-range interceptor and boot options.
+
+## Models And Mixins
+
+Common base models:
+
+- `BaseEntity`
+- `BaseKVEntity`
+- `BaseTzEntity`
+- `BaseUserAuditTzEntity`
+- `BaseTextSearchTzEntity`
+- `BaseObjectSearchTzEntity`
+- `BaseSearchableTzEntity`
+- `BaseSoftDeleteTzEntity`
+
+Common mixins:
+
+- `IdMixin`
+- `TzMixin`
+- `UserAuditMixin`
+- `SoftDeleteModelMixin`
+- `SoftPersistentMixin`
+- `TextSearchMixin`
+- `ObjectSearchMixin`
+- `VectorMixin`
+- `DuplicatableMixin`
+- `DataTypeMixin`
+- `PrincipalMixin`
+
+Example:
+
+```ts
+import {BaseUserAuditTzEntity} from '@gennext/lb-infra';
+import {model, property} from '@gennext/lb-infra/lb-repo';
+
+@model({
+  settings: {
+    postgresql: {
+      schema: 'public',
+      table: 'user',
+    },
+    strict: true,
+  },
+})
+export class User extends BaseUserAuditTzEntity {
+  @property({type: 'string', required: true})
+  email: string;
+}
+```
 
-### 4.2 Tầng Repository (Tiering)
+## Repositories
 
-- **ReadableRepository**: Tìm kiếm cơ bản.
-- **DefaultCRUDRepository**: Thao tác Thêm/Sửa/Xóa.
-- **SoftDeletableRepository**: 💡 Tự động thêm điều kiện `deleted_at IS NULL` vào mọi câu query.
-  - `hardDeleteById()`: Xóa vĩnh viễn.
-  - `restore()`: Khôi phục bản ghi đã xóa.
+Use the base repositories in `src/base/repositories`:
 
----
+- `TzCrudRepository`
+- `SearchableTzCrudRepository`
+- `KVRepository`
 
-## ⚡ 5. Redis & Caching
+Example:
 
-### 5.1 RedisManager
+```ts
+import {PostgresDataSource, TzCrudRepository} from '@gennext/lb-infra';
+import {inject, injectable, BindingScope} from '@gennext/lb-infra/lb-core';
 
-Quản lý tập trung các instance Redis. Hỗ trợ cả **Standalone** và **Cluster mode**.
+@injectable({scope: BindingScope.SINGLETON})
+export class UserRepository extends TzCrudRepository<User> {
+  constructor(@inject('datasources.postgres') dataSource: PostgresDataSource) {
+    super(User, dataSource);
+  }
+}
+```
 
-### 5.2 DefaultRedisHelper API
+## Controller Generators
 
-- `set({ key, value, options: { ttl } })`: Lưu object (tự serialize JSON).
-- `getObject({ key })`: Lấy và tự parse JSON.
-- `publish({ topics, payload, useCompress })`: Pub/Sub có hỗ trợ nén zlib để tiết kiệm băng thông.
+### CRUD
 
----
+`defineCrudController` creates standard CRUD routes:
 
-## 🌐 6. HTTP Layer (Hono + OpenAPI)
+- `GET /`
+- `POST /`
+- `PATCH /`
+- `GET /count`
+- `GET /find-one`
+- `GET /{id}`
+- `PATCH /{id}`
+- `PUT /{id}`
+- `DELETE /{id}`
 
-### 6.1 BaseController
+Example:
 
-Sử dụng `bindRoute` để có được sự hỗ trợ tuyệt đối từ TypeScript và tự sinh Swagger.
+```ts
+import {defineCrudController} from '@gennext/lb-infra';
+import {api} from '@gennext/lb-infra/lb-rest';
 
-```typescript
-this.bindRoute({
-  configs: {
-    path: '/:id',
-    method: 'get',
-    request: { params: zod.object({ id: zod.string() }) },
-    responses: { 200: jsonResponse({ schema: UserSchema, description: 'User info' }) },
-  },
-}).to({
-  handler: async c => {
-    const id = c.req.param('id');
-    // ... logic
+const BaseUserController = defineCrudController<User>({
+  entity: User,
+  repository: {name: 'UserRepository'},
+  controller: {
+    basePath: '/users',
+    readonly: false,
   },
 });
+
+@api({basePath: '/users'})
+export class UserController extends BaseUserController {}
 ```
 
----
+When extending generated controllers, keep custom method paths relative to the class base path:
 
-## 🧰 7. Bộ tiện ích (Utilities Deep Dive)
+```ts
+@get('/search')
+search() {}
+```
 
-| Utility     | Method tiêu biểu                                                | Mô tả                                 |
-| :---------- | :-------------------------------------------------------------- | :------------------------------------ |
-| **parse**   | `getUID()`, `keysToCamel()`, `toBoolean()`, `int()`, `float()`  | Xử lý kiểu dữ liệu và format key.     |
-| **crypto**  | `hashPassword()`, `comparePassword()`, `encrypt()`, `decrypt()` | Bảo mật mật khẩu và mã hóa AES.       |
-| **error**   | `getError()`, `ValidationError()`, `NotImplementedError()`      | Tạo lỗi chuẩn hóa có Status Code.     |
-| **model**   | `buildRequestBody()`, `buildPaginationResponse()`               | Tự động sinh OpenAPI schema từ Model. |
-| **promise** | `delay(ms)`                                                     | Hàm ngủ async.                        |
-| **axios**   | `get()`, `post()`, `put()`, `del()`                             | Wrapper axios kèm xử lý lỗi chuẩn.    |
+### Key-Value
 
----
+Use `defineKVController` for `BaseKVEntity` models and key-value repositories:
 
-## 🔑 8. Auth & Security
+```ts
+@api({basePath: '/sessions'})
+export class SessionController extends defineKVController<Session>({
+  entity: Session,
+  repository: {name: 'SessionRepository'},
+  controller: {
+    basePath: '/sessions',
+    readonly: false,
+  },
+}) {}
+```
 
-### 8.1 Authentication
+### Relations
 
-- Đăng ký `AuthenticateComponent`.
-- Hỗ trợ `JwtStrategy` (đọc secret từ `APP_ENV_APPLICATION_SECRET`).
+Use `defineRelationViewController` or `defineRelationCrudController` for relation endpoints:
 
-### 8.2 Authorization (Casbin)
+```ts
+@api({basePath: '/users'})
+export class UserPostRelationController extends defineRelationViewController<User, Post>({
+  entities: {source: User, target: Post},
+  relation: {name: 'posts', type: EntityRelations.HAS_MANY},
+  endPoint: 'posts',
+}) {}
+```
 
-⚠️ Cần cài `casbin`.
+## gRPC Usage Example
 
-- `CasbinDrizzleAdapter`: Lưu Policy vào bảng DB do Drizzle quản lý.
-- `CasbinEnforcer`: Check quyền bằng cú pháp: `enforcer.enforce(user, object, action)`.
+The gRPC module is exported from `@gennext/lb-infra/grpc`.
 
----
+The server flow is:
 
-## 🧪 9. Ví dụ: Full User Flow
+1. Create a `.proto` file.
+2. Create a controller method and decorate it with `@grpcMethod`.
+3. Register the controller with `app.grpcController(...)`.
+4. Configure `GrpcServerKeys.GRPC_OPTIONS`.
+5. Register `GrpcServerComponent`.
 
-```typescript
-// --- 1. Model ---
-export const users = pgTable('users', {
-  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-  email: text('email').notNull().unique(),
-  ...generateTzColumnDefs(),
-  ...generateSoftDeleteColumnDefs(),
-});
+### Proto File
+
+Example file: `src/protos/user.proto`
+
+```proto
+syntax = "proto3";
+
+package demo;
+
+service UserService {
+  rpc GetUser (GetUserRequest) returns (GetUserResponse);
+}
+
+message GetUserRequest {
+  int32 id = 1;
+}
+
+message GetUserResponse {
+  int32 id = 1;
+  string email = 2;
+  string fullName = 3;
+}
+```
+
+### gRPC Controller
+
+```ts
+import {BaseGrpcController, grpcController, grpcMethod} from '@gennext/lb-infra/grpc';
+
+type GetUserRequest = {
+  id: number;
+};
 
-// --- 2. Repository ---
-export class UserRepository extends SoftDeletableRepository<typeof users> {
+type GetUserResponse = {
+  id: number;
+  email: string;
+  fullName: string;
+};
+
+@grpcController()
+export class UserGrpcController extends BaseGrpcController {
   constructor() {
-    super(users);
+    super({scope: UserGrpcController.name});
   }
-}
 
-// --- 3. Controller ---
-@controller({ path: '/users' })
-export class UserController extends BaseController {
-  async binding() {
-    this.bindRoute({
-      configs: {
-        path: '/',
-        method: 'get',
-        responses: { 200: { description: 'List' } },
-      },
-    }).to({
-      handler: async c => {
-        const repo = app.get<UserRepository>({ key: 'repositories.UserRepository' });
-        return c.json(await repo.findAll());
-      },
-    });
+  @grpcMethod({
+    proto: 'user.proto',
+    service: 'demo.UserService',
+    method: 'GetUser',
+  })
+  async getUser(request: GetUserRequest): Promise<GetUserResponse> {
+    return {
+      id: request.id,
+      email: `user-${request.id}@example.com`,
+      fullName: `User ${request.id}`,
+    };
   }
 }
 ```
 
----
+`service` must match the package and service path loaded from the proto definition. In the example above, `package demo; service UserService` becomes `demo.UserService`.
 
-## 🛠️ 10. Scripts
+`method` must match the RPC method name in the proto. If `method` is omitted, the TypeScript method name is used.
 
-- `bun run build`: Build project (TSC + tsc-alias).
-- `bun run migrate:push`: Đẩy schema Drizzle lên Database.
-- `bun run lint`: Kiểm tra code style các file mới thay đổi.
+### Register Server In Application
 
----
+```ts
+import {BaseApplication} from '@gennext/lb-infra';
+import {
+  GrpcServerComponent,
+  GrpcServerKeys,
+  IGrpcServerOptions,
+} from '@gennext/lb-infra/grpc';
+import {ServerCredentials} from '@grpc/grpc-js';
+import {join} from 'node:path';
 
-## 11. Biến môi trường
+import {UserGrpcController} from './controllers/user-grpc.controller';
 
-| Tên biến                        | Mô tả                            | Giá trị mặc định |
-| :------------------------------ | :------------------------------- | :--------------- |
-| `APP_ENV_APPLICATION_NAME`      | Tên ứng dụng xuất hiện trong log | `APP`            |
-| `APP_ENV_POSTGRES_HOST`         | Địa chỉ PostgreSQL               | `localhost`      |
-| `APP_ENV_POSTGRES_PORT`         | Cổng PostgreSQL                  | `5432`           |
-| `APP_ENV_POSTGRES_USERNAME`     | Username DB                      | `postgres`       |
-| `APP_ENV_POSTGRES_PASSWORD`     | Password DB                      | `password`       |
-| `APP_ENV_POSTGRES_DATABASE`     | Tên Database                     | `postgres`       |
-| `APP_ENV_REDIS_DATASOURCE_HOST` | Địa chỉ Redis                    | `0.0.0.0`        |
-| `APP_ENV_REDIS_DATASOURCE_PORT` | Cổng Redis                       | `6379`           |
-| `APP_ENV_LOGGER_FOLDER_PATH`    | Đường dẫn lưu file log           | `./app_data`     |
-| `DEBUG`                         | Kích hoạt log debug              | `false`          |
+export class MyApplication extends BaseApplication {
+  staticConfigure(): void {
+    this.bind<IGrpcServerOptions>(GrpcServerKeys.GRPC_OPTIONS).to({
+      identifier: 'my-grpc-server',
+      protoFolder: join(__dirname, 'protos'),
+      address: process.env.GRPC_ADDRESS ?? '0.0.0.0:50051',
+      credentials: ServerCredentials.createInsecure(),
+    });
 
----
+    this.grpcController(UserGrpcController);
+    this.component(GrpcServerComponent);
+  }
 
-## 12. Ví dụ end-to-end: Order Service
+  getProjectRoot(): string {
+    return __dirname;
+  }
 
-```typescript
-// --- 1. Model (order.schema.ts) ---
-export const orders = pgTable('orders', {
-  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-  item: text('item').notNull(),
-  ...generateTzColumnDefs(),
-});
+  validateEnv() {
+    return {result: true};
+  }
 
-// --- 2. Repository (order.repository.ts) ---
-export class OrderRepository extends DefaultCrudRepository<typeof orders> {
-  constructor() {
-    super(orders);
+  declareModels(): Set<string> {
+    return new Set([]);
   }
+
+  preConfigure(): void {}
+
+  postConfigure(): void {}
 }
+```
 
-// --- 3. Service (order.service.ts) ---
-export class OrderService extends BaseService {
-  async create(item: string) {
-    const repo = this.get<OrderRepository>('repositories.OrderRepository');
-    return repo.create({ item });
+`GrpcServerComponent` starts the gRPC server immediately when the component is registered, except when `RUN_MODE=migrate`. Register gRPC controllers before registering the component so the server can discover them.
+
+### Client Example
+
+```ts
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import {initializeGrpcClient} from '@gennext/lb-infra/grpc';
+import get from 'lodash/get';
+import {join} from 'node:path';
+
+type GetUserResponse = {
+  id: number;
+  email: string;
+  fullName: string;
+};
+
+type UserServiceClient = grpc.Client & {
+  GetUser(
+    request: {id: number},
+    callback: (error: grpc.ServiceError | null, response: GetUserResponse) => void,
+  ): void;
+};
+
+const protoPath = join(__dirname, 'protos/user.proto');
+const packageDefinition = protoLoader.loadSync(protoPath);
+const proto = grpc.loadPackageDefinition(packageDefinition);
+
+const UserService = get(proto, 'demo.UserService') as unknown as new (
+  address: string,
+  credentials: grpc.ChannelCredentials,
+  options?: grpc.ClientOptions,
+) => UserServiceClient;
+
+const userClient = initializeGrpcClient<UserServiceClient>({
+  serviceClass: UserService,
+  address: '127.0.0.1:50051',
+  credentials: grpc.ChannelCredentials.createInsecure(),
+  autoConnect: true,
+});
+
+userClient.client.GetUser({id: 1}, (error, response) => {
+  if (error) {
+    console.error(error);
+    return;
   }
-}
 
-// --- 4. Controller (order.controller.ts) ---
-@controller({ path: '/orders' })
-export class OrderController extends BaseController {
-  async binding() {
-    this.bindRoute({
-      path: '/',
-      method: 'post',
-      responses: { 200: { description: 'Success' } },
-    }).to({
-      handler: async c => {
-        const service = this.get<OrderService>('services.OrderService');
-        return c.json(await service.create('Product A'));
-      },
-    });
+  console.log(response);
+});
+```
+
+### Repository-Style Client
+
+For app code that prefers datasource/repository style, use `GrpcDataSource` and `GrpcRepository`:
+
+```ts
+import * as grpc from '@grpc/grpc-js';
+import {GrpcDataSource, GrpcRepository} from '@gennext/lb-infra/grpc';
+
+const dataSource = new GrpcDataSource<UserServiceClient>({
+  dsConfig: {
+    host: '127.0.0.1',
+    port: 50051,
+    credentials: grpc.ChannelCredentials.createInsecure(),
+    serviceClassResolver: () => UserService,
+  },
+});
+
+class UserGrpcRepository extends GrpcRepository<UserServiceClient> {
+  constructor() {
+    super({dataSource, scope: UserGrpcRepository.name});
   }
-}
 
-// --- 5. Application (main.ts) ---
-class OrderApp extends bootMixin(BaseApplication) {
-  getAppInfo() {
-    return { name: 'OrderAPI', version: '1.0' };
+  getUser(id: number): Promise<GetUserResponse> {
+    return new Promise((resolve, reject) => {
+      this.getServiceClient().GetUser({id}, (error, response) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve(response);
+      });
+    });
   }
 }
+```
+
+The current helper examples above use standard unary request/response calls.
+
+## Components
+
+Available components include:
+
+- `AuthenticateComponent`: JWT/basic/oauth2 strategies, auth middleware, token services and auth controller generator.
+- `AuthorizeComponent`: Casbin authorization, role/permission models, adapters, provider and interceptor.
+- `MigrationComponent`: migration model, repository and runtime wiring.
+- `HealthCheckComponent`: application and datasource health checks.
+- `StaticAssetComponent`: MinIO/static asset controllers.
+- `MailComponent`: mail service, template engine, transports and queue executors.
+- `SocketIOComponent`: Socket.IO server/client helpers and Redis adapter support.
+- `GrpcServerComponent`: gRPC server support.
+- `CrashReportComponent`: crash report providers and services.
 
-bootStrapApplication(OrderApp, { port: 8080 });
+## Helpers
+
+Important helper groups:
+
+- Logger: `LoggerFactory`, `ApplicationLogger`
+- Redis: `RedisHelper`, `RedisClusterHelper`
+- Queue: `QueueHelper`, `BullMQHelper`, `MQTTClientHelper`
+- Network: HTTP request, TCP, TLS TCP and UDP helpers
+- Crypto: `AES`, `RSA`
+- Storage: `MinioHelper`, `DIContainerHelper`
+- Worker thread helpers
+- Testing helpers
+- `CronHelper`
+
+## Datasources
+
+Built-in datasources:
+
+- `PostgresDataSource`
+- `RedisDataSource`
+- `KvMemDataSource`
+
+Common environment keys are defined in `src/common/environments.ts`, including server, PostgreSQL and datasource settings.
+
+## Development Checklist
+
+Before opening a change:
+
+```bash
+bun run --filter "@gennext/lb-infra" build
+bun run --filter "@gennext/lb-infra" lint
+bun run --filter "@gennext/lb-infra" test
 ```
 
----
+When adding or changing exports:
+
+1. Update `src/index.ts` or the relevant module `index.ts`.
+2. Update `package.json` `exports` when adding a new public subpath.
+3. Build the package.
+4. Verify the consumer app can import the new path.
+
+## Notes For Consumer Apps
 
-© 2024 Gennex Technology. Toàn quyền bảo lưu.
+- Prefer the package aliases `lb-core`, `lb-rest`, `lb-repo` and `lb-auth` to keep LoopBack dependency versions consistent.
+- Add `@api({basePath: ...})` on the final exported class when using generated controllers.
+- Bind required component options before starting the application, especially authentication token options and auth service bindings.
+- Ensure build output includes copied runtime assets when publishing or packaging.