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)

The default local runtime uses FrankenPHP with two Laravel workers, matching the Kubernetes worker setting without scaling to the host CPU count. MariaDB 11.8, Valkey 9.1, Garage 2.3.0, Mailpit 1.30.4 and the Chromium image match the Fleet setup. Default, PDF and import queues run in separate containers with their production timeout and recycling policies. Use make start OCTANE=0 only when testing the PHP-FPM fallback. If a default host port is occupied, set APP_PORT or PHPMYADMIN_PORT in .env; container-to-container ports do not change.

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.8
• Cache/Queues: Valkey 9.1 using the Redis protocol
• 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