Project Structure for Large Applications: Domain-Driven Laravel

Previously in this course, we explored how Project Board Domain Modeling: Database Design and Eloquent provides the foundation for our data. While that works for small apps, as your codebase grows, the default app/ structure—where everything is thrown into Models, Http/Controllers, or Services—becomes a maintenance nightmare.

The goal of this lesson is to shift your mindset from "organizing by type" to "organizing by domain." This is the key to architecture and scalability in large-scale applications.

Why the Default Structure Fails at Scale

In a standard Laravel installation, you have app/Http/Controllers, app/Models, and app/Services. When you add a new feature, you touch three different directories. This is "scattered cohesion." As your project board grows to include notifications, billing, and reporting, your file tree becomes a "junk drawer" where it’s impossible to tell which files belong to which feature.

Implementing Domain-Driven Directory Structures

To scale, we move toward a modular approach. We create an app/Domain directory. Inside this, we group code by the business concept it serves.

A Concrete Example: The Project Domain

Instead of having controllers and services mixed globally, we create a structure like this:

TEXT
app/
  Domain/
    Project/
      Actions/
      DTOs/
      Models/
      Services/
      Providers/
        ProjectServiceProvider.php
    Task/
      ...

By grouping these files, you can see the entire "Project" feature at a glance. If you need to delete or move the project logic, you move one folder, not ten.

Managing Service Providers for Modules

In a large application, your AppServiceProvider will quickly become a thousand-line mess of bindings. Instead, give each domain its own Service Provider.

In our ProjectServiceProvider, we register the domain-specific bindings:

PHP
namespace App\Domain\Project\Providers;

use Illuminate\Support\ServiceProvider;
use App\Domain\Project\Services\ProjectService;
use App\Domain\Project\Contracts\ProjectRepository;
use App\Domain\Project\Repositories\EloquentProjectRepository;

class ProjectServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->bind(ProjectRepository::class, EloquentProjectRepository::class);
        $this->app->singleton(ProjectService::class, function ($app) {
            return new ProjectService($app->make(ProjectRepository::class));
        });
    }
}

Then, add this provider to your config/app.php file. Now, the logic for binding services remains encapsulated within the domain itself. This keeps your main application configuration clean and makes the code modular.

Hands-On Exercise: Modularizing the Task Domain

1. Create a directory app/Domain/Task.
2. Move your existing Task model, TaskService, and TaskRepository into this new directory.
3. Update the namespaces of these classes to match the new structure (e.g., namespace App\Domain\Task\Models;).
4. Create a TaskServiceProvider within the domain folder and register your repository bindings there.
5. Update your config/app.php to load your new TaskServiceProvider.

Common Pitfalls

• Over-Engineering: Don't create a "Domain" folder for a project with only two features. This pattern is for when your application reaches a level of complexity where finding files takes more than a second.
• Circular Dependencies: If Domain\Project needs Domain\Task and Domain\Task needs Domain\Project, you have a design flaw. Keep domains independent. If they must talk, use Events or a shared "Support" or "Foundation" namespace for common interfaces.
• Namespace Bloat: Ensure your composer.json autoloading is configured correctly to handle the App\Domain namespace. Run composer dump-autoload after moving files.

Recap

Scalability isn't just about database indexes; it’s about the developer experience of navigating your code. By adopting a domain-driven structure, we:

1. Modularize code by grouping related features together.
2. Implement domain-driven directories to reduce mental overhead.
3. Manage service providers per domain to keep the global container organized.

This structure allows your team to work on the "Project" domain without stepping on the toes of the "User" or "Billing" domains. It’s the difference between a project that stays maintainable and one that collapses under its own weight.

Up next: We will dive into Environment and Configuration Management to ensure our modular domains remain configurable across different deployment environments.