@flusys/nestjs-iam 4.0.1 → 4.1.0

package/README.md

@@ -1,55 +1,84 @@
-# IAM Package Guide
+# @flusys/nestjs-iam
 
-> **Package:** `@flusys/nestjs-iam`
-> **Version:** 4.0.1
-> **Purpose:** Identity and Access Management with RBAC, ABAC, and permission logic
+> Identity and Access Management for NestJS — RBAC, DIRECT, and FULL permission modes with hierarchical actions, company scoping, intelligent 1-hour caching, and multi-tenant support.
+
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-iam.svg)](https://www.npmjs.com/package/@flusys/nestjs-iam)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
+
+---
 
 ## Table of Contents
 
 - [Overview](#overview)
+- [Features](#features)
+- [Permission Modes](#permission-modes)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
-- [Module Configuration](#module-configuration)
-- [Constants](#constants)
-- [Core Concepts](#core-concepts)
-- [Interfaces](#interfaces)
+- [Quick Start](#quick-start)
+- [Module Registration](#module-registration)
+  - [forRoot (Sync)](#forroot-sync)
+  - [forRootAsync (Factory)](#forrootasync-factory)
+- [Configuration Reference](#configuration-reference)
+- [Feature Toggles](#feature-toggles)
+- [API Endpoints](#api-endpoints)
 - [Entities](#entities)
-- [Permission Modes](#permission-modes)
-- [Permission Logic](#permission-logic)
-- [Services](#services)
-- [Helpers](#helpers)
-- [REST API Endpoints](#rest-api-endpoints)
-- [Multi-Tenant Support](#multi-tenant-support)
-- [Permission Guard Integration](#permission-guard-integration)
-- [Best Practices](#best-practices)
-- [DTOs Reference](#dtos-reference)
-- [API Reference](#api-reference)
-- [Package Architecture](#package-architecture)
+- [Permission Cache](#permission-cache)
+- [Exported Services](#exported-services)
+- [Using Permissions in Controllers](#using-permissions-in-controllers)
+- [Action Types](#action-types)
+- [Hierarchical Actions](#hierarchical-actions)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
 ## Overview
 
-`@flusys/nestjs-iam` provides a comprehensive Identity and Access Management system:
+`@flusys/nestjs-iam` is a complete Identity and Access Management system. It supports three permission modes — RBAC (role-based), DIRECT (user-to-action), and FULL (both simultaneously). Permissions are cached per user+company+branch for 1 hour and automatically invalidated on changes.
 
-- **Hierarchical Actions** - Organize permissions in tree structures
-- **Action Types** - BACKEND (cached for guards), FRONTEND (returned to UI), BOTH
-- **RBAC** - Role-Based Access Control with validation
-- **DIRECT** - Direct user-to-action assignments with validation
-- **Permission Mode Validation** - Throws `BadRequestException` when using wrong mode
-- **Company/Branch Scoping** - Multi-tenant permissions with three-level granularity
-- **Tenant-Aware Caching** - Automatic cache invalidation with multi-tenant support
+The module is fully independent from `nestjs-auth` — it only depends on `nestjs-core` and `nestjs-shared`. Integration with auth is done via the `USER_ENRICHER` provider interface in `nestjs-auth`.
 
-### Package Hierarchy
+---
 
-```
-@flusys/nestjs-core     <- Foundation
-     |
-@flusys/nestjs-shared   <- Shared utilities
-     |
-@flusys/nestjs-auth     <- User/Company management
-     |
-@flusys/nestjs-iam      <- Permission management (THIS PACKAGE)
-```
+## Features
+
+- **RBAC Mode** — Users inherit permissions through Roles → Actions assignments
+- **DIRECT Mode** — Users are assigned directly to Actions without roles
+- **FULL Mode** — Both RBAC and DIRECT active simultaneously (union of permissions)
+- **Hierarchical Actions** — Actions form parent-child trees with `parentId`; tree queries supported
+- **Action Types** — `BACKEND` (API guard only), `FRONTEND` (returned to client), `BOTH`
+- **Company Whitelist** — `COMPANY_ACTION` records control which actions are available per company
+- **Permission Logic** — Complex AND/OR nested logic on `@RequirePermission()` decorator
+- **1-Hour Cache** — Permissions cached per `userId + companyId + branchId`, auto-invalidated
+- **Menu Management** — Navigation menu items with per-item action requirements
+- **Multi-tenant** — Isolated DataSource Provider per request
+
+---
+
+## Permission Modes
+
+| Mode | How it works | Controllers loaded |
+|------|--------------|--------------------|
+| `RBAC` | User → Role → Action | ActionController, RoleController, RolePermissionController, MyPermissionController |
+| `DIRECT` | User → Action (direct) | ActionController, UserActionPermissionController, MyPermissionController |
+| `FULL` | RBAC + DIRECT (union) | All above controllers |
+
+`FULL` is the default when `permissionMode` is not specified.
+
+---
+
+## Compatibility
+
+| Package | Version |
+|---------|---------|
+| `@flusys/nestjs-core` | `^4.0.0` |
+| `@flusys/nestjs-shared` | `^4.0.0` |
+| `@nestjs/core` | `^11.0.0` |
+| `typeorm` | `^0.3.0` |
+| Node.js | `>= 18.x` |
 
 ---
 
@@ -61,32 +90,33 @@ npm install @flusys/nestjs-iam @flusys/nestjs-shared @flusys/nestjs-core
 
 ---
 
-## Module Configuration
+## Quick Start
 
-### With Auth Module (Recommended)
+### RBAC Mode
 
 ```typescript
-import { AuthModule } from '@flusys/nestjs-auth';
+import { Module } from '@nestjs/common';
 import { IAMModule } from '@flusys/nestjs-iam';
 
 @Module({
   imports: [
-    AuthModule.forRoot({
-      includeIAM: true, // Required for single-tenant mode
-      bootstrapAppConfig: {
-        databaseMode: 'single',
-        enableCompanyFeature: true,
-      },
-      config: { /* auth config */ },
-    }),
-
     IAMModule.forRoot({
       global: true,
       includeController: true,
       bootstrapAppConfig: {
         databaseMode: 'single',
-        enableCompanyFeature: true,
-        permissionMode: 'FULL', // 'FULL' | 'RBAC' | 'DIRECT'
+        enableCompanyFeature: false,
+        permissionMode: 'RBAC',
+      },
+      config: {
+        defaultDatabaseConfig: {
+          type: 'postgres',
+          host: process.env.DB_HOST,
+          port: Number(process.env.DB_PORT ?? 5432),
+          username: process.env.DB_USER,
+          password: process.env.DB_PASSWORD,
+          database: process.env.DB_NAME,
+        },
       },
     }),
   ],
@@ -94,1083 +124,367 @@ import { IAMModule } from '@flusys/nestjs-iam';
 export class AppModule {}
 ```
 
-### Async Configuration
+### FULL Mode with Company Feature
 
 ```typescript
-IAMModule.forRootAsync({
+IAMModule.forRoot({
   global: true,
   includeController: true,
   bootstrapAppConfig: {
     databaseMode: 'single',
-    enableCompanyFeature: true,
-    permissionMode: 'RBAC',
+    enableCompanyFeature: true,   // Company/branch scoping
+    permissionMode: 'FULL',       // RBAC + DIRECT
   },
-  imports: [ConfigModule],
-  useFactory: (config: ConfigService) => ({
-    // IAM-specific options from config
-  }),
-  inject: [ConfigService],
+  config: { defaultDatabaseConfig: { /* ... */ } },
 })
 ```
 
 ---
 
-## Constants
-
-```typescript
-// Injection Token
-export const IAM_MODULE_OPTIONS = 'IAM_MODULE_OPTIONS';
-```
-
----
-
-## Core Concepts
-
-### Actions
-
-Actions represent permissions in the system:
-
-| Field | Description |
-|-------|-------------|
-| `name` | Human-readable name |
-| `code` | Unique identifier (e.g., `user.create`) |
-| `actionType` | Category: `backend`, `frontend`, or `both` |
-| `metadata` | Additional data (icon, routerLink for frontend) |
-| `parentId` | Parent action for hierarchy |
-| `serial` | Display order |
+## Module Registration
 
-### Action Types
+### forRoot (Sync)
 
 ```typescript
-enum ActionType {
-  BACKEND = 'backend',   // API endpoint permissions (cached for PermissionGuard)
-  FRONTEND = 'frontend', // UI features (returned in my-permissions API)
-  BOTH = 'both',         // Both backend and frontend
-}
-```
-
-### Roles
-
-Roles are collections of actions:
-
-| Field | Description |
-|-------|-------------|
-| `name` | Human-readable name |
-| `description` | Role description |
-| `companyId` | Company scope (when company feature enabled) |
-| `isActive` | Active status |
-
-### Permission Types
-
-```typescript
-enum IamPermissionType {
-  USER_ROLE = 'user_role',       // User assigned to role
-  ROLE_ACTION = 'role_action',   // Role has action
-  USER_ACTION = 'user_action',   // User has action directly
-  COMPANY_ACTION = 'company_action', // Company action whitelist
-}
+IAMModule.forRoot({
+  global?: boolean;           // Default: false
+  includeController?: boolean; // Default: false
+  bootstrapAppConfig?: {
+    databaseMode: 'single' | 'multi-tenant';
+    enableCompanyFeature: boolean;
+    permissionMode?: 'FULL' | 'RBAC' | 'DIRECT'; // Default: 'FULL'
+  };
+  config?: IIAMModuleConfig;
+})
 ```
 
-### Entity Types
-
-Used for source/target type fields in permissions:
+### forRootAsync (Factory)
 
 ```typescript
-enum IamEntityType {
-  USER = 'user',
-  ROLE = 'role',
-  ACTION = 'action',
-  COMPANY = 'company',
-}
-```
-
-### Permission Resolution Order
-
-1. **Company-Action Whitelist** - Filter by company (if enabled)
-2. **UserAction (DENY)** - Explicit denials take precedence
-3. **UserAction (GRANT)** - Explicit grants
-4. **UserRole -> RoleAction** - Inherited from roles
-5. **Action Permission Logic** - Complex AND/OR rules
-
-### Permission Cascade Deletion
+import { ConfigService } from '@nestjs/config';
 
-When removing company actions via `removeCompanyActionsWithCascade()`, the `PermissionService` performs cascade deletion:
-
-```
-Company Action Removed
-        ↓
-1. Delete COMPANY_ACTION permissions
-        ↓
-2. Find all roles in the company
-        ↓
-3. Delete ROLE_ACTION permissions for those actions
-        ↓
-4. Find all users in the company
-        ↓
-5. Delete USER_ACTION permissions for those actions
-        ↓
-6. Invalidate permission cache for affected users
+IAMModule.forRootAsync({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+    permissionMode: 'FULL',
+  },
+  imports: [ConfigModule],
+  useFactory: async (configService: ConfigService) => ({
+    defaultDatabaseConfig: {
+      type: 'postgres',
+      host: configService.get('DB_HOST'),
+      port: configService.get<number>('DB_PORT'),
+      username: configService.get('DB_USER'),
+      password: configService.get('DB_PASSWORD'),
+      database: configService.get('DB_NAME'),
+    },
+  }),
+  inject: [ConfigService],
+})
 ```
 
 ---
 
-## Interfaces
-
-### IAction
+## Configuration Reference
 
 ```typescript
-interface IAction {
-  id: string;
-  readOnly: boolean;
-  name: string;
-  description: string | null;
-  code: string | null;
-  actionType: ActionType;
-  permissionLogic: LogicNode | null;
-  serial: number | null;
-  isActive: boolean;
-  parentId: string | null;
-  metadata: Record<string, any> | null;
-  createdAt: Date;
-  updatedAt: Date;
-  deletedAt: Date | null;
-  createdById: string | null;
-  updatedById: string | null;
-  deletedById: string | null;
-}
-```
-
-### IActionTree
-
-```typescript
-interface IActionTree extends IAction {
-  children?: IActionTree[];
-}
-```
-
-### IRole
-
-```typescript
-interface IRole {
-  id: string;
-  readOnly: boolean;
-  name: string;
-  description: string | null;
-  isActive: boolean;
-  serial: number | null;
-  companyId: string | null;
-  metadata: Record<string, any> | null;
-  createdAt: Date;
-  updatedAt: Date;
-  deletedAt: Date | null;
-  createdById: string | null;
-  updatedById: string | null;
-  deletedById: string | null;
+interface IIAMModuleConfig extends IDataSourceServiceOptions {
+  // All IAM behaviour is controlled via bootstrapAppConfig.
+  // IDataSourceServiceOptions provides:
+  //   defaultDatabaseConfig?: IDatabaseConfig
+  //   tenantDefaultDatabaseConfig?: IDatabaseConfig
+  //   tenants?: ITenantDatabaseConfig[]
 }
 ```
 
-### Module Options
+Bootstrap configuration is fixed at startup and cannot change at runtime:
 
 ```typescript
-// Runtime configuration (currently empty - reserved for future use)
-interface IIAMModuleConfig extends IDataSourceServiceOptions {
-  // Future: cache TTL, etc.
-}
-
-// Full module options
-interface IAMModuleOptions extends IDynamicModuleConfig {
-  bootstrapAppConfig?: IBootstrapAppConfig;
-  config?: IIAMModuleConfig;
-}
-
-// Async options
-interface IAMModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'>, IDynamicModuleConfig {
-  bootstrapAppConfig?: IBootstrapAppConfig;
-  config?: IIAMModuleConfig;
-  useFactory?: (...args: any[]) => Promise<IIAMModuleConfig> | IIAMModuleConfig;
-  inject?: any[];
-  useClass?: Type<IAMOptionsFactory>;
-  useExisting?: Type<IAMOptionsFactory>;
+interface IBootstrapAppConfig {
+  databaseMode: 'single' | 'multi-tenant';
+  enableCompanyFeature: boolean;
+  permissionMode?: 'FULL' | 'RBAC' | 'DIRECT'; // Default: 'FULL'
 }
 ```
 
 ---
 
-## Entities
+## Feature Toggles
 
-### Entity Groups
+| Feature | Config | Default | Effect |
+|---------|--------|---------|--------|
+| Company scoping | `enableCompanyFeature: true` | `false` | Uses `*WithCompany` entity variants; adds `companyId`/`branchId` to permission assignments; registers `CompanyActionPermissionController` |
+| RBAC | `permissionMode: 'RBAC'` | — | Loads Role, RoleAction, UserRole entities; registers Role controllers |
+| DIRECT | `permissionMode: 'DIRECT'` | — | Loads UserAction entities; registers UserActionPermissionController |
+| FULL | `permissionMode: 'FULL'` | default | All entities and controllers |
 
-```typescript
-// Core entities (no company feature)
-export const IAMCoreEntities = [Action, Role, UserIamPermission];
-
-// Company-specific entities
-export const IAMCompanyEntities = [RoleWithCompany, UserIamPermissionWithCompany];
-
-// All entities
-export const IAMAllEntities = [
-  Action,
-  Role,
-  RoleWithCompany,
-  UserIamPermission,
-  UserIamPermissionWithCompany,
-];
-
-// Helper function
-export function getIAMEntitiesByConfig(
-  enableCompanyFeature: boolean,
-  permissionMode: 'FULL' | 'RBAC' | 'DIRECT' = 'FULL',
-): any[] {
-  const entities: any[] = [Action];
-
-  // Permission entity - always included
-  if (enableCompanyFeature) {
-    entities.push(UserIamPermissionWithCompany);
-  } else {
-    entities.push(UserIamPermission);
-  }
+**Controller loading by mode:**
 
-  // Role entity - Only for RBAC or FULL mode (not DIRECT)
-  if (permissionMode === 'RBAC' || permissionMode === 'FULL') {
-    if (enableCompanyFeature) {
-      entities.push(RoleWithCompany);
-    } else {
-      entities.push(Role);
-    }
-  }
+| Mode | + `enableCompanyFeature` | Additional controller |
+|------|--------------------------|-----------------------|
+| `RBAC` | true | `CompanyActionPermissionController` |
+| `DIRECT` | true | `CompanyActionPermissionController` |
+| `FULL` | true | `CompanyActionPermissionController` |
 
-  return entities;
-}
-```
-
-### ActionBase
-
-Core action fields in `action-base.entity.ts`:
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `readOnly` | boolean | System-protected action |
-| `name` | varchar(255) | Action name |
-| `code` | varchar(255) | Unique code |
-| `description` | varchar(500) | Description |
-| `actionType` | enum | BACKEND, FRONTEND, BOTH |
-| `permissionLogic` | json | AND/OR rules |
-| `parentId` | uuid | Parent action ID |
-| `serial` | int | Display order |
-| `isActive` | boolean | Active status |
-| `metadata` | json | Additional data |
+---
 
-### RoleBase
+## API Endpoints
 
-Core role fields in `role-base.entity.ts`:
+All endpoints use **POST** and require JWT authentication.
 
-| Column | Type | Description |
-|--------|------|-------------|
-| `readOnly` | boolean | System-protected role |
-| `name` | varchar(255) | Role name |
-| `description` | varchar(500) | Description |
-| `isActive` | boolean | Active status |
-| `serial` | int | Display order |
-| `metadata` | json | Additional data |
+### Actions — `POST /iam/action/*`
 
-### RoleWithCompany
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /iam/action/insert` | `action.create` | Create an action |
+| `POST /iam/action/get-all` | `action.read` | List all actions |
+| `POST /iam/action/get/:id` | `action.read` | Get action by ID |
+| `POST /iam/action/get-tree` | `action.read` | Get hierarchical action tree |
+| `POST /iam/action/update` | `action.update` | Update action |
+| `POST /iam/action/delete` | `action.delete` | Delete action |
 
-Extends RoleBase with:
-- `companyId` (uuid) - Company scope
+### Roles — `POST /iam/role/*` *(RBAC and FULL modes)*
 
-### PermissionBase
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /iam/role/insert` | `role.create` | Create a role |
+| `POST /iam/role/get-all` | `role.read` | List all roles |
+| `POST /iam/role/get/:id` | `role.read` | Get role by ID |
+| `POST /iam/role/update` | `role.update` | Update role |
+| `POST /iam/role/delete` | `role.delete` | Delete role |
 
-Core permission fields in `permission-base.entity.ts`:
+### Role Permissions — `POST /iam/role-permission/*` *(RBAC and FULL modes)*
 
-| Column | Type | Description |
-|--------|------|-------------|
-| `permissionType` | enum | USER_ROLE, ROLE_ACTION, etc. |
-| `sourceType` | enum | USER, ROLE, COMPANY |
-| `sourceId` | uuid | Source entity ID |
-| `targetType` | enum | ROLE, ACTION |
-| `targetId` | uuid | Target entity ID |
-| `userId` | uuid | User ID (nullable) |
-| `validFrom` | timestamp | Permission valid from |
-| `validUntil` | timestamp | Permission valid until |
-| `reason` | text | Reason for permission |
-| `metadata` | json | Additional data |
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /iam/role-permission/assign` | `role.update` | Assign action to role |
+| `POST /iam/role-permission/remove` | `role.update` | Remove action from role |
+| `POST /iam/role-permission/get-by-role` | `role.read` | Get all actions for a role |
+| `POST /iam/role-permission/assign-user-role` | `role.update` | Assign role to user |
+| `POST /iam/role-permission/remove-user-role` | `role.update` | Remove role from user |
 
-**Methods:**
+### User Action Permissions — `POST /iam/user-action-permission/*` *(DIRECT and FULL modes)*
 
-```typescript
-// Check if permission is currently valid (date constraints)
-isValid(now: Date = new Date()): boolean {
-  if (this.validFrom && now < this.validFrom) return false;
-  if (this.validUntil && now > this.validUntil) return false;
-  return true;
-}
-```
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /iam/user-action-permission/assign` | `action.update` | Directly assign action to user |
+| `POST /iam/user-action-permission/remove` | `action.update` | Remove direct action from user |
+| `POST /iam/user-action-permission/get-by-user` | `action.read` | Get all direct permissions for user |
 
-### UserIamPermissionWithCompany
+### Company Action Whitelist — `POST /iam/company-action/*` *(`enableCompanyFeature: true`)*
 
-Extends PermissionBase with:
-- `companyId` (uuid) - Company scope
-- `branchId` (uuid) - Branch scope
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /iam/company-action/assign` | `action.update` | Add action to company whitelist |
+| `POST /iam/company-action/remove` | `action.update` | Remove action from whitelist |
+| `POST /iam/company-action/get-by-company` | `action.read` | Get company's available actions |
 
-**Permission Granularity:**
+### My Permissions — `POST /iam/my-permission/*`
 
-| Level | companyId | branchId | Use Case |
-|-------|-----------|----------|----------|
-| Global | null | null | Super admin across all companies |
-| Company-wide | set | null | Manager for ALL branches in company |
-| Branch-specific | set | set | Manager for specific branch only |
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| `POST /iam/my-permission/get-all` | JWT | Get all permissions for current user |
 
 ---
 
-## Permission Modes
-
-Set in `bootstrapAppConfig.permissionMode`:
-
-### Permission Mode Enum
-
-```typescript
-enum IAMPermissionMode {
-  RBAC = 1,   // Role-Based: Action + RoleAction + UserRole
-  DIRECT = 2, // Direct User Permissions: Action + UserAction
-  FULL = 3,   // Both RBAC + Direct permissions
-}
-```
-
-### RBAC Mode (Role-Based)
-
-```
-User -> Role -> Action
-```
-
-Only role-based permissions. Users get permissions through assigned roles.
-
-**Note:** Calling `assignUserActions()` in RBAC mode throws `BadRequestException`.
+## Entities
 
-### DIRECT Mode (Action-Based)
+### Core Entities (always registered)
 
-```
-User -> Action
-```
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `Action` | `iam_action` | Permission actions (e.g., `product.create`) with type and hierarchy |
+| `Menu` | `iam_menu` | Navigation menu items with optional action requirement |
 
-Only direct permissions. Users get actions assigned directly.
+### RBAC Entities (`permissionMode: 'RBAC'` or `'FULL'`)
 
-**Note:** Calling `assignUserRoles()` or `assignRoleActions()` in DIRECT mode throws `BadRequestException`.
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `Role` | `iam_role` | Role definitions |
+| `RoleAction` | `iam_role_action` | Role → Action assignments |
+| `UserRole` | `iam_user_role` | User → Role assignments |
 
-### FULL Mode (Combined)
+### DIRECT Entities (`permissionMode: 'DIRECT'` or `'FULL'`)
 
-```
-User -> Role -> Action
-User -> Action
-```
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `UserAction` | `iam_user_action` | Direct User → Action assignments |
 
-Both RBAC and direct permissions. Default mode. All assignment methods available.
+### Company Feature Entities (`enableCompanyFeature: true`)
 
----
+All above entities get `WithCompany` variants with `companyId` and `branchId` columns, plus:
 
-## Permission Logic
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `CompanyAction` | `iam_company_action` | Actions whitelisted per company |
 
-Complex permission rules using AND/OR operators stored in `permissionLogic` field:
+#### Register Entities in TypeORM
 
 ```typescript
-interface LogicNode {
-  id: string;
-  type: 'group' | 'action';
-  operator?: 'AND' | 'OR';
-  children?: LogicNode[];
-  actionId?: string;
-}
-```
-
-**Example:** User must have "employee" AND ("department-head" OR "hr-clearance")
+import { IAMModule } from '@flusys/nestjs-iam';
 
-```typescript
-const logic: LogicNode = {
-  id: 'root',
-  type: 'group',
-  operator: 'AND',
-  children: [
-    { id: '1', type: 'action', actionId: 'employee-action-id' },
-    {
-      id: '2',
-      type: 'group',
-      operator: 'OR',
-      children: [
-        { id: '2-1', type: 'action', actionId: 'department-head' },
-        { id: '2-2', type: 'action', actionId: 'hr-clearance' },
-      ],
-    },
+TypeOrmModule.forRoot({
+  entities: [
+    ...IAMModule.getEntities({
+      enableCompanyFeature: true,
+      permissionMode: 'FULL',
+    }),
   ],
-};
+})
 ```
 
 ---
 
-## Services
-
-| Service | Scope | Description |
-|---------|-------|-------------|
-| `ActionService` | REQUEST | Action CRUD, tree queries |
-| `RoleService` | REQUEST | Role CRUD (RBAC/FULL mode only) |
-| `PermissionService` | REQUEST | Permission assignments, my-permissions |
-| `PermissionCacheService` | SINGLETON | Cache management |
-| `IAMConfigService` | SINGLETON | IAM configuration access |
-| `IAMDataSourceService` | REQUEST | DataSource provider for multi-tenant |
-
-### IAMConfigService
+## Permission Cache
 
-```typescript
-import { IAMConfigService } from '@flusys/nestjs-iam';
-
-// Database mode
-const dbMode = config.getDatabaseMode(); // 'single' | 'multi-tenant'
-const isMultiTenant = config.isMultiTenant();
+Permissions are cached with the key `iam:permissions:{userId}:{companyId}:{branchId}` for **1 hour**. The cache is automatically invalidated when:
 
-// Feature flags
-const hasCompany = config.isCompanyFeatureEnabled();
+- A role is assigned to or removed from a user
+- An action is directly assigned to or removed from a user
+- A role's action set is modified
+- The company action whitelist changes
 
-// Permission mode
-const mode = config.getPermissionMode(); // IAMPermissionMode enum
-const isRbac = config.isRbacEnabled(); // true for RBAC or FULL
-const isDirect = config.isDirectPermissionEnabled(); // true for DIRECT or FULL
-
-// Get raw options
-const options = config.getOptions();
-```
+Cache uses `HybridCache` (in-memory + Redis). If Redis is not configured, in-memory cache is used.
 
-### IAMDataSourceService
-
-```typescript
-import { IAMDataSourceService } from '@flusys/nestjs-iam';
-
-// Get repository for entity
-const actionRepo = await dataSourceProvider.getRepository(Action);
-
-// Tenant-specific features
-const enableCompany = dataSourceProvider.getEnableCompanyFeatureForCurrentTenant();
-const entities = await dataSourceProvider.getIAMEntities();
-```
-
-### ActionService
-
-```typescript
-import { ActionService } from '@flusys/nestjs-iam';
-
-// Create action
-await actionService.insert({
-  name: 'View Users',
-  code: 'user.view',
-  actionType: ActionType.BACKEND,
-  parentId: parentAction.id,
-});
+---
 
-// Get hierarchical tree
-const tree = await actionService.getActionTree(user, 'search', true, false);
+## Exported Services
 
-// Get actions for permission (company-filtered)
-const actions = await actionService.getActionsForPermission(user);
-```
+| Service | Description |
+|---------|-------------|
+| `PermissionService` | Resolve and check permissions for a user |
+| `ActionService` | Action CRUD and tree queries |
+| `RoleService` | Role CRUD *(RBAC/FULL modes)* |
+| `UserActionPermissionService` | Direct user-action assignment *(DIRECT/FULL modes)* |
+| `IAMConfigService` | Exposes runtime config and feature flags |
+| `IAMDataSourceProvider` | Dynamic DataSource resolution per request |
 
-### RoleService
+---
 
-```typescript
-import { RoleService } from '@flusys/nestjs-iam';
-
-// Create role
-await roleService.insert({
-  name: 'Administrator',
-  description: 'Full system access',
-  companyId: 'company-id',
-});
-```
+## Using Permissions in Controllers
 
-### PermissionService
+### Using the Decorator
 
 ```typescript
-import { PermissionService, PermissionAction } from '@flusys/nestjs-iam';
-
-// Assign roles to user (RBAC/FULL mode only)
-await permissionService.assignUserRoles({
-  userId: 'user-id',
-  companyId: 'company-id',
-  branchId: null, // null = company-wide
-  items: [{ id: 'role-id', action: PermissionAction.ADD }],
-});
-
-// Assign actions directly (DIRECT/FULL mode only)
-await permissionService.assignUserActions({
-  userId: 'user-id',
-  companyId: 'company-id',
-  branchId: 'branch-id',
-  items: [{ id: 'action-id', action: PermissionAction.ADD }],
-});
-
-// Assign actions to role (RBAC/FULL mode only)
-await permissionService.assignRoleActions({
-  roleId: 'role-id',
-  items: [{ id: 'action-id', action: PermissionAction.ADD }],
-});
-
-// Get user's permissions
-const permissions = await permissionService.getMyPermissions(
-  userId, branchId, companyId, parentCodes
-);
-```
-
-### PermissionCacheService
-
-Centralized cache management for IAM permissions. Cache key format matches PermissionGuard in nestjs-shared.
+import { RequirePermission } from '@flusys/nestjs-shared/decorators';
+import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
 
-**Cache TTLs:**
-- Permissions: 1 hour (3600000ms)
-- Action codes: 2 hours (7200000ms)
-
-**Interfaces:**
-
-```typescript
-interface PermissionCacheKeyOptions {
-  userId: string;
-  companyId?: string | null;
-  branchId?: string | null;
-  enableCompanyFeature: boolean;
-}
+@UseGuards(JwtAuthGuard)
+@Controller('products')
+export class ProductController {
+  @Post('insert')
+  @RequirePermission('product.create')
+  async create() { }
 
-interface CachedMyPermissions {
-  frontendActions: Array<{
-    id: string;
-    code: string;
-    name: string;
-    description: string | null;
-    parentId: string | null;
-  }>;
-  backendCodes: string[];
+  @Post('get-all')
+  @RequirePermission('product.read')
+  async getAll() { }
 }
 ```
 
-**Usage:**
-
-```typescript
-import { PermissionCacheService } from '@flusys/nestjs-iam';
-
-// Set permissions (backend codes for PermissionGuard)
-await cacheService.setPermissions(
-  { userId, companyId, branchId, enableCompanyFeature: true },
-  ['users.read', 'users.write']
-);
-
-// Set my-permissions (full response with frontend actions)
-await cacheService.setMyPermissions(cacheOptions, {
-  frontendActions: [...],
-  backendCodes: ['users.read', 'users.write'],
-});
-
-// Get cached my-permissions
-const cached = await cacheService.getMyPermissions(cacheOptions);
-
-// Invalidate single user cache
-await cacheService.invalidateUser('user-id', 'company-id', ['branch-id']);
-
-// Invalidate multiple users cache
-await cacheService.invalidateUsers(userIds, 'company-id', branchIds);
-
-// Invalidate role members (all users assigned to role)
-await cacheService.invalidateRole('role-id', userIds, 'company-id', branchIds);
-
-// Tenant-aware action code cache
-await cacheService.setActionCodeMap(codeToIdMap, tenantId);
-await cacheService.getActionIdsByCodes(['user.view'], tenantId);
-```
-
-**Cache Key Formats:**
-```
-permissions:user:{userId}                                        // Without company
-permissions:company:{companyId}:branch:{branchId}:user:{userId}  // With company
-my-permissions:user:{userId}                                     // My-permissions (no company)
-my-permissions:company:{companyId}:branch:{branchId}:user:{userId}  // My-permissions (with company)
-action-codes:map                                                 // Single tenant
-action-codes:tenant:{tenantId}:map                               // Multi-tenant
-```
-
----
-
-## Helpers
-
-### PermissionModeHelper
-
-Centralizes conversion from string to enum to prevent duplication:
+### Checking Permissions Programmatically
 
 ```typescript
-import { PermissionModeHelper } from '@flusys/nestjs-iam';
-
-// Convert string to enum
-const mode = PermissionModeHelper.fromString('RBAC');
-// Returns: IAMPermissionMode.RBAC
+import { PermissionService } from '@flusys/nestjs-iam';
 
-const mode = PermissionModeHelper.fromString(undefined);
-// Returns: IAMPermissionMode.FULL (default)
+@Injectable()
+export class ProductService {
+  constructor(
+    @Inject(PermissionService) private readonly permissionService: PermissionService,
+  ) {}
 
-// Convert enum to string
-const str = PermissionModeHelper.toString(IAMPermissionMode.RBAC);
-// Returns: 'RBAC'
-```
-
-**Used by:**
-- `iam.module.ts` (forRoot, forRootAsync)
-- `iam-config.service.ts` (getPermissionMode)
-- `main.ts` (Swagger setup)
-
-### validateCompanyAccess
-
-Validates user access to a company for permission operations:
+  async canUserCreate(userId: string, companyId?: string): Promise<boolean> {
+    return this.permissionService.hasPermission(userId, 'product.create', companyId);
+  }
 
-```typescript
-import { validateCompanyAccess } from '@flusys/nestjs-iam';
-
-// In a controller or service
-validateCompanyAccess(
-  iamConfig,
-  dto.companyId,
-  user,
-  'You do not have access to this company',
-);
-// Throws ForbiddenException if user.companyId !== dto.companyId
+  async getUserPermissions(userId: string, companyId?: string): Promise<string[]> {
+    return this.permissionService.getPermissions(userId, companyId);
+  }
+}
 ```
 
 ---
 
-## REST API Endpoints
-
-### Actions API
-
-| Endpoint | Method | Permission | Description |
-|----------|--------|------------|-------------|
-| `/iam/actions/insert` | POST | `action.create` | Create action |
-| `/iam/actions/insert-many` | POST | `action.create` | Create multiple actions |
-| `/iam/actions/get-all` | POST | `action.read` | List actions (paginated) |
-| `/iam/actions/get` | POST | `action.read` | Get action by ID |
-| `/iam/actions/tree` | POST | JWT Auth | Get hierarchical tree (ALL actions) |
-| `/iam/actions/tree-for-permission` | POST | JWT Auth | Get company-filtered actions |
-| `/iam/actions/update` | POST | `action.update` | Update action |
-| `/iam/actions/update-many` | POST | `action.update` | Update multiple actions |
-| `/iam/actions/delete` | POST | `action.delete` | Delete action |
-
-### Roles API (RBAC/FULL mode only)
-
-| Endpoint | Method | Permission | Description |
-|----------|--------|------------|-------------|
-| `/iam/roles/insert` | POST | `role.create` | Create role |
-| `/iam/roles/insert-many` | POST | `role.create` | Create multiple roles |
-| `/iam/roles/get-all` | POST | `role.read` | List roles (paginated, auto-filtered by company) |
-| `/iam/roles/get` | POST | `role.read` | Get role by ID |
-| `/iam/roles/update` | POST | `role.update` | Update role |
-| `/iam/roles/update-many` | POST | `role.update` | Update multiple roles |
-| `/iam/roles/delete` | POST | `role.delete` | Delete role |
-
-### Permissions API
-
-| Endpoint | Method | Permission | Modes | Description |
-|----------|--------|------------|-------|-------------|
-| `/iam/permissions/role-actions/assign` | POST | `role-action.assign` | RBAC, FULL | Assign actions to role |
-| `/iam/permissions/get-role-actions` | POST | `role-action.read` | RBAC, FULL | Get role actions |
-| `/iam/permissions/user-roles/assign` | POST | `user-role.assign` | RBAC, FULL | Assign roles to user |
-| `/iam/permissions/get-user-roles` | POST | `user-role.read` | RBAC, FULL | Get user roles |
-| `/iam/permissions/user-actions/assign` | POST | `user-action.assign` | DIRECT, FULL | Assign actions to user |
-| `/iam/permissions/get-user-actions` | POST | `user-action.read` | DIRECT, FULL | Get user actions |
-| `/iam/permissions/company-actions/assign` | POST | `company-action.assign` | Company enabled | Company action whitelist |
-| `/iam/permissions/get-company-actions` | POST | `company-action.read` | Company enabled | Get company actions |
-| `/iam/permissions/my-permissions` | POST | JWT Auth | All | Get current user's permissions |
-
-### Permission Constants
-
-These permission codes are defined in `@flusys/nestjs-shared`:
+## Action Types
 
-```typescript
-// Actions
-ACTION_PERMISSIONS = { CREATE: 'action.create', READ: 'action.read', UPDATE: 'action.update', DELETE: 'action.delete' }
-
-// Roles
-ROLE_PERMISSIONS = { CREATE: 'role.create', READ: 'role.read', UPDATE: 'role.update', DELETE: 'role.delete' }
-
-// Role-Action assignments
-ROLE_ACTION_PERMISSIONS = { ASSIGN: 'role-action.assign', READ: 'role-action.read' }
-
-// User-Role assignments
-USER_ROLE_PERMISSIONS = { ASSIGN: 'user-role.assign', READ: 'user-role.read' }
-
-// User-Action assignments (direct)
-USER_ACTION_PERMISSIONS = { ASSIGN: 'user-action.assign', READ: 'user-action.read' }
-
-// Company-Action assignments
-COMPANY_ACTION_PERMISSIONS = { ASSIGN: 'company-action.assign', READ: 'company-action.read' }
-```
-
-**Controller Registration by Mode:**
-
-| Mode | Controllers |
+| Type | Description |
 |------|-------------|
-| DIRECT | ActionController, MyPermissionController, UserActionPermissionController |
-| RBAC | ActionController, MyPermissionController, RoleController, RolePermissionController |
-| FULL | All controllers |
-| Company Enabled | + CompanyActionPermissionController |
-
----
-
-## Multi-Tenant Support
-
-### Company Feature Toggle
-
-```typescript
-// config/app.config.ts
-export const bootstrapAppConfig: IBootstrapAppConfig = {
-  databaseMode: 'single', // or 'multi-tenant'
-  enableCompanyFeature: true,
-  permissionMode: 'FULL',
-};
-```
-
-### When `enableCompanyFeature: true`
-
-- `companyId` and `branchId` fields available in DTOs
-- Company-Action Permissions controller registered
-- Three-level permission granularity (Global, Company-wide, Branch-specific)
-- Uses `UserIamPermissionWithCompany` and `RoleWithCompany` entities
-
-### When `enableCompanyFeature: false`
-
-- Company endpoints NOT available (404)
-- `companyId`/`branchId` fields visible in Swagger but ignored
-- All permissions are global
-- Uses `UserIamPermission` and `Role` entities
-
-### Multi-Tenant Database Mode
-
-When `databaseMode: 'multi-tenant'`:
-- Each tenant has isolated database/schema
-- Action code cache is tenant-aware (separate cache per tenant)
-- Uses `IAMDataSourceService` for tenant-specific connections
-
-### Permission Merging
-
-When `getMyPermissions` is called:
-
-**With branchId specified:**
-1. Company-wide roles (branchId=null) + Branch-specific roles for that branch
-2. Actions from all merged roles
-3. Company-wide user actions + Branch-specific user actions for that branch
-
-**Without branchId (null):**
-1. ALL roles for the user in the company (any branch)
-2. Actions from all roles
-3. ALL user actions for the company (any branch)
-
-**Result:** Complete permission set without duplicates, filtered by company whitelist.
-
----
-
-## Permission Guard Integration
-
-```typescript
-import { RequirePermission, RequireAnyPermission } from '@flusys/nestjs-shared/decorators';
-
-@Controller('users')
-export class UserController {
-  @RequirePermission('user.view')
-  @Post('get-all')
-  getUsers() {}
-
-  @RequireAnyPermission('user.create', 'admin')
-  @Post('insert')
-  createUser() {}
+| `BACKEND` | Enforced by `PermissionGuard` on API requests only. Not returned to the frontend. |
+| `FRONTEND` | Returned to the frontend in permission lists. Not enforced server-side. |
+| `BOTH` | Enforced server-side AND returned to the frontend. |
+
+```json
+POST /iam/action/insert
+{
+  "name": "Create Product",
+  "code": "product.create",
+  "type": "BOTH",
+  "parentId": null,
+  "description": "Allows creating new products"
 }
 ```
 
 ---
 
-## Best Practices
+## Hierarchical Actions
 
-### 1. Action Code Naming
+Actions support parent-child relationships. Use `parentId` to create a tree:
 
-```typescript
-// Hierarchical naming for backend
-'user.view', 'user.create', 'user.delete'
-
-// UPPERCASE for frontend actions
-'MENU_USERS', 'MENU_REPORTS', 'FEATURE_EXPORT'
 ```
-
-### 2. Company-wide vs Branch-specific
-
-```typescript
-// Company-wide for managers across ALL branches
-{ companyId: 'company-a', branchId: null }
-
-// Branch-specific for location-bound staff
-{ companyId: 'company-a', branchId: 'branch-x' }
+product           (BOTH - parent)
+├── product.read  (BOTH - child)
+├── product.create (BOTH - child)
+├── product.update (BOTH - child)
+└── product.delete (BOTH - child)
 ```
 
-### 3. Use Roles for Common Patterns
-
-```typescript
-// Create roles for common permission sets
-const roles = [
-  { name: 'Viewer', actions: ['*.view'] },
-  { name: 'Editor', actions: ['*.view', '*.create', '*.update'] },
-  { name: 'Admin', actions: ['*'] },
-];
+Get the full tree:
+```json
+POST /iam/action/get-tree
+{}
 ```
 
-### 4. Use Direct Actions Sparingly
-
-Direct actions should be exceptions and branch-specific overrides, not the primary permission mechanism.
+The wildcard `product.*` in `@RequirePermission('product.*')` matches any action whose code starts with `product.`.
 
 ---
 
-## DTOs Reference
-
-### Permission Operation DTOs
-
-```typescript
-// Permission action enum for add/remove operations
-enum PermissionAction {
-  ADD = 'add',
-  REMOVE = 'remove',
-}
+## Troubleshooting
 
-// Common item structure for permission assignments
-interface PermissionItemDto {
-  id: string;              // ID of target (action or role)
-  action: PermissionAction; // ADD or REMOVE
-}
-```
+**`PermissionGuard` always denies — user has correct role**
 
-### Assignment DTOs
+Check that the IAM entities are included in your `TypeOrmModule` registration. Missing entities cause the permission query to return empty results.
 
-```typescript
-// Assign actions directly to user
-interface AssignUserActionsDto {
-  userId: string;
-  companyId?: string;  // Company scope (when enabled)
-  branchId?: string;   // Branch scope (null = company-wide)
-  items: PermissionItemDto[];
-}
-
-// Assign roles to user
-interface AssignUserRolesDto {
-  userId: string;
-  companyId?: string;
-  branchId?: string;
-  items: PermissionItemDto[];
-}
-
-// Assign actions to role
-interface AssignRoleActionsDto {
-  roleId: string;
-  items: PermissionItemDto[];
-}
-
-// Assign actions to company (whitelist)
-interface AssignCompanyActionsDto {
-  companyId: string;
-  items: PermissionItemDto[];
-}
-```
-
-### Query DTOs
-
-```typescript
-// Query user's permissions (my-permissions)
-interface MyPermissionsQueryDto {
-  parentCodes?: string[]; // Filter by parent action codes
-}
-
-// Query action tree
-interface ActionTreeQueryDto {
-  search?: string;      // Filter by name or code
-  isActive?: boolean;   // Filter by active status
-  withDeleted?: boolean; // Include deleted actions
-}
-```
-
-### Response DTOs
-
-```typescript
-// My-permissions response
-interface MyPermissionsResponseDto {
-  frontendActions: FrontendActionDto[];
-  cachedEndpoints: number; // Count of backend codes cached
-}
+---
 
-interface FrontendActionDto {
-  id: string;
-  code: string;
-  name: string;
-  description: string | null;
-}
+**Permission cache not invalidating after role change**
 
-// Permission operation result
-interface PermissionOperationResultDto {
-  success: boolean;
-  added: number;
-  removed: number;
-  message: string;
-}
-```
+Check that `REDIS_URL` is configured correctly. If multiple service instances share the same Redis, cache invalidation propagates automatically. In single-instance in-memory mode, invalidation only affects the current process.
 
 ---
 
-## API Reference
-
-### Exports
+**`No metadata for entity` on startup**
 
-```typescript
-// Config
-export { IAM_MODULE_OPTIONS } from './config';
-
-// Modules
-export { IAMModule } from './modules';
-
-// Entities
-export { Action } from './entities/action.entity';
-export { ActionBase } from './entities/action-base.entity';
-export { Role } from './entities/role.entity';
-export { RoleBase } from './entities/role-base.entity';
-export { RoleWithCompany } from './entities/role-with-company.entity';
-export { PermissionBase } from './entities/permission-base.entity';
-export { UserIamPermission } from './entities/user-iam-permission.entity';
-export { UserIamPermissionWithCompany } from './entities/permission-with-company.entity';
-export { IAMCoreEntities, IAMCompanyEntities, IAMAllEntities, getIAMEntitiesByConfig } from './entities';
-
-// Services
-export { ActionService } from './services/action.service';
-export { RoleService } from './services/role.service';
-export { PermissionService } from './services/permission.service';
-export { PermissionCacheService } from './services/permission-cache.service';
-export { IAMConfigService } from './services/iam-config.service';
-export { IAMDataSourceService } from './services/iam-datasource.service';
-
-// Helpers
-export { PermissionModeHelper } from './helpers/permission-mode.helper';
-export { validateCompanyAccess } from './helpers/company-access.helper';
-
-// Enums
-export { ActionType } from './enums/action-type.enum';
-export { IAMPermissionMode } from './enums/permission-type.enum';
-
-// Types
-export { LogicNode } from './types/logic-node.type';
-
-// DTOs
-export * from './dtos';
-// Key DTOs:
-// - CreateActionDto, UpdateActionDto, ActionResponseDto, ActionTreeDto, ActionTreeQueryDto
-// - CreateRoleDto, UpdateRoleDto, RoleResponseDto
-// - PermissionAction (enum: ADD, REMOVE), PermissionItemDto
-// - AssignUserActionsDto, AssignRoleActionsDto, AssignUserRolesDto, AssignCompanyActionsDto
-// - GetUserActionsDto, GetRoleActionsDto, GetUserRolesDto, GetCompanyActionsDto
-// - UserActionResponseDto, RoleActionResponseDto, UserRoleResponseDto, CompanyActionResponseDto
-// - MyPermissionsQueryDto, MyPermissionsResponseDto, FrontendActionDto
-// - PermissionOperationResultDto
-
-// Interfaces
-export * from './interfaces';
-// Key Interfaces:
-// - IAction, IActionTree (for action responses)
-// - IRole (for role responses)
-// - IIAMModuleConfig, IAMModuleOptions, IAMOptionsFactory, IAMModuleAsyncOptions
-
-// Swagger Config
-export { iamSwaggerConfig } from './docs';
-```
-
-### Swagger Configuration
+Use `IAMModule.getEntities()` with both `enableCompanyFeature` and `permissionMode` matching your `bootstrapAppConfig`:
 
 ```typescript
-import { iamSwaggerConfig } from '@flusys/nestjs-iam';
-
-// Generate swagger config based on features
-const swaggerOptions = iamSwaggerConfig(
-  enableCompanyFeature, // boolean
-  permissionMode,       // IAMPermissionMode
-);
-
-// Returns IModuleSwaggerOptions with:
-// - title, description, version, path, bearerAuth
-// - excludeSchemaProperties (hides companyId/branchId when company disabled)
-// - excludeTags (hides unused controllers based on mode)
-// - excludeQueryParameters (hides unused query params)
+...IAMModule.getEntities({ enableCompanyFeature: true, permissionMode: 'FULL' })
 ```
 
-The swagger config automatically:
-- Excludes Auth-related tags (Authentication, Users, Companies, etc.)
-- Hides Company Action endpoints when company feature is disabled
-- Hides RBAC endpoints (Roles, User-Roles) in DIRECT mode
-- Hides Direct endpoints (User-Actions) in RBAC mode
-- Shows appropriate documentation based on current configuration
+---
 
-### Module Static Methods
+**Company action whitelist blocks all permissions**
 
-```typescript
-// Configure module
-IAMModule.forRoot(options?: IAMModuleOptions): DynamicModule
-IAMModule.forRootAsync(options: IAMModuleAsyncOptions): DynamicModule
-IAMModule.forFeature(options?: IAMModuleOptions): DynamicModule
-```
+When `enableCompanyFeature: true`, a user's permissions are intersected with the company's action whitelist. If the whitelist is empty, the user has no permissions. Seed the whitelist using `POST /iam/company-action/assign`.
 
 ---
 
-## Package Architecture
+## License
 
-```
-nestjs-iam/src/
-├── config/
-│   ├── iam.constants.ts           # IAM_MODULE_OPTIONS token
-│   └── index.ts
-├── modules/
-│   └── iam.module.ts              # Main module with dynamic config
-├── entities/
-│   ├── action-base.entity.ts      # Action base fields
-│   ├── action.entity.ts           # Action entity
-│   ├── role-base.entity.ts        # Role base fields
-│   ├── role.entity.ts             # Role (no company)
-│   ├── role-with-company.entity.ts
-│   ├── permission-base.entity.ts  # Permission base fields
-│   ├── user-iam-permission.entity.ts
-│   ├── permission-with-company.entity.ts
-│   └── index.ts                   # Entity groups & getIAMEntitiesByConfig
-├── services/
-│   ├── action.service.ts          # Action CRUD
-│   ├── role.service.ts            # Role CRUD
-│   ├── permission.service.ts      # Permission management
-│   ├── permission-cache.service.ts # Cache management
-│   ├── iam-config.service.ts      # Configuration
-│   └── iam-datasource.service.ts  # DataSource provider
-├── controllers/
-│   ├── action.controller.ts
-│   ├── role.controller.ts
-│   ├── my-permission.controller.ts
-│   ├── role-permission.controller.ts
-│   ├── user-action-permission.controller.ts
-│   └── company-action-permission.controller.ts
-├── helpers/
-│   ├── company-access.helper.ts   # Company access validation
-│   └── permission-mode.helper.ts  # String to enum conversion
-├── dtos/
-│   ├── action.dto.ts
-│   ├── role.dto.ts
-│   └── permission.dto.ts
-├── interfaces/
-│   ├── action.interface.ts
-│   ├── role.interface.ts
-│   └── iam-module-options.interface.ts
-├── enums/
-│   ├── action-type.enum.ts
-│   └── permission-type.enum.ts
-├── types/
-│   └── logic-node.type.ts
-├── docs/
-│   └── iam-swagger.config.ts
-└── index.ts
-```
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-25
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.