Skip to main content

​
System Architecture

Urban Things is built on a multi-tenant architecture using Laravel 11, enabling multiple organizations to use the platform while maintaining complete data isolation.

​
Tech Stack

Backend

  • Laravel 11.9
  • PHP 8.2+
  • MySQL (Production)
  • SQLite (Testing)

Authentication

  • Laravel Sanctum
  • Bearer Token Auth
  • Firebase Integration

​
Core Concepts

​
Multi-Tenancy Model

The platform uses a many-to-many relationship between Users and Tenants:
  • Users can belong to multiple organizations (tenants)
  • Each tenant can have multiple users
  • Roles are defined per tenant (ADMIN, MEMBER)
  • Complete data isolation between tenants

​
Database Schema

​
Users Table

Standard user accounts that can belong to multiple tenants:
  • Basic info: id, name, email, password
  • Status: is_active, user_type
  • Preferences: theme, language, timezone
  • Notifications: email_marketing, email_system, push_system

​
Tenants Table

Organizations using the platform:
  • id, name
  • Timestamps
  • Soft deletes enabled

​
Tenant_Users Pivot Table

Links users to tenants with metadata:
  • tenant_id, user_id
  • role (ADMIN, MEMBER)
  • is_active
  • last_active_at
  • Unique constraint on [tenant_id, user_id]

​
Automatic Tenant Scoping

Models using the HasTenant trait are automatically filtered by tenant: 
// Automatically filtered by X-Tenant-ID header
$products = Product::all();

// Bypass scoping when needed
$allProducts = Product::withAnyTenant()->get();

// Force specific tenant
$products = Product::forTenant($tenantId)->get();

​
Event-Driven Architecture

The system uses events and webhooks for integrations:
1

Event Triggered

User actions trigger events (e.g., UserRegistered)
2

Outbox Pattern

Events recorded in integration_outbox table
3

Background Processing

Jobs publish events to webhook subscribers
4

Delivery Tracking

Webhook deliveries tracked for reliability

​
Security Features

Tenant Isolation

Automatic data scoping prevents cross-tenant access

Role-Based Access

ADMIN role required for sensitive operations

Token Authentication

Sanctum tokens for secure API access

Input Validation

All inputs validated before processing

​
Performance Optimizations

​
Query Optimization

  • Single JOIN queries instead of N+1
  • Eager loading for relationships
  • Pagination for large datasets

​
Caching Strategy

  • Route caching
  • Config caching
  • Query result caching

​
Scalability

The architecture supports horizontal scaling:
  • Stateless API design
  • Database read replicas
  • Queue workers for background jobs
  • CDN for static assets

​
Migration Context

This project was originally single-tenant and is being migrated to multi-tenant architecture. The migration includes:
  • Adding tenant scoping to existing models
  • Implementing role-based access control
  • Creating middleware for automatic tenant filtering