@venturialstd/organization 0.0.1 → 0.0.3

package/README.md

@@ -1,678 +1,910 @@
-# @venturialstd/organization
-
-Organization Management Module for Venturial - A NestJS module for managing organizations and organization members with role-based access control.
-
-## 📋 Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Module Structure](#module-structure)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Entities](#entities)
-- [API Reference](#api-reference)
-- [Enums & Constants](#enums--constants)
-- [Guards & Decorators](#guards--decorators)
-- [Test Server](#test-server)
-- [NPM Scripts](#npm-scripts)
-- [Usage Examples](#usage-examples)
-
----
-
-## ✨ Features
-
-- 🏢 **Organization Management**: Complete CRUD operations
-- 👥 **Member Management**: Add, invite, remove organization members
-- 🔐 **Role-Based Access**: Owner, Admin, Member, Viewer roles
-- ⚙️ **Settings System**: Configurable organization settings
-- 🛡️ **Guards & Decorators**: Request-level access control
-- 🔄 **TypeORM Integration**: Full database support with migrations
-- 📦 **Fully Typed**: Complete TypeScript support
-- 🧪 **Test Infrastructure**: Standalone test server on port 3002
-
----
-
-## 📦 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"
-}
-```
-
----
-
-## 📁 Module Structure
-
-```
-src/organization/
-├── package.json                           # Module configuration
-├── tsconfig.json                         # TypeScript configuration
-├── README.md                             # This file
-├── .npmignore                            # NPM publish exclusions
-├── src/                                  # Source code
-│   ├── constants/
-│   │   ├── organization.constant.ts      # Enums (roles, status)
-│   │   └── organization.settings.constant.ts  # Settings keys
-│   ├── decorators/
-│   │   ├── organization.decorator.ts     # @OrganizationId(), @UserId(), etc.
-│   │   └── roles.decorator.ts            # @Roles() decorator
-│   ├── entities/
-│   │   ├── organization.entity.ts        # Organization entity
-│   │   └── organization-user.entity.ts   # OrganizationUser entity
-│   ├── guards/
-│   │   └── organization.guard.ts         # OrganizationGuard, OrganizationRoleGuard
-│   ├── services/
-│   │   ├── organization.service.ts       # Organization CRUD service
-│   │   └── organization-user.service.ts  # User-Organization service
-│   ├── settings/
-│   │   └── organization.settings.ts      # Module settings definition
-│   ├── organization.module.ts            # NestJS module
-│   └── index.ts                          # Public exports
-└── test/                                 # Test infrastructure
-    ├── controllers/
-    │   ├── organization-test.controller.ts
-    │   └── organization-user-test.controller.ts
-    ├── migrations/                       # Database migrations
-    ├── .env.example                      # Environment template
-    ├── data-source.ts                    # TypeORM DataSource
-    ├── test-app.module.ts                # Test app module
-    └── main.ts                           # Test server bootstrap
-```
-
----
-
-## 🚀 Quick Start
-
-### 1. Import the Module
-
-```typescript
-import { Module } from '@nestjs/common';
-import { OrganizationModule } from '@venturialstd/organization';
-
-@Module({
-  imports: [OrganizationModule],
-})
-export class AppModule {}
-```
-
-### 2. Use the Services
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { OrganizationService, OrganizationUserService } from '@venturialstd/organization';
-
-@Injectable()
-export class YourService {
-  constructor(
-    private readonly organizationService: OrganizationService,
-    private readonly organizationUserService: OrganizationUserService,
-  ) {}
-
-  async createOrganization() {
-    const organization = await this.organizationService.createOrganization(
-      'My Organization',
-      'my-org',
-      'example.com',
-      'Organization description',
-      'user-id-123'
-    );
-    
-    return organization;
-  }
-
-  async addMember() {
-    return this.organizationUserService.addUserToOrganization(
-      'org-id',
-      'user-id',
-      ORGANIZATION_USER_ROLE.MEMBER
-    );
-  }
-}
-```
-
----
-
-## ⚙️ Configuration
-
-### Development Setup
-
-```bash
-# Navigate to module directory
-cd src/organization
-
-# Install dependencies
-npm install --legacy-peer-deps
-
-# Set up environment
-cp test/.env.example test/.env
-# Edit test/.env with your database credentials
-
-# Generate migration
-npm run migration:generate --name=InitialSchema
-
-# Run migrations
-npm run migration:run
-
-# Start test server
-npm run test:dev
-```
-
-### Environment Variables (test/.env)
-
-```bash
-APP_PORT=3002
-DB_HOST=localhost
-DB_PORT=5433
-DB_NAME=organization_test
-DB_USER=root
-DB_PASS=example
-```
-
----
-
-## 🗄️ Entities
-
-### Organization
-
-```typescript
-@Entity('organization')
-export class Organization {
-  id: string;                          // UUID primary key
-  name: string;                        // Unique organization name
-  slug: string;                        // Unique URL-friendly slug
-  domain?: string;                     // Optional custom domain
-  description?: string;                // Organization description
-  isActive: boolean;                   // Active/inactive status
-  settings: Record<string, unknown>;   // JSONB settings
-  ownerId?: string;                    // Owner user ID
-  createdAt: Date;                     // Creation timestamp
-  updatedAt: Date;                     // Update timestamp
-}
-```
-
-**Key Features:**
-- Unique `name` and `slug` constraints
-- JSONB `settings` for flexible configuration
-- Soft activation with `isActive` flag
-- Owner tracking via `ownerId`
-
-### OrganizationUser
-
-```typescript
-@Entity('organization_user')
-export class OrganizationUser {
-  id: string;                          // UUID primary key
-  organizationId: string;              // Organization reference (indexed)
-  userId: string;                      // User reference (indexed)
-  role: ORGANIZATION_USER_ROLE;        // User role in organization
-  status: ORGANIZATION_USER_STATUS;    // Member status
-  isPrimary: boolean;                  // Primary owner flag
-  invitedBy?: string;                  // Inviter user ID
-  invitedAt?: Date;                    // Invitation timestamp
-  joinedAt?: Date;                     // Join timestamp
-  permissions: Record<string, unknown>; // JSONB custom permissions
-  createdAt: Date;                     // Creation timestamp
-  updatedAt: Date;                     // Update timestamp
-}
-```
-
-**Key Features:**
-- Unique index on `(organizationId, userId)`
-- Separate indexes on `organizationId` and `userId`
-- Invitation system support
-- Primary owner designation
-- Custom permissions via JSONB
-
----
-
-## 📖 API Reference
-
-### OrganizationService
-
-#### Create Organization
-```typescript
-createOrganization(
-  name: string,
-  slug: string,
-  domain?: string,
-  description?: string,
-  ownerId?: string
-): Promise<Organization>
-```
-
-#### Find Methods
-```typescript
-getOrganizationBySlug(slug: string): Promise<Organization>
-getOrganizationByDomain(domain: string): Promise<Organization>
-getActiveOrganizations(): Promise<Organization[]>
-getOrganizationsByOwner(ownerId: string): Promise<Organization[]>
-```
-
-#### Update Methods
-```typescript
-updateOrganizationSettings(
-  organizationId: string,
-  settings: Record<string, unknown>
-): Promise<Organization>
-
-setOrganizationStatus(
-  organizationId: string,
-  isActive: boolean
-): Promise<Organization>
-```
-
-### OrganizationUserService
-
-#### Member Management
-```typescript
-addUserToOrganization(
-  organizationId: string,
-  userId: string,
-  role?: ORGANIZATION_USER_ROLE,
-  invitedBy?: string
-): Promise<OrganizationUser>
-
-inviteUserToOrganization(
-  organizationId: string,
-  userId: string,
-  role: ORGANIZATION_USER_ROLE,
-  invitedBy: string
-): Promise<OrganizationUser>
-
-acceptInvitation(
-  organizationId: string,
-  userId: string
-): Promise<OrganizationUser>
-
-removeUserFromOrganization(
-  organizationId: string,
-  userId: string
-): Promise<void>
-```
-
-#### Role Management
-```typescript
-updateUserRole(
-  organizationId: string,
-  userId: string,
-  newRole: ORGANIZATION_USER_ROLE
-): Promise<OrganizationUser>
-
-setPrimaryOwner(
-  organizationId: string,
-  userId: string
-): Promise<OrganizationUser>
-
-transferOwnership(
-  organizationId: string,
-  fromUserId: string,
-  toUserId: string
-): Promise<void>
-```
-
-#### Query Methods
-```typescript
-getUserOrganizations(userId: string): Promise<OrganizationUser[]>
-getOrganizationUsers(organizationId: string): Promise<OrganizationUser[]>
-getActiveOrganizationUsers(organizationId: string): Promise<OrganizationUser[]>
-getUserInvitations(userId: string): Promise<OrganizationUser[]>
-hasAccess(organizationId: string, userId: string): Promise<boolean>
-getUserRole(organizationId: string, userId: string): Promise<ORGANIZATION_USER_ROLE | null>
-```
-
-#### Status Management
-```typescript
-suspendUser(organizationId: string, userId: string): Promise<OrganizationUser>
-reactivateUser(organizationId: string, userId: string): Promise<OrganizationUser>
-```
-
----
-
-## 🎭 Enums & Constants
-
-### ORGANIZATION_USER_ROLE
-
-```typescript
-enum ORGANIZATION_USER_ROLE {
-  OWNER = 'owner',      // Full control over organization
-  ADMIN = 'admin',      // Administrative access
-  MEMBER = 'member',    // Standard member access
-  VIEWER = 'viewer'     // Read-only access
-}
-```
-
-### ORGANIZATION_USER_STATUS
-
-```typescript
-enum ORGANIZATION_USER_STATUS {
-  ACTIVE = 'active',       // Active member
-  INVITED = 'invited',     // Pending invitation
-  SUSPENDED = 'suspended'  // Suspended member
-}
-```
-
-### Settings Keys
-
-```typescript
-ORGANIZATION_SETTING_KEYS = {
-  GENERAL_MAX_ORGANIZATIONS: 'organization.general.max_organizations',
-  GENERAL_MAX_MEMBERS: 'organization.general.max_members',
-  FEATURES_CUSTOM_DOMAIN: 'organization.features.custom_domain',
-  FEATURES_API_ACCESS: 'organization.features.api_access',
-  FEATURES_SSO: 'organization.features.sso',
-  LIMITS_STORAGE: 'organization.limits.storage_gb',
-  LIMITS_BANDWIDTH: 'organization.limits.bandwidth_gb',
-  LIMITS_PROJECTS: 'organization.limits.projects',
-}
-```
-
----
-
-## 🛡️ Guards & Decorators
-
-### Decorators
-
-#### @OrganizationId()
-Extract organization ID from request:
-```typescript
-@Get()
-async getData(@OrganizationId() organizationId: string) {
-  return this.service.getData(organizationId);
-}
-```
-
-#### @UserId()
-Extract user ID from request:
-```typescript
-@Get()
-async getData(@UserId() userId: string) {
-  return this.service.getUserData(userId);
-}
-```
-
-#### @OrganizationContext()
-Extract full context:
-```typescript
-@Get()
-async getData(@OrganizationContext() context) {
-  // context = { organizationId, userId, role, user }
-  return this.service.getData(context);
-}
-```
-
-#### @Roles()
-Specify required roles:
-```typescript
-@Roles(ORGANIZATION_USER_ROLE.OWNER, ORGANIZATION_USER_ROLE.ADMIN)
-@UseGuards(OrganizationGuard, OrganizationRoleGuard)
-@Delete(':id')
-async delete() { ... }
-```
-
-### Guards
-
-#### OrganizationGuard
-Ensures user has access to the organization:
-```typescript
-@UseGuards(OrganizationGuard)
-@Get()
-async getData(@OrganizationId() organizationId: string) {
-  return this.service.getData(organizationId);
-}
-```
-
-#### OrganizationRoleGuard
-Enforces role-based access control:
-```typescript
-@Roles(ORGANIZATION_USER_ROLE.OWNER, ORGANIZATION_USER_ROLE.ADMIN)
-@UseGuards(OrganizationGuard, OrganizationRoleGuard)
-@Delete(':id')
-async delete() { ... }
-```
-
----
-
-## 🧪 Test Server
-
-Start the test server on port **3002**:
-
-```bash
-npm run test:dev
-```
-
-### Available Endpoints
-
-#### Organization Management
-```
-POST   /organizations                      - Create organization
-GET    /organizations                      - Get all organizations
-GET    /organizations/active               - Get active organizations
-GET    /organizations/owner/:ownerId       - Get by owner
-GET    /organizations/slug/:slug           - Get by slug
-GET    /organizations/domain/:domain       - Get by domain
-GET    /organizations/:id                  - Get by ID
-PUT    /organizations/:id/settings         - Update settings
-PUT    /organizations/:id/status           - Update status
-DELETE /organizations/:id                  - Delete organization
-```
-
-#### User-Organization Management
-```
-POST   /organization-users/add                              - Add user
-POST   /organization-users/invite                           - Invite user
-POST   /organization-users/accept-invitation                - Accept invite
-GET    /organization-users/organization/:organizationId     - Get members
-GET    /organization-users/organization/:organizationId/active - Get active members
-GET    /organization-users/user/:userId                     - Get user's organizations
-GET    /organization-users/user/:userId/invitations         - Get invitations
-GET    /organization-users/check-access/:orgId/:userId      - Check access
-GET    /organization-users/role/:orgId/:userId              - Get user role
-PUT    /organization-users/role                             - Update role
-PUT    /organization-users/primary-owner                    - Set primary owner
-POST   /organization-users/transfer-ownership               - Transfer ownership
-PUT    /organization-users/suspend                          - Suspend user
-PUT    /organization-users/reactivate                       - Reactivate user
-DELETE /organization-users/remove                           - Remove user
-```
-
----
-
-## 📝 NPM Scripts
-
-```bash
-# Build
-npm run build                              # Build TypeScript to dist/
-npm run prepublishOnly                     # Auto-build before publish
-
-# Publishing
-npm run release:patch                      # Build, bump version, publish
-
-# Development
-npm run test:dev                           # Start test server
-npm run test:watch                         # Watch mode for development
-
-# Migrations
-npm run migration:generate --name=Name     # Generate migration
-npm run migration:run                      # Run pending migrations
-npm run migration:revert                   # Revert last migration
-```
-
----
-
-## 💡 Usage Examples
-
-### Basic Organization Creation
-
-```typescript
-import { OrganizationService } from '@venturialstd/organization';
-
-@Injectable()
-export class MyService {
-  constructor(private orgService: OrganizationService) {}
-
-  async createOrg() {
-    return this.orgService.createOrganization(
-      'Acme Corp',
-      'acme-corp',
-      'acme.com',
-      'A leading company',
-      'owner-user-id-123'
-    );
-  }
-}
-```
-
-### Adding Members with Roles
-
-```typescript
-import { 
-  OrganizationUserService, 
-  ORGANIZATION_USER_ROLE 
-} from '@venturialstd/organization';
-
-@Injectable()
-export class MemberService {
-  constructor(private orgUserService: OrganizationUserService) {}
-
-  async addAdmin(orgId: string, userId: string) {
-    return this.orgUserService.addUserToOrganization(
-      orgId,
-      userId,
-      ORGANIZATION_USER_ROLE.ADMIN,
-      'inviter-user-id'
-    );
-  }
-}
-```
-
-### Protected Endpoints
-
-```typescript
-import { 
-  Controller, 
-  Get, 
-  UseGuards 
-} from '@nestjs/common';
-import {
-  OrganizationGuard,
-  OrganizationRoleGuard,
-  OrganizationId,
-  Roles,
-  ORGANIZATION_USER_ROLE
-} from '@venturialstd/organization';
-
-@Controller('projects')
-@UseGuards(OrganizationGuard)
-export class ProjectController {
-  
-  // Any member can view
-  @Get()
-  async list(@OrganizationId() orgId: string) {
-    return this.service.getProjects(orgId);
-  }
-
-  // Only owners and admins can delete
-  @Delete(':id')
-  @UseGuards(OrganizationRoleGuard)
-  @Roles(ORGANIZATION_USER_ROLE.OWNER, ORGANIZATION_USER_ROLE.ADMIN)
-  async delete(@OrganizationId() orgId: string, @Param('id') id: string) {
-    return this.service.deleteProject(orgId, id);
-  }
-}
-```
-
-### Invitation Flow
-
-```typescript
-@Injectable()
-export class InvitationService {
-  constructor(private orgUserService: OrganizationUserService) {}
-
-  // Step 1: Send invitation
-  async inviteMember(orgId: string, email: string, inviterId: string) {
-    const userId = await this.userService.findByEmail(email);
-    
-    return this.orgUserService.inviteUserToOrganization(
-      orgId,
-      userId,
-      ORGANIZATION_USER_ROLE.MEMBER,
-      inviterId
-    );
-  }
-
-  // Step 2: Get user's pending invitations
-  async getPendingInvites(userId: string) {
-    return this.orgUserService.getUserInvitations(userId);
-  }
-
-  // Step 3: Accept invitation
-  async acceptInvite(orgId: string, userId: string) {
-    return this.orgUserService.acceptInvitation(orgId, userId);
-  }
-}
-```
-
-### Ownership Transfer
-
-```typescript
-@Injectable()
-export class OwnershipService {
-  constructor(private orgUserService: OrganizationUserService) {}
-
-  async transferOwnership(
-    orgId: string,
-    currentOwnerId: string,
-    newOwnerId: string
-  ) {
-    // Verify current owner
-    const isPrimaryOwner = await this.orgUserService
-      .getUserRole(orgId, currentOwnerId);
-    
-    if (isPrimaryOwner !== ORGANIZATION_USER_ROLE.OWNER) {
-      throw new ForbiddenException('Only owner can transfer');
-    }
-
-    // Transfer
-    await this.orgUserService.transferOwnership(
-      orgId,
-      currentOwnerId,
-      newOwnerId
-    );
-  }
-}
-```
-
----
-
-## 📄 License
-
-MIT
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
----
-
-## 📧 Support
-
-For issues and questions, please create an issue in the repository.
-
----
-
-**Built with ❤️ using NestJS and TypeORM**
+# @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.