@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
- Installation
- Quick Start
- Core Concepts
- Architecture
- API Reference
- Organization Settings System
- Test Server
- Migration Guide
- Examples
- 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
\\\

$3

\\\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

$3

\\\typescript
import { Module } from '@nestjs/common';
import { OrganizationModule } from '@venturialstd/organization';

@Module({
imports: [OrganizationModule],
})
export class AppModule {}
\\\

$3

\\\bash

Create and run migrations

npm run migration:generate -- CreateOrganizations
npm run migration:run
\\\

$3

\\\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

$3

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

$3

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

$3

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

$3

\\\
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
\\\

$3

\\\
┌─────────────────────────────────────────────────┐
│ 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

$3

#### OrganizationService

\\\typescript
class OrganizationService {
// Create a new organization
createOrganization(
name: string,
slug: string,
domain: string,
description: string,
ownerId: string
): Promise

// Get organization by ID
getOrganizationById(id: string): Promise

// Update organization
updateOrganization(id: string, data: Partial): Promise

// Delete organization
deleteOrganization(id: string): Promise

// Get user's organizations
getUserOrganizations(userId: string): Promise
}
\\\

#### OrganizationUserService

\\\typescript
class OrganizationUserService {
// Add user to organization
addUserToOrganization(
organizationId: string,
userId: string,
role: ORGANIZATION_USER_ROLE
): Promise

// Remove user from organization
removeUserFromOrganization(
organizationId: string,
userId: string
): Promise

// Update user role
updateUserRole(
organizationId: string,
userId: string,
role: ORGANIZATION_USER_ROLE
): Promise

// Get organization members
getOrganizationMembers(organizationId: string): Promise

// Check user role
getUserRole(
organizationId: string,
userId: string
): Promise
}
\\\

#### OrganizationSettingsService

\\\typescript
class OrganizationSettingsService {
// Get a single setting
get(organizationId: string, key: string): Promise

// Get multiple settings
getManySettings(
organizationId: string,
keys: string[]
): Promise>

// Get all settings for organization
getAllForOrganization(
organizationId: string,
module?: string
): Promise

// Set or update a setting
setOrganizationSetting(
organizationId: string,
dto: Partial
): Promise

// Delete a setting
deleteOrganizationSetting(
organizationId: string,
module: string,
section: string,
key: string
): Promise

// Reset all settings for a module
resetModuleSettings(
organizationId: string,
module: string
): Promise

// Bulk update settings
bulkUpdateSettings(
organizationId: string,
settings: Partial[]
): Promise
}
\\\

$3

#### Organization

\\\typescript
class Organization {
id: string;
name: string;
slug: string;
domain: string;
description: string;
isActive: boolean;
settings: Record;
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;
}
\\\

$3

\\\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() { }
\\\

$3

\\\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() { }
\\\

$3

\\\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

$3

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)
\\\

$3

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
// ...
},
];
\\\

$3

#### 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 {}
\\\

$3

\\\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.

$3

\\\bash
cd src/organization
npm install
npm run start:dev
\\\

The server runs on http://localhost:3002

$3

\\\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"
}
\\\

$3

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

$3

\\\bash

Generate migration

npm run migration:generate -- YourMigrationName

Run migrations

npm run migration:run

Revert migration

npm run migration:revert
\\\

$3

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

$3

\\\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, '-');
}
}
\\\

$3

\\\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
}
}
\\\

$3

\\\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();
}
}
\\\

$3

\\\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,
},
]);
}
}
\\\

$3

\\\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

$3

\\\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);
\\\

$3

\\\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

\\\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
}
\\\

$3

\\\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.