MintfitV2

A modern Learning Management System (LMS) built as a modular monolith with Laravel 12. Designed to replace Moodle with a flexible, API-driven architecture that maintains microservice-style boundaries while keeping deployment simple.

Key Features

• API-Only Backend - Stateless JWT authentication, JSON responses
• Modular Monolith - Self-contained modules with strict boundaries enforced by Deptrac
• Docker-Based - Complete development environment with one command
• Anonymous Sessions - Guest users can interact before registration
• Multi-Tenancy - Built-in tenant isolation
• RBAC - Role-based access control with flexible permission system

Architecture

Each module is a self-contained domain with clean separation:

modules/{ModuleName}/
├── Domain/           # Entities, DTOs, value objects
├── Application/      # Services (public API), use cases
└── Infrastructure/   # Repositories, controllers, models

Module Communication: Modules interact only via Service injection. Services return DTOs, never models.

Current Modules: Health, Tenant, Identity, User, Block, Notification, Dashboard

Quick Start

# Complete setup (first time)
make setup

# Start development environment
make start

Services:

• Dashboard: http://localhost:8000 (System monitoring & health)
• API Docs: http://localhost:8000/docs
• phpMyAdmin: http://localhost:8080 (Database management)
• Mailpit: http://localhost:8025 (Email testing)

Common Commands

# Development
make start              # Start all services
make logs               # View application logs
make shell              # Open shell in container

# Database
make db-migrate         # Run migrations
make db-seed            # Seed database
make db-reset           # Fresh database with seeds

# Testing & Quality
make test               # Run all tests
make analyze            # Run all checks (tests, pint, deptrac, phpstan)
make pint               # Format code
make deptrac            # Check module boundaries

# Modules
make module NAME=Product TYPE=stateful    # Generate new module
make module-test MODULE=Tenant            # Test specific module
make module-migrate MODULE=Tenant         # Migrate specific module

# View all commands
make help

Creating a New Module

# Interactive mode (recommended)
make module NAME=Product

# With options
make module NAME=Order TYPE=stateful WITH_EVENTS=1 WITH_TESTS=1

The generator creates:

• Complete module structure (Domain, Application, Infrastructure)
• DTOs with validation rules
• Service with CRUD operations
• Repository and Model
• Controller and routes
• Migration and seeder
• Tests (Feature and Unit)
• Permission provider (stateful modules)

After generation:

1. Customize DTOs and validation rules
2. Update migration schema
3. Configure permissions in config/module_rbac.php
4. Run make module-migrate MODULE=YourModule
5. Run make module-test MODULE=YourModule

Git Hooks

Pre-commit hooks enforce code quality automatically before each commit:

• Laravel Pint - Enforces PSR-12 code style
• Deptrac - Validates module boundaries
• PHPStan - Static analysis (level 5)

Installation:

make install-hooks

The hooks are stored in .githooks/ and symlinked to .git/hooks/. If any check fails, the commit is blocked.

Bypass (not recommended):

git commit --no-verify

See .githooks/README.md for more details.

Documentation

• CLAUDE.md - Complete project documentation (architecture, patterns, commands)
• CONTRIBUTING.md - Module system rules and conventions
• API Documentation - Auto-generated, view at /docs endpoint

Technology Stack

• Framework: Laravel 12 (PHP 8.2+)
• Database: MariaDB 11
• Cache/Queues: Redis
• Authentication: JWT (stateless)
• Frontend: Tailwind CSS 4, Vite
• Testing: PHPUnit with SQLite
• API Docs: Scribe
• Architecture Enforcement: Deptrac, PHPStan

Development Workflow

1. Understand the architecture - Read CONTRIBUTING.md
2. Explore existing modules - Look at Health, Tenant, or Block for patterns
3. Create or modify modules - Use make module or follow existing patterns
4. Test your changes - Write tests, run make test
5. Verify quality - Run make analyze before committing

Architecture Enforcement

Deptrac enforces module boundaries:

• Modules can ONLY access other modules via Services
• No direct access to Repositories, Models, or Infrastructure
• Layered architecture: Domain → Application → Infrastructure

PHPStan ensures type safety and catches bugs before runtime.

Run make analyze to verify both.

Important Notes

• This is NOT standard Laravel - Strict module boundaries enforced
• All authentication is stateless JWT (no sessions)
• Services are the public API for modules
• Always return DTOs from Services, never models
• Use ULIDs for primary keys (via HasUlids trait)
• API-only - No Blade views or traditional forms (except Dashboard module for internal monitoring)

License

Proprietary - All rights reserved