How Packages Connect

Exowpee is a monorepo with eight packages inside packages/. Each package owns a specific business domain and communicates with others through contracts (PHP interfaces). This page shows you the full picture.

The Package Map

What Each Package Owns (One-Liner)

Package	One-liner	Directory
Shared	Common code that every package uses — helpers, traits, base classes	`packages/Shared/`
IAM	”Who is this person and what can they do?” — authentication, JWT, roles, permissions, profiles	`packages/Iam/`
Team	”What business structure do they belong to?” — organizations, companies, members, agents, currencies, settings	`packages/Team/`
Catalog	”What does this business sell?” — products, variants, categories, pricing, vendors, purchases, stock, assets	`packages/Catalog/`
Order	”What did someone buy?” — orders, order items, payments, cash registers, cashiers	`packages/Order/`
Ledger	”What is the financial impact?” — accounts, transactions, double-entry journal entries	`packages/Ledger/`
Customer	”Who are the buyers?” — customer records, credit tracking, payment history	`packages/Customer/`
Notification	”How do we communicate?” — email notifications for invitations, onboarding, verification, password reset	`packages/notification/`

How Packages Communicate: Contracts

Packages never import each other’s classes directly. Instead, they depend on interfaces (contracts): Each package exposes an interface in its src/Contracts/ directory. Other packages depend on the interface, not the implementation. Laravel’s service container binds the real class at runtime. Example: When the Order package needs to create an accounting entry after a sale, it does not import LedgerService directly. It uses LedgerInterface:

// In Order package — depends on the interface, not the class
public function __construct(LedgerInterface $ledger)
{
    $this->ledger = $ledger;
}

public function confirmOrder(Order $order)
{
    // ... change order status, decrease stock ...

    // Create the accounting entry via the contract
    $this->ledger->createTransaction([
        ['account' => 'cash', 'type' => 'debit', 'amount' => $order->total],
        ['account' => 'sales_revenue', 'type' => 'credit', 'amount' => $order->total],
    ]);
}

Why this matters: You can work on the Order package without understanding the Ledger internals. The interface is the contract — as long as it is respected, everything works.

The Request Journey: What Happens When Sena Makes a Sale

Let us trace POST /v1/order/orders from HTTP request to database writes, showing which packages are involved at each step.

Packages involved in a single sale:

Step	Package	What it does
Authentication	IAM	Decodes JWT, verifies the user is valid
Company context	Team	Sets the active company from the JWT payload
Permission check	IAM	Verifies the user has `orders.create` permission
Product validation	Catalog	Confirms the variant IDs exist and stock is available
Order creation	Order	Creates the order record and order items
Stock management	Catalog	Reserves and then decreases stock
Accounting	Ledger	Creates the balanced double-entry transaction

This is why understanding the package map matters — even a “simple” sale touches 4 out of 8 packages.

Dependency Rules

These rules keep the codebase maintainable:

Shared has no dependencies — it is the foundation layer
IAM depends only on Shared — authentication is a foundational concern
Team depends on IAM + Shared — organizational structure needs identity
Catalog, Order, Customer depend on IAM + Team + Shared — business logic needs both identity and company context
Ledger depends on IAM + Team + Shared — accounting needs identity and company context
Order depends on Catalog — orders reference products and manage stock
Order and Customer depend on Ledger — financial events create accounting entries
Notification depends on Shared — handles email sending (invitations, onboarding, verification, password reset)
No circular dependencies — if A depends on B, B must not depend on A

Common Mistakes

Importing a class from another package directly — Always use the contract interface. If you need something from the Ledger package, inject LedgerInterface, not LedgerService. Creating circular dependencies — If Package A depends on Package B, then Package B must not depend on Package A. If you need two-way communication, use events or a shared interface in the Shared package. Forgetting that Catalog is organization-scoped — Products, categories, and vendors are shared across all companies. If you add a company-specific filter to a catalog query, you will break multi-branch visibility. Forgetting that Stock is company-scoped — Stock levels are per company, not per organization. If you aggregate stock without grouping by company, the numbers will be wrong.

Where to Go Next

Step	What to read	What you will learn
Next	Multi-Tenancy Explained	How data scoping works in practice
Then	Authentication Explained	Users vs Agents, JWT, profile switching
Then	Permissions Explained	Roles, profiles, and permission checks

Previous: Permissions Explained | Next: Open your shop

Getting started

Architecture

Developer guide

Operations

More

How Packages Connect

The Package Map

What Each Package Owns (One-Liner)

How Packages Communicate: Contracts

The Request Journey: What Happens When Sena Makes a Sale

Packages involved in a single sale:

Dependency Rules

Common Mistakes

Where to Go Next

​The Package Map

​What Each Package Owns (One-Liner)

​How Packages Communicate: Contracts

​The Request Journey: What Happens When Sena Makes a Sale

​Packages involved in a single sale:

​Dependency Rules

​Common Mistakes

​Where to Go Next

The Package Map

What Each Package Owns (One-Liner)

How Packages Communicate: Contracts

The Request Journey: What Happens When Sena Makes a Sale

Packages involved in a single sale:

Dependency Rules

Common Mistakes

Where to Go Next