🏗️ Domion – The Ultimate DDD Starter Kit for Laravel

Welcome to Domion! 👋

Simplify your enterprise Laravel development with a robust Domain-Driven Design (DDD) architecture. Domion is not just a structure package; it is a Complete Starter Kit that gives you everything you need to launch a professional, scalable application in minutes.

Whether you're building a RESTful API, a React SPA, or a Vue.js application, Domion has you covered with pre-configured authentication, settings modules, and enterprise-grade patterns.

🚀 Why Choose Domion?

📦 Installation Guide

Follow these simple steps to start your journey with Domion.

Step 1: Create a Laravel Project

Start with a fresh Laravel installation.

laravel new my-app
cd my-app

Step 2: Install Domion

Install the package via Composer.

composer require samushi/domion

Step 3: Setup Your Architecture 🪄

This is where the magic happens. The interactive setup command will:

• Ask you to choose between API, React, or Vue mode
• Configure your project structure
• Install all necessary dependencies
• Scaffold core domains (Auth, Dashboard, Settings)
• Set up 2FA via Fortify (for React/Vue modes)

php artisan domion:setup

Step 4: Launch Your Application

For API Mode:

php artisan migrate
php artisan serve

For React/Vue Mode:

npm install
npm run dev
php artisan migrate
php artisan serve

Open your browser and explore your new application!

🎯 Starter Kit Modes

Domion supports three distinct modes, each optimized for different use cases.

1. 🔌 API Mode (Headless)

Perfect for building RESTful APIs, mobile backends, or microservices.

Features:

• No frontend UI – pure JSON API endpoints
• Standardized API responses via laravel-api-response-builder
• Token-based authentication (Laravel Sanctum)
• Clean controller structure extending ApiControllers

API Response Example:

// In your Controller
return $this->success($data, 'Data retrieved successfully');

// Response:
{
    "success": true,
    "code": 200,
    "message": "Data retrieved successfully",
    "data": { ... }
}

Error Response:

return $this->error('Validation failed', 422);

// Response:
{
    "success": false,
    "code": 422,
    "message": "Validation failed"
}

2. ⚛️ React Mode (Inertia.js)

Modern single-page application experience with React and TypeScript.

Features:

• Full React + TypeScript + Inertia.js setup
• Pre-built pages: Login, Register, Dashboard, Settings
• Shadcn-inspired UI components
• Dark/Light mode support
• Sidebar navigation layout
• Two-Factor Authentication UI

Included Pages:

• / – Landing Page
• /login – Authentication
• /register – User Registration
• /dashboard – Protected Dashboard
• /settings/profile – Profile Management
• /settings/password – Password Update
• /settings/appearance – Theme Selection
• /settings/two-factor – 2FA Management

3. 💚 Vue Mode (Inertia.js)

Elegant single-page application with Vue 3 and TypeScript.

Features:

• Full Vue 3 + TypeScript + Inertia.js setup
• Same pre-built pages as React mode
• Component-based architecture
• Dark/Light mode support
• Responsive layouts

🏗️ Architecture Overview

Domion organizes your code into Domains. Each domain is self-contained, handling its own logic, database interactions, and frontend views (if applicable).

Directory Structure

app/
├── Domain/
│   ├── Auth/                    # Authentication Domain
│   │   ├── Actions/             # LoginAction, RegisterAction, etc.
│   │   ├── Controllers/         # AuthController
│   │   ├── Requests/            # LoginRequest, RegisterRequest
│   │   └── web.php              # Domain routes
│   │
│   ├── Dashboard/               # Dashboard Domain
│   │   ├── Controllers/         # DashboardController
│   │   └── web.php              # Dashboard routes
│   │
│   ├── Settings/                # Settings Domain
│   │   ├── Actions/             # UpdateUserProfileAction, DeleteUserAction
│   │   ├── Dto/                 # UpdateProfileDto, UpdatePasswordDto
│   │   ├── Requests/            # ProfileUpdateRequest, PasswordUpdateRequest
│   │   ├── Controllers/         # SettingsController
│   │   └── web.php              # Settings routes
│   │
│   ├── User/                    # User Domain
│   │   ├── Models/              # User.php
│   │   └── Repository/          # UserRepository
│   │
│   └── [YourDomain]/            # Your Custom Business Logic
│       ├── Actions/
│       ├── Dto/
│       ├── Models/
│       ├── Repository/
│       ├── Requests/
│       └── Controllers/
│
├── Support/                     # Shared Infrastructure
│   ├── Controllers/             # Base Controllers (ApiControllers, InertiaControllers)
│   ├── Traits/                  # HttpResponseTrait, InertiaResponseTrait
│   ├── Middleware/              # HandleInertiaRequests
│   └── Frontend/                # Layouts, Components (React/Vue)
│       ├── Layouts/
│       ├── components/
│       └── Pages/

🧱 Core Concepts

1. Actions (Business Logic)

Actions are the heart of your business logic. Each action does one thing and does it well.

Creating an Action:

php artisan domion:make:action CreateOrder

Action Structure:

<?php

namespace App\Domain\Orders\Actions;

use Samushi\Domion\Actions\ActionFactory;
use App\Domain\Orders\Dto\CreateOrderDto;
use App\Domain\Orders\Repository\OrderRepository;

class CreateOrderAction extends ActionFactory
{
    public function __construct(
        protected OrderRepository $orderRepository
    ) {}

    public function handle(CreateOrderDto $dto): Order
    {
        return $this->orderRepository->create($dto->toArray());
    }
}

Calling an Action:

// Static call (recommended)
$order = CreateOrderAction::run($dto);

// Or with error handling
$result = CreateOrderAction::runSafe($dto);
if ($result['success']) {
    // Handle success
}

2. DTOs (Data Transfer Objects)

DTOs ensure type safety and clean data flow between layers.

DTO Structure:

<?php

namespace App\Domain\Orders\Dto;

use App\Support\DataObjects;

class CreateOrderDto extends DataObjects
{
    public function __construct(
        public readonly int $customerId,
        public readonly array $items,
        public readonly float $total,
    ) {}
}

Creating from Request:

// In Controller
$dto = CreateOrderDto::fromRequest($request);

// The base DataObjects class automatically maps validated() data to constructor properties

Available Methods:

• fromRequest(FormRequest $request) – Create from validated request
• fromArray(array $data) – Create from array
• toArray() – Convert to array
• toCollection() – Convert to Laravel Collection

3. Repositories (Data Access Layer)

Repositories abstract database operations and integrate with Query Filters.

Repository Structure:

<?php

namespace App\Domain\Orders\Repository;

use App\Domain\Orders\Models\Order;
use App\Support\Repositories;
use Illuminate\Database\Eloquent\Model;

class OrderRepository extends Repositories
{
    protected function getModel(): Model
    {
        return new Order();
    }

    // Optional: Define domain-specific filters
    protected function getFilters(): array
    {
        return [
            new \App\Domain\Orders\Filters\StatusFilter(),
            new \App\Domain\Orders\Filters\CustomerFilter(),
        ];
    }
}

Available Repository Methods:

$repository->all();                    // Get all records
$repository->paginate(15);             // Paginate results
$repository->find($id);                // Find by ID
$repository->findOrFail($id);          // Find or throw exception
$repository->findBy('email', $email);  // Find by column
$repository->findWhere(['status' => 'active']); // Find with conditions
$repository->create($data);            // Create record
$repository->update($data, $id);       // Update record
$repository->delete($id);              // Delete record
$repository->exists($id);              // Check existence
$repository->count();                  // Count records

4. Query Filters (samushi/query-filter)

Domion integrates samushi/query-filter for powerful, reusable query filtering.

Creating a Filter:

<?php

namespace App\Domain\Orders\Filters;

use Samushi\QueryFilter\Filter;

class StatusFilter extends Filter
{
    public function applyFilter($builder)
    {
        return $builder->where('status', $this->getValue());
    }
}

Usage in Repository: Filters are automatically applied when you call all() or paginate() if query parameters match.

// Request: GET /orders?status=pending&search=john

$orders = $orderRepository->paginate(15);
// Automatically filtered by status and searched!

Built-in Filters:

• Search – Full-text search across searchable columns
• Order – Dynamic ordering (e.g., ?order_by=created_at&order_dir=desc)

5. Controllers

Controllers are thin and delegate to Actions. They extend base controllers provided by Domion.

For API Mode:

<?php

namespace App\Domain\Orders\Controllers;

use App\Support\Controllers\ApiControllers as Controller;

class OrderController extends Controller
{
    public function index(OrderRepository $repository)
    {
        return $this->success($repository->paginate());
    }

    public function store(CreateOrderRequest $request)
    {
        $dto = CreateOrderDto::fromRequest($request);
        $order = CreateOrderAction::run($dto);
        
        return $this->success($order, 'Order created', 201);
    }
}

For React/Vue Mode:

<?php

namespace App\Domain\Orders\Controllers;

use App\Support\Controllers\InertiaControllers as Controller;

class OrderController extends Controller
{
    public function index(OrderRepository $repository)
    {
        return $this->render('Orders/Index', [
            'orders' => $repository->paginate()
        ]);
    }
}

Available Response Methods:

🔐 Security Features

Two-Factor Authentication (2FA)

Domion integrates Laravel Fortify for 2FA. This is automatically configured during setup.

How it works:

1. User navigates to Settings → Two Factor Auth
2. Clicks Enable
3. Scans QR Code with authenticator app
4. Saves Recovery Codes
5. Future logins require OTP verification

Backend: Fortify handles all 2FA logic (/user/two-factor-authentication endpoints).

Frontend: Complete React/Vue UI is provided.

API Authentication (Sanctum)

For API mode, authentication is handled via Laravel Sanctum tokens.

// Login endpoint returns token
{
    "success": true,
    "data": {
        "token": "1|abc123...",
        "user": { ... }
    }
}

// Use token in subsequent requests
Authorization: Bearer 1|abc123...

🛠️ CLI Commands

📦 Dependencies

Domion automatically installs these packages based on your chosen mode:

🏢 Multi-tenancy Support

Domion supports multi-tenant applications via stancl/tenancy.

When enabled, domains are organized into:

• Central Domains: Shared across all tenants (e.g., Billing, Admin)
• Tenant Domains: Isolated per tenant (e.g., Projects, Orders)

php artisan domion:make:domain Billing
# > Is this a Central or Tenant domain? [Central]

🤝 Contributing

We welcome contributions! Please fork the repository and submit a pull request.

📄 License

The MIT License (MIT). Please see License File for more information.

Created with ❤️ by Sami Maxhuni