laravel-modular-monolith-starter — Laravel Starter Template

SHA-256: c43d8c31247ede698dc27e2eec6e7e091d4b2c7d51d50b952fa85458a0c69c75

2026-10-02T14:38:19.866Z

# Modulith — Laravel Modular Monolith Starter

[![CI](https://github.com/Sharps-M/laravel-modular-monolith-starter/actions/workflows/ci.yml/badge.svg)](https://github.com/Sharps-M/laravel-modular-monolith-starter/actions/workflows/ci.yml)
![PHP](https://img.shields.io/badge/PHP-8.3%2B-777bb4)
![Laravel](https://img.shields.io/badge/Laravel-12-ff2d20)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Modulith** is a production-minded **Laravel 12 starter for modular monoliths**: each business
domain lives in its own self-contained module with explicit layers (Domain,
Application, Infrastructure, UI), while authentication, role-based access
control, auditing and the UI shell are shared by every module.

It is the extracted, generic core of internal management platforms I build and
maintain. Add a domain by copying a reference module and enabling it in config:
no changes to the core.

![Users list](docs/screenshots/usuarios.png)

> The UI and the in-depth technical docs ([`docs/`](docs/README.md)) are in
> Spanish, the language of the platforms this base was built for. Code
> identifiers follow the same convention.

---

## Highlights

- **Convention-based module loader.** `ModuleServiceProvider` boots every
  module listed in `config/modules.php` and wires its routes, migrations,
  namespaced views, translations, config and its own service provider.
- **Layered modules with enforced boundaries.** An architecture test fails the
  build if a Domain class imports Infrastructure, UI, HTTP or facades.
- **Repository contracts in the domain, Eloquent in infrastructure**, bound per
  module, so controllers never depend on the ORM.
- **RBAC with Spatie Permission.** Permissions are namespaced per module
  (`gestion.usuarios.administrar`); a `Super Administrador` role gets full
  access through `Gate::before`.
- **Privilege-escalation guards.** Only a super admin can grant the super admin
  role or edit another super admin; assignable roles are validated against the
  module's catalog.
- **Hardened authentication.** No public sign-up, disabled accounts cannot log
  in, login is rate-limited, and password reset never reveals whether an
  account exists.
- **Audit trail.** Role changes are stored (who, whom, before/after) and every
  outgoing email is logged to a dedicated channel.
- **Replaceable branding.** Name from `APP_NAME`, logo from one Blade partial,
  colors from CSS design tokens, with light and dark themes.
- **Dockerized** (PHP 8.3-FPM, Nginx, MariaDB) and **CI on every push**: Pint,
  PHPUnit on PHP 8.3/8.4, Vite build and Docker image build.

## Architecture

```
app/                    Shared kernel: auth, users, feedback, auditing, mail
modules/
├── Gestion/            Users & roles administration (enabled)
│   ├── Domain/            Repositories (contracts)
│   ├── Infrastructure/    Eloquent repositories, config, service provider
│   ├── UI/                Controllers, form requests, routes, Blade views
│   └── Tests/             Feature tests, auto-discovered by PHPUnit
└── Skeleton_referencia/ Reference module to copy when adding a new domain
```

Dependencies only point inward:

```
UI  ──►  Application  ──►  Domain  ◄──  Infrastructure
```

Enabling a module is one line:

```php
// config/modules.php
'enabled' => [
    'Gestion',
    'Inventory', // copied from modules/Skeleton_referencia
],
```

The reasoning behind each design choice is recorded in
[`docs/decisiones.md`](docs/decisiones.md).

## Tech stack

| Layer | Technology |
|-------|------------|
| Backend | PHP 8.3, Laravel 12, Spatie Permission 6 |
| Database | MariaDB 11.4 (SQLite in-memory for tests) |
| Frontend | Blade, Bootstrap 5.3, Tailwind 3 (`tw-` prefix), Vite 6 |
| Infrastructure | Docker Compose: PHP-FPM, Nginx 1.27, MariaDB |
| Quality | PHPUnit 11, Laravel Pint, GitHub Actions |

## Getting started

Requirements: Docker and Docker Compose.

```bash
git clone https://github.com/Sharps-M/laravel-modular-monolith-starter.git
cd laravel-modular-monolith-starter
cp .env.example .env

docker compose up -d --build
docker compose exec app composer install
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate --seed

npm install && npm run build
```

Open <http://localhost:8080>. The seeder creates a super admin using
`SEED_ADMIN_EMAIL` / `SEED_ADMIN_PASSWORD` from `.env`; if the password is left
empty, a random one is generated and printed once.

### Running the tests

```bash
docker compose exec app php artisan test
docker compose exec app vendor/bin/pint --test
```

## Adding a module

1. Copy `modules/Skeleton_referencia/` to `modules/YourModule/` and rename the
   namespaces.
2. Add `'YourModule'` to `enabled` in `config/modules.php`.
3. Put routes in `UI/Http/routes.php`, views in `UI/Views/` (available as
   `view('your_module::...')`), migrations in
   `Infrastructure/Database/Migrations/` and tests in `Tests/`.
4. Declare the module's permissions in `RolesPermisosSeeder` and protect its
   routes with `can:`.

Full guide (in Spanish): [`modules/README.md`](modules/README.md) and
[`docs/nuevo-proyecto.md`](docs/nuevo-proyecto.md).

## Screenshots

| Sign in | New user | Dark theme |
|---------|----------|------------|
| ![Sign in](docs/screenshots/login.png) | ![New user](docs/screenshots/crear.png) | ![Dark theme](docs/screenshots/usuarios-dark.png) |

## Documentation

| Document | Contents |
|----------|----------|
| [`docs/decisiones.md`](docs/decisiones.md) | Architecture decision record and AI-assisted development rules |
| [`docs/despliegue.md`](docs/despliegue.md) | Deployment and infrastructure guide |
| [`docs/guidelines/`](docs/guidelines) | Per-subsystem guidelines: base app, users module, visual identity, email |
| [`modules/README.md`](modules/README.md) | How the module system works |
| [`CHANGELOG.md`](CHANGELOG.md) | Release history |

## License

[MIT](LICENSE)