@venturialstd/organization 0.0.2 → 0.0.3

package/README.md

@@ -1,910 +1,910 @@
-# @venturialstd/organization
-
-A comprehensive NestJS module for managing organizations with multi-tenant capabilities, role-based access control, and isolated per-organization settings.
-
-## 📋 Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [Architecture](#architecture)
-- [API Reference](#api-reference)
-- [Organization Settings System](#organization-settings-system)
-- [Test Server](#test-server)
-- [Migration Guide](#migration-guide)
-- [Examples](#examples)
-- [Best Practices](#best-practices)
-
----
-
-## ✨ Features
-
-- 🏢 **Organization Management**: Complete CRUD operations for organizations
-- 👥 **Member Management**: Add, invite, and manage organization members
-- 🔐 **Role-Based Access Control**: Owner, Admin, Member, and Viewer roles
-- ⚙️ **Isolated Settings System**: Per-organization configuration for modules
-- 🔒 **Complete Isolation**: No fallback between organizations
-- 🛡️ **Guards & Decorators**: Request-level access control
-- 🔄 **TypeORM Integration**: Full database support with migrations
-- 📦 **Fully Typed**: Complete TypeScript support
-- 🧪 **Test Infrastructure**: Standalone test server
-
----
-
-## 📦 Installation
-
-\`\`\`bash
-npm install @venturialstd/organization
-\`\`\`
-
-### Peer Dependencies
-
-\`\`\`json
-{
-  "@nestjs/common": "^11.0.11",
-  "@nestjs/core": "^11.0.5",
-  "@nestjs/typeorm": "^10.0.0",
-  "@venturialstd/core": "^1.0.16",
-  "class-transformer": "^0.5.1",
-  "class-validator": "^0.14.1",
-  "typeorm": "^0.3.20"
-}
-\`\`\`
-
----
-
-## 🚀 Quick Start
-
-### 1. Import the Module
-
-\`\`\`typescript
-import { Module } from '@nestjs/common';
-import { OrganizationModule } from '@venturialstd/organization';
-
-@Module({
-  imports: [OrganizationModule],
-})
-export class AppModule {}
-\`\`\`
-
-### 2. Run Migrations
-
-\`\`\`bash
-# Create and run migrations
-npm run migration:generate -- CreateOrganizations
-npm run migration:run
-\`\`\`
-
-### 3. Use the Services
-
-\`\`\`typescript
-import { Injectable } from '@nestjs/common';
-import { 
-  OrganizationService, 
-  OrganizationUserService,
-  ORGANIZATION_USER_ROLE 
-} from '@venturialstd/organization';
-
-@Injectable()
-export class YourService {
-  constructor(
-    private readonly organizationService: OrganizationService,
-    private readonly organizationUserService: OrganizationUserService,
-  ) {}
-
-  async createOrganization(userId: string) {
-    return this.organizationService.createOrganization(
-      'My Organization',
-      'my-org',
-      'example.com',
-      'Description',
-      userId
-    );
-  }
-
-  async addMember(organizationId: string, userId: string) {
-    return this.organizationUserService.addUserToOrganization(
-      organizationId,
-      userId,
-      ORGANIZATION_USER_ROLE.MEMBER
-    );
-  }
-}
-\`\`\`
-
----
-
-## 💡 Core Concepts
-
-### Organizations
-
-An organization represents a tenant in your multi-tenant application. Each organization:
-- Has a unique name and slug
-- Can have a custom domain
-- Has its own settings and configuration
-- Contains multiple members with different roles
-- Is completely isolated from other organizations
-
-### Organization Members
-
-Users can belong to multiple organizations with different roles:
-- **Owner**: Full control, can delete organization
-- **Admin**: Can manage members and settings
-- **Member**: Standard access to organization resources
-- **Viewer**: Read-only access
-
-### Organization Settings
-
-Each organization can have isolated settings for any module in your application:
-- **Complete Isolation**: No sharing between organizations
-- **No Fallback**: Each organization must configure its own settings
-- **Type-Safe**: Fully typed with TypeScript
-- **Module-Agnostic**: Works with any module (GitLab, Jira, Slack, etc.)
-
----
-
-## 🏗️ Architecture
-
-### Module Structure
-
-\`\`\`
-OrganizationModule
-├── Entities
-│   ├── Organization          # Organization entity
-│   ├── OrganizationUser      # User-Organization relationship
-│   └── OrganizationSettings  # Per-organization settings
-├── Services
-│   ├── OrganizationService           # CRUD operations
-│   ├── OrganizationUserService       # Member management
-│   └── OrganizationSettingsService   # Settings management
-├── Guards
-│   ├── OrganizationGuard            # Check user belongs to org
-│   └── OrganizationRoleGuard        # Check user role
-└── Decorators
-    ├── @OrganizationId()    # Extract org ID from request
-    ├── @UserId()            # Extract user ID from request
-    ├── @Roles()             # Define required roles
-    └── @OrganizationContext()  # Extract full context
-\`\`\`
-
-### Settings Isolation
-
-\`\`\`
-┌─────────────────────────────────────────────────┐
-│  Application                                    │
-│                                                 │
-│  ┌──────────────────────────────────────────┐  │
-│  │  Organization A                          │  │
-│  │  • GitLab: gitlab-a.com + token-a       │  │
-│  │  • Jira: jira-a.com + credentials-a     │  │
-│  └──────────────────────────────────────────┘  │
-│                                                 │
-│  ┌──────────────────────────────────────────┐  │
-│  │  Organization B                          │  │
-│  │  • GitLab: gitlab.com + token-b         │  │
-│  │  • Jira: [Not configured]               │  │
-│  └──────────────────────────────────────────┘  │
-│                                                 │
-└─────────────────────────────────────────────────┘
-\`\`\`
-
----
-
-## 📚 API Reference
-
-### Services
-
-#### OrganizationService
-
-\`\`\`typescript
-class OrganizationService {
-  // Create a new organization
-  createOrganization(
-    name: string,
-    slug: string,
-    domain: string,
-    description: string,
-    ownerId: string
-  ): Promise<Organization>
-
-  // Get organization by ID
-  getOrganizationById(id: string): Promise<Organization>
-
-  // Update organization
-  updateOrganization(id: string, data: Partial<Organization>): Promise<Organization>
-
-  // Delete organization
-  deleteOrganization(id: string): Promise<void>
-
-  // Get user's organizations
-  getUserOrganizations(userId: string): Promise<Organization[]>
-}
-\`\`\`
-
-#### OrganizationUserService
-
-\`\`\`typescript
-class OrganizationUserService {
-  // Add user to organization
-  addUserToOrganization(
-    organizationId: string,
-    userId: string,
-    role: ORGANIZATION_USER_ROLE
-  ): Promise<OrganizationUser>
-
-  // Remove user from organization
-  removeUserFromOrganization(
-    organizationId: string,
-    userId: string
-  ): Promise<void>
-
-  // Update user role
-  updateUserRole(
-    organizationId: string,
-    userId: string,
-    role: ORGANIZATION_USER_ROLE
-  ): Promise<OrganizationUser>
-
-  // Get organization members
-  getOrganizationMembers(organizationId: string): Promise<OrganizationUser[]>
-
-  // Check user role
-  getUserRole(
-    organizationId: string,
-    userId: string
-  ): Promise<ORGANIZATION_USER_ROLE>
-}
-\`\`\`
-
-#### OrganizationSettingsService
-
-\`\`\`typescript
-class OrganizationSettingsService {
-  // Get a single setting
-  get(organizationId: string, key: string): Promise<string | undefined>
-
-  // Get multiple settings
-  getManySettings(
-    organizationId: string,
-    keys: string[]
-  ): Promise<Record<string, string>>
-
-  // Get all settings for organization
-  getAllForOrganization(
-    organizationId: string,
-    module?: string
-  ): Promise<OrganizationSettings[]>
-
-  // Set or update a setting
-  setOrganizationSetting(
-    organizationId: string,
-    dto: Partial<OrganizationSettings>
-  ): Promise<OrganizationSettings>
-
-  // Delete a setting
-  deleteOrganizationSetting(
-    organizationId: string,
-    module: string,
-    section: string,
-    key: string
-  ): Promise<void>
-
-  // Reset all settings for a module
-  resetModuleSettings(
-    organizationId: string,
-    module: string
-  ): Promise<void>
-
-  // Bulk update settings
-  bulkUpdateSettings(
-    organizationId: string,
-    settings: Partial<OrganizationSettings>[]
-  ): Promise<OrganizationSettings[]>
-}
-\`\`\`
-
-### Entities
-
-#### Organization
-
-\`\`\`typescript
-class Organization {
-  id: string;
-  name: string;
-  slug: string;
-  domain: string;
-  description: string;
-  isActive: boolean;
-  settings: Record<string, unknown>;
-  ownerId: string;
-  createdAt: Date;
-  updatedAt: Date;
-}
-\`\`\`
-
-#### OrganizationUser
-
-\`\`\`typescript
-class OrganizationUser {
-  id: string;
-  organizationId: string;
-  userId: string;
-  role: ORGANIZATION_USER_ROLE;
-  isActive: boolean;
-  createdAt: Date;
-  updatedAt: Date;
-}
-\`\`\`
-
-#### OrganizationSettings
-
-\`\`\`typescript
-class OrganizationSettings {
-  id: string;
-  organizationId: string;
-  module: string;        // e.g., 'GITLAB', 'JIRA'
-  section: string;       // e.g., 'CREDENTIALS', 'OAUTH'
-  key: string;           // e.g., 'TOKEN', 'API_KEY'
-  value: string;
-  type: SETTINGS_TYPE;
-  label: string;
-  description: string;
-  options: object | null;
-  sortOrder: number;
-  createdAt: Date;
-  updatedAt: Date;
-}
-\`\`\`
-
-### Decorators
-
-\`\`\`typescript
-// Extract organization ID from request
-@Get()
-getData(@OrganizationId() organizationId: string) { }
-
-// Extract user ID from request
-@Get()
-getData(@UserId() userId: string) { }
-
-// Extract full context
-@Get()
-getData(@OrganizationContext() context: OrganizationContextType) { }
-
-// Define required roles
-@Roles(ORGANIZATION_USER_ROLE.ADMIN, ORGANIZATION_USER_ROLE.OWNER)
-@UseGuards(OrganizationRoleGuard)
-adminEndpoint() { }
-\`\`\`
-
-### Guards
-
-\`\`\`typescript
-// Check user belongs to organization
-@UseGuards(OrganizationGuard)
-@Get('organizations/:organizationId/data')
-getData() { }
-
-// Check user has required role
-@Roles(ORGANIZATION_USER_ROLE.ADMIN)
-@UseGuards(OrganizationRoleGuard)
-adminEndpoint() { }
-\`\`\`
-
-### Constants
-
-\`\`\`typescript
-// User roles
-enum ORGANIZATION_USER_ROLE {
-  OWNER = 'owner',
-  ADMIN = 'admin',
-  MEMBER = 'member',
-  VIEWER = 'viewer',
-}
-
-// Settings types
-enum SETTINGS_TYPE {
-  TEXT = 'text',
-  TEXTAREA = 'textarea',
-  NUMBER = 'number',
-  BOOLEAN = 'boolean',
-  SELECT = 'select',
-  MULTISELECT = 'multiselect',
-  JSON = 'json',
-  DATE = 'date',
-  SECRET = 'secret',
-}
-\`\`\`
-
----
-
-## ⚙️ Organization Settings System
-
-### Complete Isolation
-
-Organization settings are **completely isolated** with no fallback mechanism:
-
-\`\`\`typescript
-// Organization A
-const tokenA = await orgSettings.get('org-a-id', 'GITLAB:CREDENTIALS:TOKEN');
-// Returns: 'token-a'
-
-// Organization B (not configured)
-const tokenB = await orgSettings.get('org-b-id', 'GITLAB:CREDENTIALS:TOKEN');
-// Returns: undefined (NO FALLBACK)
-\`\`\`
-
-### Settings Types
-
-Use \`SETTINGS_TYPE\` enum for type-safe settings:
-
-\`\`\`typescript
-import { SETTINGS_TYPE } from '@venturialstd/organization';
-
-const settings = [
-  {
-    module: 'GITLAB',
-    section: 'CREDENTIALS',
-    key: 'TOKEN',
-    type: SETTINGS_TYPE.SECRET,  // Hides value in UI
-    // ...
-  },
-  {
-    module: 'GITLAB',
-    section: 'PREFERENCES',
-    key: 'AUTO_MERGE',
-    type: SETTINGS_TYPE.BOOLEAN,  // true/false toggle
-    // ...
-  },
-];
-\`\`\`
-
-### Using Settings in Your Module
-
-#### 1. Define Settings for Your Module
-
-\`\`\`typescript
-// src/your-module/settings/your-module.settings.ts
-import { SETTINGS_TYPE } from '@venturialstd/organization';
-
-export const SETTINGS = [
-  {
-    scope: 'ORGANIZATION',
-    module: 'YOUR_MODULE',
-    section: 'CREDENTIALS',
-    key: 'API_KEY',
-    label: 'API Key',
-    description: 'Your module API key',
-    type: SETTINGS_TYPE.SECRET,
-    value: '',
-    options: {
-      placeholder: 'Enter your API key',
-      help: 'Get your API key from your module dashboard',
-    },
-    sortOrder: 10,
-  },
-  {
-    scope: 'ORGANIZATION',
-    module: 'YOUR_MODULE',
-    section: 'CREDENTIALS',
-    key: 'API_SECRET',
-    label: 'API Secret',
-    description: 'Your module API secret',
-    type: SETTINGS_TYPE.SECRET,
-    value: '',
-    options: null,
-    sortOrder: 11,
-  },
-];
-\`\`\`
-
-#### 2. Use Settings in Your Service
-
-\`\`\`typescript
-import { Injectable } from '@nestjs/common';
-import { OrganizationSettingsService } from '@venturialstd/organization';
-
-@Injectable()
-export class YourModuleService {
-  constructor(
-    private readonly orgSettings: OrganizationSettingsService
-  ) {}
-
-  async connect(organizationId: string) {
-    // Get organization-specific credentials
-    const apiKey = await this.orgSettings.get(
-      organizationId,
-      'YOUR_MODULE:CREDENTIALS:API_KEY'
-    );
-
-    const apiSecret = await this.orgSettings.get(
-      organizationId,
-      'YOUR_MODULE:CREDENTIALS:API_SECRET'
-    );
-
-    // Check if configured
-    if (!apiKey || !apiSecret) {
-      throw new Error('Module not configured for this organization');
-    }
-
-    // Use organization-specific credentials
-    return this.client.connect({ apiKey, apiSecret });
-  }
-
-  async getMultipleSettings(organizationId: string) {
-    // Get multiple settings at once
-    const settings = await this.orgSettings.getManySettings(
-      organizationId,
-      [
-        'YOUR_MODULE:CREDENTIALS:API_KEY',
-        'YOUR_MODULE:CREDENTIALS:API_SECRET',
-        'YOUR_MODULE:PREFERENCES:TIMEOUT',
-      ]
-    );
-
-    return settings;
-  }
-}
-\`\`\`
-
-#### 3. Import OrganizationModule
-
-\`\`\`typescript
-import { Module } from '@nestjs/common';
-import { OrganizationModule } from '@venturialstd/organization';
-
-@Module({
-  imports: [OrganizationModule],
-  providers: [YourModuleService],
-})
-export class YourModule {}
-\`\`\`
-
-### Database Schema
-
-\`\`\`sql
-CREATE TABLE organization_settings (
-  id UUID PRIMARY KEY,
-  organizationId UUID REFERENCES organization(id) ON DELETE CASCADE,
-  module VARCHAR NOT NULL,        -- 'GITLAB', 'JIRA', 'YOUR_MODULE'
-  section VARCHAR NOT NULL,       -- 'CREDENTIALS', 'OAUTH', 'PREFERENCES'
-  key VARCHAR NOT NULL,           -- 'TOKEN', 'API_KEY', 'HOST'
-  value VARCHAR NOT NULL,         -- Actual value
-  type settings_type_enum NOT NULL,
-  label VARCHAR NOT NULL,
-  description VARCHAR,
-  options JSONB,
-  sortOrder INTEGER DEFAULT 0,
-  createdAt TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  updatedAt TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  UNIQUE(organizationId, module, section, key)
-);
-\`\`\`
-
----
-
-## 🧪 Test Server
-
-The module includes a standalone test server for development and testing.
-
-### Start the Test Server
-
-\`\`\`bash
-cd src/organization
-npm install
-npm run start:dev
-\`\`\`
-
-The server runs on **http://localhost:3002**
-
-### Test Endpoints
-
-\`\`\`bash
-# Get all organizations
-GET http://localhost:3002/test/organizations
-
-# Get organization by ID
-GET http://localhost:3002/test/organizations/:id
-
-# Get organization settings
-GET http://localhost:3002/test/organizations/:id/settings
-
-# Get settings for specific module
-GET http://localhost:3002/test/organizations/:id/settings?module=GITLAB
-
-# Create/update setting
-PUT http://localhost:3002/test/organizations/:id/settings
-Content-Type: application/json
-
-{
-  "module": "GITLAB",
-  "section": "CREDENTIALS",
-  "key": "TOKEN",
-  "value": "your-token",
-  "label": "GitLab Token",
-  "type": "secret"
-}
-\`\`\`
-
-### Test Controller
-
-The test controller is for **reference and development only**. In production, implement your own controllers with:
-- Custom authentication
-- Custom authorization
-- Custom validation
-- Custom error handling
-
-**Location:** \`test/controllers/organization-settings-test.controller.ts\`
-
----
-
-## 📖 Migration Guide
-
-### Running Migrations
-
-\`\`\`bash
-# Generate migration
-npm run migration:generate -- YourMigrationName
-
-# Run migrations
-npm run migration:run
-
-# Revert migration
-npm run migration:revert
-\`\`\`
-
-### Required Migrations
-
-The module requires these migrations:
-1. Create organizations table
-2. Create organization_users table
-3. Create organization_settings table
-
-Migrations are located in: \`database/migrations/\`
-
----
-
-## 💻 Examples
-
-### Example 1: Create Organization with Owner
-
-\`\`\`typescript
-@Injectable()
-export class OnboardingService {
-  constructor(
-    private readonly orgService: OrganizationService,
-    private readonly orgUserService: OrganizationUserService,
-  ) {}
-
-  async onboardUser(userId: string, companyName: string) {
-    // Create organization
-    const org = await this.orgService.createOrganization(
-      companyName,
-      this.generateSlug(companyName),
-      \`\${this.generateSlug(companyName)}.example.com\`,
-      \`\${companyName} organization\`,
-      userId
-    );
-
-    // Owner is automatically added by createOrganization
-    return org;
-  }
-
-  private generateSlug(name: string): string {
-    return name.toLowerCase().replace(/\\s+/g, '-');
-  }
-}
-\`\`\`
-
-### Example 2: Check User Permission
-
-\`\`\`typescript
-@Controller('organizations/:organizationId/data')
-export class DataController {
-  constructor(
-    private readonly orgUserService: OrganizationUserService,
-  ) {}
-
-  @Get()
-  @UseGuards(OrganizationGuard)
-  async getData(
-    @OrganizationId() organizationId: string,
-    @UserId() userId: string,
-  ) {
-    const role = await this.orgUserService.getUserRole(
-      organizationId,
-      userId
-    );
-
-    // Check if user has required role
-    if (![ORGANIZATION_USER_ROLE.ADMIN, ORGANIZATION_USER_ROLE.OWNER].includes(role)) {
-      throw new ForbiddenException('Insufficient permissions');
-    }
-
-    // Return data
-  }
-}
-\`\`\`
-
-### Example 3: Module with Organization Settings
-
-\`\`\`typescript
-// GitLab Service
-@Injectable()
-export class GitLabService {
-  constructor(
-    private readonly orgSettings: OrganizationSettingsService
-  ) {}
-
-  async getClient(organizationId: string) {
-    // Get org-specific GitLab credentials
-    const [host, token] = await Promise.all([
-      this.orgSettings.get(organizationId, 'GITLAB:CREDENTIALS:HOST'),
-      this.orgSettings.get(organizationId, 'GITLAB:CREDENTIALS:TOKEN'),
-    ]);
-
-    // Validate configuration
-    if (!host || !token) {
-      throw new Error(
-        'GitLab not configured for this organization. ' +
-        'Please configure it in organization settings.'
-      );
-    }
-
-    // Return organization-specific client
-    return new GitLab({ host, token });
-  }
-
-  async getRepositories(organizationId: string) {
-    const client = await this.getClient(organizationId);
-    return client.Projects.all();
-  }
-}
-\`\`\`
-
-### Example 4: Bulk Configure Organization
-
-\`\`\`typescript
-@Injectable()
-export class OrganizationSetupService {
-  constructor(
-    private readonly orgSettings: OrganizationSettingsService,
-  ) {}
-
-  async configureGitLab(
-    organizationId: string,
-    config: { host: string; token: string }
-  ) {
-    return this.orgSettings.bulkUpdateSettings(organizationId, [
-      {
-        module: 'GITLAB',
-        section: 'CREDENTIALS',
-        key: 'HOST',
-        value: config.host,
-        label: 'GitLab Host',
-        type: SETTINGS_TYPE.TEXT,
-      },
-      {
-        module: 'GITLAB',
-        section: 'CREDENTIALS',
-        key: 'TOKEN',
-        value: config.token,
-        label: 'GitLab Token',
-        type: SETTINGS_TYPE.SECRET,
-      },
-    ]);
-  }
-}
-\`\`\`
-
-### Example 5: Settings Resolution Pattern
-
-\`\`\`typescript
-@Injectable()
-export class IntegrationService {
-  constructor(
-    private readonly orgSettings: OrganizationSettingsService,
-  ) {}
-
-  async getIntegrationConfig(organizationId: string, integration: string) {
-    // Get all settings for this integration
-    const settings = await this.orgSettings.getAllForOrganization(
-      organizationId,
-      integration
-    );
-
-    // Check if configured
-    if (settings.length === 0) {
-      return {
-        configured: false,
-        message: \`\${integration} is not configured for this organization\`,
-      };
-    }
-
-    // Convert to key-value object
-    const config = settings.reduce((acc, setting) => {
-      acc[\`\${setting.section}:\${setting.key}\`] = setting.value;
-      return acc;
-    }, {});
-
-    return {
-      configured: true,
-      config,
-    };
-  }
-}
-\`\`\`
-
----
-
-## 📝 Best Practices
-
-### 1. Always Check Configuration
-
-\`\`\`typescript
-// ❌ Don't assume settings exist
-const token = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:TOKEN');
-await client.connect(token);  // Could be undefined!
-
-// ✅ Always validate
-const token = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:TOKEN');
-if (!token) {
-  throw new Error('Module not configured');
-}
-await client.connect(token);
-\`\`\`
-
-### 2. Use Bulk Operations
-
-\`\`\`typescript
-// ❌ Multiple single calls
-const host = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:HOST');
-const token = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:TOKEN');
-const secret = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:SECRET');
-
-// ✅ Single bulk call
-const settings = await orgSettings.getManySettings(orgId, [
-  'MODULE:CREDENTIALS:HOST',
-  'MODULE:CREDENTIALS:TOKEN',
-  'MODULE:CREDENTIALS:SECRET',
-]);
-\`\`\`
-
-### 3. Implement Your Own Controllers
-
-\`\`\`typescript
-// ❌ Don't use test controller in production
-import { OrganizationSettingsTestController } from '@venturialstd/organization';
-
-// ✅ Implement your own
-@Controller('api/organizations/:organizationId/settings')
-@UseGuards(JwtAuthGuard, OrganizationGuard)
-export class OrganizationSettingsController {
-  // Your implementation with proper auth
-}
-\`\`\`
-
-### 4. Use Type-Safe Settings Types
-
-\`\`\`typescript
-// ✅ Import and use the enum
-import { SETTINGS_TYPE } from '@venturialstd/organization';
-
-const setting = {
-  type: SETTINGS_TYPE.SECRET,  // Type-safe
-  // ...
-};
-\`\`\`
-
----
-
-## 📄 License
-
-MIT
-
----
-
-## 🤝 Contributing
-
-Contributions welcome! Please read the contributing guidelines before submitting PRs.
+# @venturialstd/organization
+
+A comprehensive NestJS module for managing organizations with multi-tenant capabilities, role-based access control, and isolated per-organization settings.
+
+## 📋 Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Architecture](#architecture)
+- [API Reference](#api-reference)
+- [Organization Settings System](#organization-settings-system)
+- [Test Server](#test-server)
+- [Migration Guide](#migration-guide)
+- [Examples](#examples)
+- [Best Practices](#best-practices)
+
+---
+
+## ✨ Features
+
+- 🏢 **Organization Management**: Complete CRUD operations for organizations
+- 👥 **Member Management**: Add, invite, and manage organization members
+- 🔐 **Role-Based Access Control**: Owner, Admin, Member, and Viewer roles
+- ⚙️ **Isolated Settings System**: Per-organization configuration for modules
+- 🔒 **Complete Isolation**: No fallback between organizations
+- 🛡️ **Guards & Decorators**: Request-level access control
+- 🔄 **TypeORM Integration**: Full database support with migrations
+- 📦 **Fully Typed**: Complete TypeScript support
+- 🧪 **Test Infrastructure**: Standalone test server
+
+---
+
+## 📦 Installation
+
+\`\`\`bash
+npm install @venturialstd/organization
+\`\`\`
+
+### Peer Dependencies
+
+\`\`\`json
+{
+  "@nestjs/common": "^11.0.11",
+  "@nestjs/core": "^11.0.5",
+  "@nestjs/typeorm": "^10.0.0",
+  "@venturialstd/core": "^1.0.16",
+  "class-transformer": "^0.5.1",
+  "class-validator": "^0.14.1",
+  "typeorm": "^0.3.20"
+}
+\`\`\`
+
+---
+
+## 🚀 Quick Start
+
+### 1. Import the Module
+
+\`\`\`typescript
+import { Module } from '@nestjs/common';
+import { OrganizationModule } from '@venturialstd/organization';
+
+@Module({
+  imports: [OrganizationModule],
+})
+export class AppModule {}
+\`\`\`
+
+### 2. Run Migrations
+
+\`\`\`bash
+# Create and run migrations
+npm run migration:generate -- CreateOrganizations
+npm run migration:run
+\`\`\`
+
+### 3. Use the Services
+
+\`\`\`typescript
+import { Injectable } from '@nestjs/common';
+import { 
+  OrganizationService, 
+  OrganizationUserService,
+  ORGANIZATION_USER_ROLE 
+} from '@venturialstd/organization';
+
+@Injectable()
+export class YourService {
+  constructor(
+    private readonly organizationService: OrganizationService,
+    private readonly organizationUserService: OrganizationUserService,
+  ) {}
+
+  async createOrganization(userId: string) {
+    return this.organizationService.createOrganization(
+      'My Organization',
+      'my-org',
+      'example.com',
+      'Description',
+      userId
+    );
+  }
+
+  async addMember(organizationId: string, userId: string) {
+    return this.organizationUserService.addUserToOrganization(
+      organizationId,
+      userId,
+      ORGANIZATION_USER_ROLE.MEMBER
+    );
+  }
+}
+\`\`\`
+
+---
+
+## 💡 Core Concepts
+
+### Organizations
+
+An organization represents a tenant in your multi-tenant application. Each organization:
+- Has a unique name and slug
+- Can have a custom domain
+- Has its own settings and configuration
+- Contains multiple members with different roles
+- Is completely isolated from other organizations
+
+### Organization Members
+
+Users can belong to multiple organizations with different roles:
+- **Owner**: Full control, can delete organization
+- **Admin**: Can manage members and settings
+- **Member**: Standard access to organization resources
+- **Viewer**: Read-only access
+
+### Organization Settings
+
+Each organization can have isolated settings for any module in your application:
+- **Complete Isolation**: No sharing between organizations
+- **No Fallback**: Each organization must configure its own settings
+- **Type-Safe**: Fully typed with TypeScript
+- **Module-Agnostic**: Works with any module (GitLab, Jira, Slack, etc.)
+
+---
+
+## 🏗️ Architecture
+
+### Module Structure
+
+\`\`\`
+OrganizationModule
+├── Entities
+│   ├── Organization          # Organization entity
+│   ├── OrganizationUser      # User-Organization relationship
+│   └── OrganizationSettings  # Per-organization settings
+├── Services
+│   ├── OrganizationService           # CRUD operations
+│   ├── OrganizationUserService       # Member management
+│   └── OrganizationSettingsService   # Settings management
+├── Guards
+│   ├── OrganizationGuard            # Check user belongs to org
+│   └── OrganizationRoleGuard        # Check user role
+└── Decorators
+    ├── @OrganizationId()    # Extract org ID from request
+    ├── @UserId()            # Extract user ID from request
+    ├── @Roles()             # Define required roles
+    └── @OrganizationContext()  # Extract full context
+\`\`\`
+
+### Settings Isolation
+
+\`\`\`
+┌─────────────────────────────────────────────────┐
+│  Application                                    │
+│                                                 │
+│  ┌──────────────────────────────────────────┐  │
+│  │  Organization A                          │  │
+│  │  • GitLab: gitlab-a.com + token-a       │  │
+│  │  • Jira: jira-a.com + credentials-a     │  │
+│  └──────────────────────────────────────────┘  │
+│                                                 │
+│  ┌──────────────────────────────────────────┐  │
+│  │  Organization B                          │  │
+│  │  • GitLab: gitlab.com + token-b         │  │
+│  │  • Jira: [Not configured]               │  │
+│  └──────────────────────────────────────────┘  │
+│                                                 │
+└─────────────────────────────────────────────────┘
+\`\`\`
+
+---
+
+## 📚 API Reference
+
+### Services
+
+#### OrganizationService
+
+\`\`\`typescript
+class OrganizationService {
+  // Create a new organization
+  createOrganization(
+    name: string,
+    slug: string,
+    domain: string,
+    description: string,
+    ownerId: string
+  ): Promise<Organization>
+
+  // Get organization by ID
+  getOrganizationById(id: string): Promise<Organization>
+
+  // Update organization
+  updateOrganization(id: string, data: Partial<Organization>): Promise<Organization>
+
+  // Delete organization
+  deleteOrganization(id: string): Promise<void>
+
+  // Get user's organizations
+  getUserOrganizations(userId: string): Promise<Organization[]>
+}
+\`\`\`
+
+#### OrganizationUserService
+
+\`\`\`typescript
+class OrganizationUserService {
+  // Add user to organization
+  addUserToOrganization(
+    organizationId: string,
+    userId: string,
+    role: ORGANIZATION_USER_ROLE
+  ): Promise<OrganizationUser>
+
+  // Remove user from organization
+  removeUserFromOrganization(
+    organizationId: string,
+    userId: string
+  ): Promise<void>
+
+  // Update user role
+  updateUserRole(
+    organizationId: string,
+    userId: string,
+    role: ORGANIZATION_USER_ROLE
+  ): Promise<OrganizationUser>
+
+  // Get organization members
+  getOrganizationMembers(organizationId: string): Promise<OrganizationUser[]>
+
+  // Check user role
+  getUserRole(
+    organizationId: string,
+    userId: string
+  ): Promise<ORGANIZATION_USER_ROLE>
+}
+\`\`\`
+
+#### OrganizationSettingsService
+
+\`\`\`typescript
+class OrganizationSettingsService {
+  // Get a single setting
+  get(organizationId: string, key: string): Promise<string | undefined>
+
+  // Get multiple settings
+  getManySettings(
+    organizationId: string,
+    keys: string[]
+  ): Promise<Record<string, string>>
+
+  // Get all settings for organization
+  getAllForOrganization(
+    organizationId: string,
+    module?: string
+  ): Promise<OrganizationSettings[]>
+
+  // Set or update a setting
+  setOrganizationSetting(
+    organizationId: string,
+    dto: Partial<OrganizationSettings>
+  ): Promise<OrganizationSettings>
+
+  // Delete a setting
+  deleteOrganizationSetting(
+    organizationId: string,
+    module: string,
+    section: string,
+    key: string
+  ): Promise<void>
+
+  // Reset all settings for a module
+  resetModuleSettings(
+    organizationId: string,
+    module: string
+  ): Promise<void>
+
+  // Bulk update settings
+  bulkUpdateSettings(
+    organizationId: string,
+    settings: Partial<OrganizationSettings>[]
+  ): Promise<OrganizationSettings[]>
+}
+\`\`\`
+
+### Entities
+
+#### Organization
+
+\`\`\`typescript
+class Organization {
+  id: string;
+  name: string;
+  slug: string;
+  domain: string;
+  description: string;
+  isActive: boolean;
+  settings: Record<string, unknown>;
+  ownerId: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+\`\`\`
+
+#### OrganizationUser
+
+\`\`\`typescript
+class OrganizationUser {
+  id: string;
+  organizationId: string;
+  userId: string;
+  role: ORGANIZATION_USER_ROLE;
+  isActive: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+\`\`\`
+
+#### OrganizationSettings
+
+\`\`\`typescript
+class OrganizationSettings {
+  id: string;
+  organizationId: string;
+  module: string;        // e.g., 'GITLAB', 'JIRA'
+  section: string;       // e.g., 'CREDENTIALS', 'OAUTH'
+  key: string;           // e.g., 'TOKEN', 'API_KEY'
+  value: string;
+  type: SETTINGS_TYPE;
+  label: string;
+  description: string;
+  options: object | null;
+  sortOrder: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+\`\`\`
+
+### Decorators
+
+\`\`\`typescript
+// Extract organization ID from request
+@Get()
+getData(@OrganizationId() organizationId: string) { }
+
+// Extract user ID from request
+@Get()
+getData(@UserId() userId: string) { }
+
+// Extract full context
+@Get()
+getData(@OrganizationContext() context: OrganizationContextType) { }
+
+// Define required roles
+@Roles(ORGANIZATION_USER_ROLE.ADMIN, ORGANIZATION_USER_ROLE.OWNER)
+@UseGuards(OrganizationRoleGuard)
+adminEndpoint() { }
+\`\`\`
+
+### Guards
+
+\`\`\`typescript
+// Check user belongs to organization
+@UseGuards(OrganizationGuard)
+@Get('organizations/:organizationId/data')
+getData() { }
+
+// Check user has required role
+@Roles(ORGANIZATION_USER_ROLE.ADMIN)
+@UseGuards(OrganizationRoleGuard)
+adminEndpoint() { }
+\`\`\`
+
+### Constants
+
+\`\`\`typescript
+// User roles
+enum ORGANIZATION_USER_ROLE {
+  OWNER = 'owner',
+  ADMIN = 'admin',
+  MEMBER = 'member',
+  VIEWER = 'viewer',
+}
+
+// Settings types
+enum SETTINGS_TYPE {
+  TEXT = 'text',
+  TEXTAREA = 'textarea',
+  NUMBER = 'number',
+  BOOLEAN = 'boolean',
+  SELECT = 'select',
+  MULTISELECT = 'multiselect',
+  JSON = 'json',
+  DATE = 'date',
+  SECRET = 'secret',
+}
+\`\`\`
+
+---
+
+## ⚙️ Organization Settings System
+
+### Complete Isolation
+
+Organization settings are **completely isolated** with no fallback mechanism:
+
+\`\`\`typescript
+// Organization A
+const tokenA = await orgSettings.get('org-a-id', 'GITLAB:CREDENTIALS:TOKEN');
+// Returns: 'token-a'
+
+// Organization B (not configured)
+const tokenB = await orgSettings.get('org-b-id', 'GITLAB:CREDENTIALS:TOKEN');
+// Returns: undefined (NO FALLBACK)
+\`\`\`
+
+### Settings Types
+
+Use \`SETTINGS_TYPE\` enum for type-safe settings:
+
+\`\`\`typescript
+import { SETTINGS_TYPE } from '@venturialstd/organization';
+
+const settings = [
+  {
+    module: 'GITLAB',
+    section: 'CREDENTIALS',
+    key: 'TOKEN',
+    type: SETTINGS_TYPE.SECRET,  // Hides value in UI
+    // ...
+  },
+  {
+    module: 'GITLAB',
+    section: 'PREFERENCES',
+    key: 'AUTO_MERGE',
+    type: SETTINGS_TYPE.BOOLEAN,  // true/false toggle
+    // ...
+  },
+];
+\`\`\`
+
+### Using Settings in Your Module
+
+#### 1. Define Settings for Your Module
+
+\`\`\`typescript
+// src/your-module/settings/your-module.settings.ts
+import { SETTINGS_TYPE } from '@venturialstd/organization';
+
+export const SETTINGS = [
+  {
+    scope: 'ORGANIZATION',
+    module: 'YOUR_MODULE',
+    section: 'CREDENTIALS',
+    key: 'API_KEY',
+    label: 'API Key',
+    description: 'Your module API key',
+    type: SETTINGS_TYPE.SECRET,
+    value: '',
+    options: {
+      placeholder: 'Enter your API key',
+      help: 'Get your API key from your module dashboard',
+    },
+    sortOrder: 10,
+  },
+  {
+    scope: 'ORGANIZATION',
+    module: 'YOUR_MODULE',
+    section: 'CREDENTIALS',
+    key: 'API_SECRET',
+    label: 'API Secret',
+    description: 'Your module API secret',
+    type: SETTINGS_TYPE.SECRET,
+    value: '',
+    options: null,
+    sortOrder: 11,
+  },
+];
+\`\`\`
+
+#### 2. Use Settings in Your Service
+
+\`\`\`typescript
+import { Injectable } from '@nestjs/common';
+import { OrganizationSettingsService } from '@venturialstd/organization';
+
+@Injectable()
+export class YourModuleService {
+  constructor(
+    private readonly orgSettings: OrganizationSettingsService
+  ) {}
+
+  async connect(organizationId: string) {
+    // Get organization-specific credentials
+    const apiKey = await this.orgSettings.get(
+      organizationId,
+      'YOUR_MODULE:CREDENTIALS:API_KEY'
+    );
+
+    const apiSecret = await this.orgSettings.get(
+      organizationId,
+      'YOUR_MODULE:CREDENTIALS:API_SECRET'
+    );
+
+    // Check if configured
+    if (!apiKey || !apiSecret) {
+      throw new Error('Module not configured for this organization');
+    }
+
+    // Use organization-specific credentials
+    return this.client.connect({ apiKey, apiSecret });
+  }
+
+  async getMultipleSettings(organizationId: string) {
+    // Get multiple settings at once
+    const settings = await this.orgSettings.getManySettings(
+      organizationId,
+      [
+        'YOUR_MODULE:CREDENTIALS:API_KEY',
+        'YOUR_MODULE:CREDENTIALS:API_SECRET',
+        'YOUR_MODULE:PREFERENCES:TIMEOUT',
+      ]
+    );
+
+    return settings;
+  }
+}
+\`\`\`
+
+#### 3. Import OrganizationModule
+
+\`\`\`typescript
+import { Module } from '@nestjs/common';
+import { OrganizationModule } from '@venturialstd/organization';
+
+@Module({
+  imports: [OrganizationModule],
+  providers: [YourModuleService],
+})
+export class YourModule {}
+\`\`\`
+
+### Database Schema
+
+\`\`\`sql
+CREATE TABLE organization_settings (
+  id UUID PRIMARY KEY,
+  organizationId UUID REFERENCES organization(id) ON DELETE CASCADE,
+  module VARCHAR NOT NULL,        -- 'GITLAB', 'JIRA', 'YOUR_MODULE'
+  section VARCHAR NOT NULL,       -- 'CREDENTIALS', 'OAUTH', 'PREFERENCES'
+  key VARCHAR NOT NULL,           -- 'TOKEN', 'API_KEY', 'HOST'
+  value VARCHAR NOT NULL,         -- Actual value
+  type settings_type_enum NOT NULL,
+  label VARCHAR NOT NULL,
+  description VARCHAR,
+  options JSONB,
+  sortOrder INTEGER DEFAULT 0,
+  createdAt TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updatedAt TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE(organizationId, module, section, key)
+);
+\`\`\`
+
+---
+
+## 🧪 Test Server
+
+The module includes a standalone test server for development and testing.
+
+### Start the Test Server
+
+\`\`\`bash
+cd src/organization
+npm install
+npm run start:dev
+\`\`\`
+
+The server runs on **http://localhost:3002**
+
+### Test Endpoints
+
+\`\`\`bash
+# Get all organizations
+GET http://localhost:3002/test/organizations
+
+# Get organization by ID
+GET http://localhost:3002/test/organizations/:id
+
+# Get organization settings
+GET http://localhost:3002/test/organizations/:id/settings
+
+# Get settings for specific module
+GET http://localhost:3002/test/organizations/:id/settings?module=GITLAB
+
+# Create/update setting
+PUT http://localhost:3002/test/organizations/:id/settings
+Content-Type: application/json
+
+{
+  "module": "GITLAB",
+  "section": "CREDENTIALS",
+  "key": "TOKEN",
+  "value": "your-token",
+  "label": "GitLab Token",
+  "type": "secret"
+}
+\`\`\`
+
+### Test Controller
+
+The test controller is for **reference and development only**. In production, implement your own controllers with:
+- Custom authentication
+- Custom authorization
+- Custom validation
+- Custom error handling
+
+**Location:** \`test/controllers/organization-settings-test.controller.ts\`
+
+---
+
+## 📖 Migration Guide
+
+### Running Migrations
+
+\`\`\`bash
+# Generate migration
+npm run migration:generate -- YourMigrationName
+
+# Run migrations
+npm run migration:run
+
+# Revert migration
+npm run migration:revert
+\`\`\`
+
+### Required Migrations
+
+The module requires these migrations:
+1. Create organizations table
+2. Create organization_users table
+3. Create organization_settings table
+
+Migrations are located in: \`database/migrations/\`
+
+---
+
+## 💻 Examples
+
+### Example 1: Create Organization with Owner
+
+\`\`\`typescript
+@Injectable()
+export class OnboardingService {
+  constructor(
+    private readonly orgService: OrganizationService,
+    private readonly orgUserService: OrganizationUserService,
+  ) {}
+
+  async onboardUser(userId: string, companyName: string) {
+    // Create organization
+    const org = await this.orgService.createOrganization(
+      companyName,
+      this.generateSlug(companyName),
+      \`\${this.generateSlug(companyName)}.example.com\`,
+      \`\${companyName} organization\`,
+      userId
+    );
+
+    // Owner is automatically added by createOrganization
+    return org;
+  }
+
+  private generateSlug(name: string): string {
+    return name.toLowerCase().replace(/\\s+/g, '-');
+  }
+}
+\`\`\`
+
+### Example 2: Check User Permission
+
+\`\`\`typescript
+@Controller('organizations/:organizationId/data')
+export class DataController {
+  constructor(
+    private readonly orgUserService: OrganizationUserService,
+  ) {}
+
+  @Get()
+  @UseGuards(OrganizationGuard)
+  async getData(
+    @OrganizationId() organizationId: string,
+    @UserId() userId: string,
+  ) {
+    const role = await this.orgUserService.getUserRole(
+      organizationId,
+      userId
+    );
+
+    // Check if user has required role
+    if (![ORGANIZATION_USER_ROLE.ADMIN, ORGANIZATION_USER_ROLE.OWNER].includes(role)) {
+      throw new ForbiddenException('Insufficient permissions');
+    }
+
+    // Return data
+  }
+}
+\`\`\`
+
+### Example 3: Module with Organization Settings
+
+\`\`\`typescript
+// GitLab Service
+@Injectable()
+export class GitLabService {
+  constructor(
+    private readonly orgSettings: OrganizationSettingsService
+  ) {}
+
+  async getClient(organizationId: string) {
+    // Get org-specific GitLab credentials
+    const [host, token] = await Promise.all([
+      this.orgSettings.get(organizationId, 'GITLAB:CREDENTIALS:HOST'),
+      this.orgSettings.get(organizationId, 'GITLAB:CREDENTIALS:TOKEN'),
+    ]);
+
+    // Validate configuration
+    if (!host || !token) {
+      throw new Error(
+        'GitLab not configured for this organization. ' +
+        'Please configure it in organization settings.'
+      );
+    }
+
+    // Return organization-specific client
+    return new GitLab({ host, token });
+  }
+
+  async getRepositories(organizationId: string) {
+    const client = await this.getClient(organizationId);
+    return client.Projects.all();
+  }
+}
+\`\`\`
+
+### Example 4: Bulk Configure Organization
+
+\`\`\`typescript
+@Injectable()
+export class OrganizationSetupService {
+  constructor(
+    private readonly orgSettings: OrganizationSettingsService,
+  ) {}
+
+  async configureGitLab(
+    organizationId: string,
+    config: { host: string; token: string }
+  ) {
+    return this.orgSettings.bulkUpdateSettings(organizationId, [
+      {
+        module: 'GITLAB',
+        section: 'CREDENTIALS',
+        key: 'HOST',
+        value: config.host,
+        label: 'GitLab Host',
+        type: SETTINGS_TYPE.TEXT,
+      },
+      {
+        module: 'GITLAB',
+        section: 'CREDENTIALS',
+        key: 'TOKEN',
+        value: config.token,
+        label: 'GitLab Token',
+        type: SETTINGS_TYPE.SECRET,
+      },
+    ]);
+  }
+}
+\`\`\`
+
+### Example 5: Settings Resolution Pattern
+
+\`\`\`typescript
+@Injectable()
+export class IntegrationService {
+  constructor(
+    private readonly orgSettings: OrganizationSettingsService,
+  ) {}
+
+  async getIntegrationConfig(organizationId: string, integration: string) {
+    // Get all settings for this integration
+    const settings = await this.orgSettings.getAllForOrganization(
+      organizationId,
+      integration
+    );
+
+    // Check if configured
+    if (settings.length === 0) {
+      return {
+        configured: false,
+        message: \`\${integration} is not configured for this organization\`,
+      };
+    }
+
+    // Convert to key-value object
+    const config = settings.reduce((acc, setting) => {
+      acc[\`\${setting.section}:\${setting.key}\`] = setting.value;
+      return acc;
+    }, {});
+
+    return {
+      configured: true,
+      config,
+    };
+  }
+}
+\`\`\`
+
+---
+
+## 📝 Best Practices
+
+### 1. Always Check Configuration
+
+\`\`\`typescript
+// ❌ Don't assume settings exist
+const token = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:TOKEN');
+await client.connect(token);  // Could be undefined!
+
+// ✅ Always validate
+const token = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:TOKEN');
+if (!token) {
+  throw new Error('Module not configured');
+}
+await client.connect(token);
+\`\`\`
+
+### 2. Use Bulk Operations
+
+\`\`\`typescript
+// ❌ Multiple single calls
+const host = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:HOST');
+const token = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:TOKEN');
+const secret = await orgSettings.get(orgId, 'MODULE:CREDENTIALS:SECRET');
+
+// ✅ Single bulk call
+const settings = await orgSettings.getManySettings(orgId, [
+  'MODULE:CREDENTIALS:HOST',
+  'MODULE:CREDENTIALS:TOKEN',
+  'MODULE:CREDENTIALS:SECRET',
+]);
+\`\`\`
+
+### 3. Implement Your Own Controllers
+
+\`\`\`typescript
+// ❌ Don't use test controller in production
+import { OrganizationSettingsTestController } from '@venturialstd/organization';
+
+// ✅ Implement your own
+@Controller('api/organizations/:organizationId/settings')
+@UseGuards(JwtAuthGuard, OrganizationGuard)
+export class OrganizationSettingsController {
+  // Your implementation with proper auth
+}
+\`\`\`
+
+### 4. Use Type-Safe Settings Types
+
+\`\`\`typescript
+// ✅ Import and use the enum
+import { SETTINGS_TYPE } from '@venturialstd/organization';
+
+const setting = {
+  type: SETTINGS_TYPE.SECRET,  // Type-safe
+  // ...
+};
+\`\`\`
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Please read the contributing guidelines before submitting PRs.