Skip to main content

Multi-Tenant Architecture

Overview​

The AttuneLogic API implements a robust multi-tenant architecture designed to serve multiple business types, primarily focusing on trucking and service/repair industries. The system uses a hybrid tenancy model that combines database-level isolation with shared infrastructure.

Core Components​

1. Tenant Model (Customer)​

CustomerSchema = {
  // Tenant Identifier
  slug: { type: String, unique: true },

  // Business Type
  appType: { type: String, enum: ["trucking", "serviceRepair"] },

  // Configuration
  metadata: Schema.Types.Mixed,

  // Status
  active: Boolean,
  paymentStatus: String,
};

2. Tenant Context​

The system maintains tenant context through:

  • URL-based identification (slug)
  • Authentication tokens
  • Request middleware
  • Parent company verification

Architectural Patterns​

1. Data Isolation​

// Example of tenant scoping in queries
async function findForTenant(model, query, tenant) {
  return model.find({
    ...query,
    parentCompany: tenant._id,
  });
}

2. Feature Segregation​

// Example of industry-specific feature toggle
if (customer.appType === "trucking") {
  // Enable trucking-specific features
  // - Route optimization
  // - Fleet management
  // - Driver tracking
} else if (customer.appType === "serviceRepair") {
  // Enable service industry features
  // - Service area management
  // - Technician scheduling
  // - Work order tracking
}

Security Implementation​

1. Tenant Isolation Middleware​

const verifyParent = async (req, res, next) => {
  // Verify user belongs to the correct tenant
  // Prevent cross-tenant data access
  // Validate tenant-specific permissions
};

2. Access Control​

  • Tenant-level administrators
  • Role-based access within tenants
  • Industry-specific permissions

Configuration Management​

1. Default Configurations​

  • Located in @services/config/default-configs/
  • Industry-specific defaults
  • Customizable per tenant

2. Custom Configurations​

  • Stored in tenant's metadata
  • Override capability
  • Feature flags

Database Strategy​

1. Collection Structure​

  • All collections include parentCompany reference
  • Indexes on tenant identifiers
  • Industry-specific collections when needed

2. Query Patterns​

// Example of tenant-scoped query
const jobs = await Job.find({
  parentCompany: req.user.parentCompany,
  // other query parameters
}).lean();

API Design​

1. Routing​

  • Version-based (/api/v1/)
  • Tenant identification
  • Industry-specific endpoints

2. Request Flow​

Request → Tenant Resolution → Authentication → Parent Verification → Handler

Industry-Specific Implementations​

1. Trucking Industry​

  • Fleet management module
  • Route optimization
  • Driver management
  • Load tracking
  • Maintenance scheduling

2. Service/Repair Industry​

  • Service area management
  • Technician dispatching
  • Work order system
  • Customer management
  • Inventory tracking

Scalability Considerations​

1. Database​

  • Indexed tenant queries
  • Efficient data partitioning
  • Query optimization

2. Caching​

  • Tenant-aware caching
  • Configuration caching
  • Session management

Best Practices​

1. Development Guidelines​

  • Always include tenant context
  • Validate cross-tenant operations
  • Use industry-specific feature flags
  • Implement proper error boundaries

2. Security Guidelines​

  • Strict tenant isolation
  • Role-based access control
  • Data validation per tenant
  • Audit logging

Common Patterns​

1. Controller Pattern​

async function listResources(req, res) {
  const { parentCompany } = req.user;
  const resources = await Resource.find({ parentCompany });
  return res.json({ resources });
}

2. Service Pattern​

class TenantService {
  constructor(tenant) {
    this.tenant = tenant;
  }

  async getConfiguration() {
    return {
      ...defaultConfig,
      ...this.tenant.metadata,
    };
  }
}

Testing Strategy​

1. Tenant Isolation Tests​

  • Verify data isolation
  • Test cross-tenant access prevention
  • Validate tenant-specific features

2. Industry-Specific Tests​

  • Test industry features
  • Validate business rules
  • Check configuration management

Monitoring and Debugging​

1. Logging​

  • Tenant-aware logging
  • Industry-specific metrics
  • Performance monitoring

2. Error Handling​

  • Tenant-specific error messages
  • Industry-context preservation
  • Proper error categorization

Future Considerations​

  1. Enhanced Tenant Analytics
  2. Dynamic Feature Management
  3. Improved Configuration System
  4. Advanced Industry Customization
  5. Cross-Tenant Collaboration Features

Last Updated: [Current Date] Version: 1.0