gufi-cli 0.1.49 → 0.1.51

package/docs/dev-guide/1-02-multi-tenant.md

@@ -0,0 +1,415 @@
+---
+id: multi-tenant
+title: "Multi-Tenant System"
+description: "How Gufi isolates company data"
+icon: Building2
+category: dev
+part: 1
+---
+
+# Multi-Tenant System
+
+How Gufi isolates company data
+
+## Overview
+
+Gufi uses **schema-based multi-tenancy** where each company has its own PostgreSQL schema. This provides complete data isolation with excellent performance.
+
+## Schema Architecture
+
+### Core Schema
+
+The `core` schema contains platform-wide data:
+
+```sql
+-- Users (can belong to multiple companies)
+core.users
+├── id
+├── email
+├── name
+├── password_hash
+├── platform_role    -- admin, consultant, client
+└── created_at
+
+-- Companies
+core.companies
+├── id
+├── name
+├── settings (jsonb)
+└── created_at
+
+-- User-Company membership
+core.company_users
+├── user_id
+├── company_id
+├── roles (jsonb array)
+└── is_active
+
+-- Module definitions (templates)
+core.modules
+├── id
+├── company_id
+├── name
+├── config (jsonb)
+└── created_at
+
+-- Entity definitions
+core.entities
+├── id
+├── module_id
+├── name
+├── automations (jsonb)
+└── fields (jsonb)
+```
+
+### Company Schemas
+
+Each company gets a dedicated schema:
+
+```sql
+-- Company 146 has schema: company_146
+company_146.m360_t4589    -- Products table
+company_146.m360_t4590    -- Categories table
+company_146.m361_t4600    -- Customers table
+company_146.__audit_log__ -- Audit trail
+```
+
+### Naming Convention
+
+Tables follow the pattern `m{moduleId}_t{entityId}`:
+
+```
+m360_t4589
+│    └── Entity ID 4589
+└── Module ID 360
+```
+
+This ensures:
+- Unique table names across modules
+- Easy mapping to entity definitions
+- No name collisions between modules
+
+## Request Flow
+
+### JWT Contains Company
+
+Every authenticated request includes company context:
+
+```json
+{
+  "sub": "user_123",
+  "company_id": 146,
+  "roles": ["Admin"],
+  "exp": 1699999999
+}
+```
+
+### Backend Processing
+
+```javascript
+// Middleware extracts and sets context
+async function setTenantContext(req, res, next) {
+  const companyId = req.user.company_id;
+
+  // Get connection from pool
+  const client = await pool.connect();
+
+  // Set schema search path
+  await client.query(
+    `SET search_path TO company_${companyId}, core, public`
+  );
+
+  req.db = client;
+  next();
+}
+```
+
+### Query Execution
+
+With search_path set, queries automatically scope to company:
+
+```sql
+-- Developer writes:
+SELECT * FROM m360_t4589 WHERE status = 'active';
+
+-- PostgreSQL resolves to:
+SELECT * FROM company_146.m360_t4589 WHERE status = 'active';
+```
+
+## Data Isolation Guarantees
+
+### Schema Separation
+
+| Guarantee | Implementation |
+|---|---|
+| **No cross-company queries** | search_path prevents access |
+| **No data leakage** | Separate schemas, separate tables |
+| **Backup isolation** | Per-schema backups possible |
+| **Performance isolation** | Indexes are per-schema |
+
+### Security Layers
+
+```
+1. JWT Validation
+   └── Company ID extracted from token
+
+2. Middleware Check
+   └── User belongs to company verified
+
+3. Schema Switch
+   └── search_path set to company schema
+
+4. Query Execution
+   └── Only company data visible
+
+5. Response
+   └── Data returned (already filtered)
+```
+
+### What This Prevents
+
+```javascript
+// This is IMPOSSIBLE:
+// User from Company A querying Company B data
+
+// Even if an attacker modified the query to:
+SELECT * FROM company_200.products;
+
+// They would get:
+ERROR: permission denied for schema company_200
+```
+
+## Company Creation
+
+### Schema Provisioning
+
+When a new company is created:
+
+```javascript
+async function createCompanySchema(companyId) {
+  const schemaName = `company_${companyId}`;
+
+  // Create schema
+  await pool.query(`CREATE SCHEMA ${schemaName}`);
+
+  // Create system tables
+  await pool.query(`
+    CREATE TABLE ${schemaName}.__audit_log__ (
+      id SERIAL PRIMARY KEY,
+      table_name TEXT,
+      record_id INTEGER,
+      action TEXT,
+      old_data JSONB,
+      new_data JSONB,
+      user_id INTEGER,
+      created_at TIMESTAMP DEFAULT NOW()
+    )
+  `);
+
+  // Set up triggers for audit
+  // ... (trigger creation)
+}
+```
+
+### Module Installation
+
+When a module is installed for a company:
+
+```javascript
+async function installModule(companyId, moduleConfig) {
+  const schemaName = `company_${companyId}`;
+
+  for (const entity of moduleConfig.entities) {
+    const tableName = `m${moduleConfig.id}_t${entity.id}`;
+
+    // Create table with fields
+    const columns = entity.fields.map(f =>
+      `${f.name} ${mapToPostgresType(f.type)}`
+    ).join(', ');
+
+    await pool.query(`
+      CREATE TABLE ${schemaName}.${tableName} (
+        id SERIAL PRIMARY KEY,
+        ${columns},
+        created_at TIMESTAMP DEFAULT NOW(),
+        updated_at TIMESTAMP DEFAULT NOW(),
+        created_by INTEGER,
+        updated_by INTEGER
+      )
+    `);
+
+    // Create indexes, triggers, etc.
+  }
+}
+```
+
+## Logical vs Physical Names
+
+### The Mapping
+
+Users see logical names, database uses physical names:
+
+| Logical Name | Physical Name | Stored In |
+|---|---|---|
+| products | m360_t4589 | core.entities |
+| categories | m360_t4590 | core.entities |
+| customers | m361_t4600 | core.entities |
+
+### Resolution Process
+
+```javascript
+// Frontend requests using logical name
+GET /api/tables/products
+
+// Backend resolves to physical name
+async function resolveTableName(companyId, logicalName) {
+  const result = await pool.query(`
+    SELECT
+      CONCAT('m', m.id, '_t', e.id) as physical_name
+    FROM core.entities e
+    JOIN core.modules m ON e.module_id = m.id
+    WHERE m.company_id = $1 AND e.name = $2
+  `, [companyId, logicalName]);
+
+  return result.rows[0]?.physical_name;
+}
+
+// Query executed against physical table
+SELECT * FROM company_146.m360_t4589;
+```
+
+### Benefits
+
+1. **No Name Collisions**: Two modules can have "products" entity
+2. **Renaming**: Change display name without migrations
+3. **Module Portability**: Same module works across companies
+4. **Clear Ownership**: Table name shows which module owns it
+
+## Cross-Company Operations
+
+### Platform Admin Access
+
+Platform admins can query across companies:
+
+```javascript
+// Only for platform_role = 'admin'
+async function getCrossCompanyReport() {
+  // Temporarily use all schemas
+  const companies = await pool.query(
+    'SELECT id FROM core.companies'
+  );
+
+  const results = [];
+  for (const company of companies.rows) {
+    await pool.query(
+      `SET search_path TO company_${company.id}`
+    );
+
+    const data = await pool.query(
+      'SELECT COUNT(*) FROM m360_t4589'
+    );
+    results.push({ companyId: company.id, count: data.rows[0].count });
+  }
+
+  return results;
+}
+```
+
+### Data Migration
+
+Moving data between companies (rare):
+
+```javascript
+// Export from source
+SET search_path TO company_100;
+COPY products TO '/tmp/products.csv' CSV;
+
+// Import to destination
+SET search_path TO company_200;
+COPY products FROM '/tmp/products.csv' CSV;
+```
+
+## Performance Considerations
+
+### Schema Benefits
+
+- **Index isolation**: Each company's indexes are independent
+- **Statistics per schema**: Query planner optimizes per-company
+- **Vacuum per schema**: Maintenance can be targeted
+
+### Pooling Strategy
+
+```javascript
+// Connection pool is shared
+const pool = new Pool({
+  max: 100,  // Total connections
+  // ...
+});
+
+// But each request sets its own search_path
+// No connection affinity needed
+```
+
+### Caching
+
+Schema is cached per company:
+
+```javascript
+const schemaCache = new Map();
+
+async function getCompanySchema(companyId) {
+  const cacheKey = `schema:${companyId}`;
+
+  let schema = schemaCache.get(cacheKey);
+  if (!schema) {
+    schema = await loadSchemaFromDb(companyId);
+    schemaCache.set(cacheKey, schema);
+  }
+
+  return schema;
+}
+```
+
+## Best Practices
+
+### Always Use search_path
+
+```javascript
+// Good
+await client.query('SET search_path TO company_${id}');
+await client.query('SELECT * FROM products');
+
+// Bad - never hardcode schema in queries
+await client.query('SELECT * FROM company_${id}.products');
+```
+
+### Clean Up Connections
+
+```javascript
+async function handleRequest(req, res) {
+  const client = await pool.connect();
+  try {
+    await client.query(`SET search_path TO company_${req.companyId}`);
+    // ... do work ...
+  } finally {
+    await client.query('RESET search_path');
+    client.release();
+  }
+}
+```
+
+### Validate Company Access
+
+```javascript
+// Before any operation
+async function validateAccess(userId, companyId) {
+  const membership = await pool.query(`
+    SELECT 1 FROM core.company_users
+    WHERE user_id = $1 AND company_id = $2 AND is_active = true
+  `, [userId, companyId]);
+
+  if (membership.rows.length === 0) {
+    throw new ForbiddenError('Access denied');
+  }
+}
+```