Monorepo & Packages

Why a monorepo?

Exowpee uses a monorepo with Laravel packages to organize domain logic. Instead of putting everything in app/, each business domain lives in its own package under packages/. Benefits:

Isolation — Each package has its own models, routes, migrations, and tests
Reusability — A package can theoretically be extracted to its own repository
Clear boundaries — Inter-package communication happens through interfaces and contracts
Independent testing — You can test one package without loading others
Team scalability — Different developers can own different packages

How packages are registered

Packages are registered as Composer path repositories in the root composer.json:

{
  "repositories": [
    { "type": "path", "url": "packages/catalog" },
    { "type": "path", "url": "packages/customer" },
    { "type": "path", "url": "packages/iam" },
    { "type": "path", "url": "packages/ledger" },
    { "type": "path", "url": "packages/notification" },
    { "type": "path", "url": "packages/order" },
    { "type": "path", "url": "packages/shared" },
    { "type": "path", "url": "packages/team" }
  ],
  "require": {
    "exowpee/catalog": "*",
    "exowpee/customer": "*",
    "exowpee/iam": "*",
    "exowpee/ledger": "*",
    "exowpee/notification": "*",
    "exowpee/order": "*",
    "exowpee/shared": "*",
    "exowpee/team": "*"
  }
}

Each package has its own composer.json with a ServiceProvider that Laravel auto-discovers.

Package anatomy

Every package follows a standard structure:

packages/catalog/
├── src/
│   ├── Providers/
│   │   └── CatalogServiceProvider.php    # Entry point
│   ├── Http/
│   │   ├── Controllers/                  # API endpoints
│   │   ├── Requests/                     # Validation rules
│   │   ├── Resources/                    # Response transformers
│   │   └── routes.php                    # Route definitions
│   ├── Models/                           # Eloquent models
│   ├── Services/                         # Business logic
│   ├── Policies/                         # Authorization
│   ├── Enums/                            # Constants (ProductType, ProductStatus)
│   ├── Contracts/                        # Interfaces
│   └── Traits/                           # Reusable behaviors
├── database/
│   └── migrations/                       # Package migrations
├── lang/                                 # Translations (en, fr)
└── composer.json                         # Package metadata

What the ServiceProvider does

Each package’s ServiceProvider is the entry point that registers everything with Laravel:

class CatalogServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Load routes
        $this->loadRoutesFrom(__DIR__ . '/../Http/routes.php');

        // Load migrations
        $this->loadMigrationsFrom(__DIR__ . '/../../database/migrations');

        // Load translations
        $this->loadTranslationsFrom(__DIR__ . '/../../lang', 'catalog');

        // Register policies
        Gate::policy(Product::class, ProductPolicy::class);
        Gate::policy(Category::class, CategoryPolicy::class);
        // ... more policies
    }

    public function register(): void
    {
        // Bind interfaces to implementations
        $this->app->bind(CatalogInterface::class, CatalogService::class);
    }
}

Inter-package communication

Packages communicate through interfaces (contracts), never by directly importing another package’s internals.

Pattern: Contract-based communication

packages/catalog/src/Contracts/CatalogInterface.php   # Defines what Catalog exposes
packages/team/src/Contracts/TeamInterface.php          # Defines what Team exposes

Example: The Order package needs to check stock from the Catalog package:

// In packages/catalog/src/Contracts/CatalogInterface.php
interface CatalogInterface
{
    public function getVariantStock(string $variantId): int;
    public function decreaseStock(string $variantId, int $quantity): void;
}

// In packages/order/src/Services/OrderService.php
class OrderService
{
    public function __construct(
        private CatalogInterface $catalog
    ) {}

    public function confirmOrder(Order $order): void
    {
        foreach ($order->items as $item) {
            $this->catalog->decreaseStock($item->variation_id, $item->quantity);
        }
    }
}

The binding happens in the ServiceProvider:

$this->app->bind(CatalogInterface::class, CatalogService::class);

Why this pattern?

Packages never directly use models or services from other packages
You can swap implementations without changing consumers
Testing is easier — mock the interface

Package dependencies

The shared package is the base dependency — it provides:

KsuidTrait — KSUID primary key generation
HashPasswordTrait — Password hashing
OptimisticLockingTrait — Concurrency control
BeforePolicyFilterTrait — Pre-authorization checks
AuditableTrait — Activity logging (wraps Spatie’s LogsActivity)
ExowpeeCompanyCachableTrait — Company-level caching behavior
ExowpeeOrganizationCachableTrait — Organization-level caching behavior
WorkingHourTrait — Working hour management for companies
RestApiFormRequest — Base form request with JSON error handling
Helper functions (isKsuid(), uploadFile2(), toMinorUnit(), etc.)

Adding a new package

See the Package Development guide for step-by-step instructions on creating a new package.

Getting started

Architecture

Developer guide

Operations

More

Monorepo & Packages

Why a monorepo?

How packages are registered

Package anatomy

What the ServiceProvider does

Inter-package communication

Pattern: Contract-based communication

Why this pattern?

Package dependencies

Adding a new package

​Why a monorepo?

​How packages are registered

​Package anatomy

​What the ServiceProvider does

​Inter-package communication

​Pattern: Contract-based communication

​Why this pattern?

​Package dependencies

​Adding a new package

Why a monorepo?

How packages are registered

Package anatomy

What the ServiceProvider does

Inter-package communication

Pattern: Contract-based communication

Why this pattern?

Package dependencies

Adding a new package