A modular monolith in Laravel preserves one of the framework’s best advantages: fast, coherent delivery. It also creates boundaries around business capabilities so the codebase does not become a single web of models, observers, and helpers. The goal is not to imitate microservices inside folders. It is to make change safer.
Begin with business capabilities
Modules should reflect language the product team uses: Orders, Billing, Catalog, Subscriptions, or Identity. “Controllers” and “Repositories” are technical layers, not business boundaries. A module should own the behavior and data decisions for its capability.
Boundaries will be imperfect at first. That is normal. Start with areas that change for different reasons and have recognizable owners, then refine them as the product teaches you more.
Make dependency direction explicit
Billing may need to know that an order became payable, but it should not reach through Order internals and update arbitrary tables. Expose a small application service, command, query, or event. The important part is that another module consumes a deliberate contract rather than accidental implementation details.
Static analysis and architecture tests can prevent forbidden namespaces from being imported. A boundary that exists only in a diagram will gradually disappear under delivery pressure.
Keep transactions local where possible
A monolith can use one database transaction across modules, but doing so everywhere creates hidden coupling. Let a module protect its own invariants. For follow-up work that can be eventually consistent, publish an event after the transaction commits.
Events need ownership and clear semantics. OrderPaid is a business fact; OrderUpdated forces every listener to inspect vague state. Avoid turning events into an invisible call stack that nobody can trace.
Use Laravel conventions without leaking everything
Eloquent, queues, validation, and service providers are useful. Modularity does not require hiding Laravel behind an interface for every class. Add an abstraction where it protects a volatile external dependency or an important domain boundary, not as a reflex.
A practical structure might keep HTTP and console entry points, application actions, domain rules, and infrastructure adapters within each module. Shared code should remain small. A large “Common” module is often the new monolith.
Choose data ownership deliberately
Separate databases are not required. Tables can live in one schema while ownership remains clear. Other modules may reference an identifier without treating the foreign model as their own mutable object. Reporting and read models can combine data without opening write access everywhere.
Test through stable boundaries
Unit-test domain rules that are independent. Feature-test each module’s public actions with Laravel and the database. Add a few cross-module workflow tests around the business journeys that matter most. Avoid asserting every internal call; that makes refactoring the module unnecessarily painful.
What a modular monolith does not solve
It cannot replace clear ownership, production metrics, or good database design. It also does not provide independent scaling and deployment. If one capability eventually has a radically different load profile or an independent team, a real service boundary may become useful.
Extract only after the boundary has evidence
A well-contained module is easier to extract, but extraction still adds network failure, distributed tracing, contract versioning, and data consistency work. Make that move for a measured reason—team autonomy, operational isolation, or distinct scale—not because the codebase reached an arbitrary size.
A good modular monolith keeps today’s deployment simple while making tomorrow’s choices less expensive.
For broader scaling decisions, see the backend architecture service. If an existing codebase has unclear boundaries, a Laravel code audit can map the highest-risk coupling before refactoring begins.
A concrete module layout
Start with a feature whose language is already stable. The following layout keeps its public contract visible while leaving implementation details private. It is an illustration, not a Laravel framework requirement. Controllers can remain in the standard application directory if moving them would add confusion; the boundary is enforced by imports and ownership, not by the path alone.
app/Modules/Orders/
Contracts/OrderReader.php
Application/PlaceOrder.php
Domain/Order.php
Events/OrderPlaced.php
Infrastructure/EloquentOrderReader.php
OrdersServiceProvider.phpOther modules may depend on Contracts/OrderReader.php and consume a small response object. They should not construct EloquentOrderReader, query the orders table directly, or mutate an Order model to bypass an invariant. The provider binds the contract to the implementation. If the contract exposes every Eloquent method, it has not reduced coupling; it has only renamed it.
Write a dependency rule that a build can enforce
Choose one direction for dependencies. For example, application code may call its own domain layer, while infrastructure implements domain or application contracts. A Billing class may import an Orders contract but must not import App\Modules\Orders\Infrastructure. A simple architecture check can scan PHP imports and fail when a forbidden namespace appears. As the codebase grows, a PHP architecture testing tool can make the rule more expressive.
Test the rule against a deliberately forbidden import before trusting it. Also decide what happens with Eloquent relationships between modules. A read-only reporting query may legitimately join tables, but that exception needs an owner and a narrow location. Without an explicit exception policy, developers will eventually add joins wherever a deadline demands one, and the diagram will become decorative.
Events and transactions: a complete order example
Suppose Orders owns placing an order and Billing owns creating an invoice. The order transaction validates inventory and writes the order. Once committed, Orders emits OrderPlaced with an order identifier and schema version. Billing handles that fact and creates its invoice idempotently. Its handler should tolerate delivery more than once because queue retries are normal. If invoicing must succeed in the same transaction for legal or product reasons, document that stronger consistency requirement instead of disguising it as an asynchronous event.
An event payload should contain identifiers and facts, not a serialized Eloquent model. Consumers can then evolve independently of model attributes. Name the event in past tense, record who owns it, and document whether it is emitted before or after commit. Laravel's after-commit queue behavior can help prevent a worker from observing a database state that has not committed yet, but its exact configuration must be checked in the application.
Move an existing Laravel codebase in small steps
- Map one business journey, the classes it touches, and the database writes it makes. Note hidden entry points such as scheduled jobs, observers, and console commands.
- Pick one capability with a clear owner. Move behavior behind an application action while keeping the existing HTTP response and database schema stable.
- Add the contract that another module actually needs. Migrate one consumer at a time and remove direct imports after each migration.
- Enforce the new import rule in CI. Review exceptions in code review, with a reason and an expiration or follow-up task.
- Measure whether change becomes easier: files touched per feature, cross-module defects, and time spent understanding dependencies. These are internal measures, not universal benchmarks.
This sequence keeps a deployable application at every step. A large folder move can create a noisy diff while leaving coupling intact; a small contract backed by an enforceable rule provides more useful progress.
Decision matrix: monolith, modules, or services
| Condition | Likely choice | Reason to revisit |
|---|---|---|
| Small team, one release cycle, intertwined data | Well-structured monolith | Changes repeatedly cross unclear ownership lines |
| Several business capabilities, one deployment remains useful | Modular monolith | A capability needs independent operations or release control |
| Independent team and measured isolation need | Service boundary candidate | Network and data consistency cost exceeds the benefit |
Neither row is a scorecard that automatically chooses an architecture. Examine deployment frequency, failure isolation, data ownership, and the team's ability to operate distributed systems. For related design decisions, the Laravel SaaS architecture guide discusses how tenant context crosses queues, cache, and storage. Those same cross-cutting concerns can reveal a poorly chosen module boundary.
For the framework behavior behind this design, consult Laravel's official service provider documentation and queue and after-commit documentation.
Frequently asked questions
Is a modular monolith just folders?
No. The value comes from dependency rules and ownership of data and behavior. Folder structure only makes those boundaries visible.
Can a module become a microservice later?
Potentially. A clear boundary makes extraction less painful, but distribution should still be justified by scaling, ownership, or operational needs.