MintfitV2

Issues and merge requests

Track new work in mintfit-ecosystem issues, including changes limited to this repository. Search before creating an issue and label every affected area: api, admin, web and/or ecosystem. Keep existing issues here and link them when relevant.

Keep branches, commits and merge requests in the repository containing the changes. Link each merge request to the central issue using its full URL or mintfit2/mintfit-ecosystem#<number>. For work spanning repositories, close the issue only after all required changes are merged and acceptance criteria are met. See the central workflow.

Local development

Use the workspace guide to choose a standalone repository worktree or an ecosystem workspace. Run make init to prepare this repository, make check to check it, and make status to inspect publication and integration. Shared application services require an ecosystem workspace.

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

Workspace commands

Use local workspace commands from this checkout. Repository commands prepare dependencies and run checks independently; the ecosystem owns the application stack, ports and development data.

make init
make status
make app-test
make app-lint
make app-shell

Application operations use explicit commands in this workspace:

make app-exec COMMAND="php artisan make:module Product --type=stateful"
make app-exec COMMAND="php vendor/bin/deptrac analyse --config-file=deptrac.yaml"
make app-exec COMMAND="php vendor/bin/phpstan analyse --memory-limit=512M"
make app-exec COMMAND="php vendor/bin/pint"

To migrate development data, run make app-exec APP=api COMMAND="php artisan migrate" at the ecosystem root. Repository tool commands use isolated testing configuration.

app-lint checks formatting without modifying files, then runs Deptrac and PHPStan. app-test FILTER=Tenant selects tests by name using the same isolated settings as the full test command. app-test first downloads the pinned Moodle import fixtures (make fixtures); set MOODLE_FIXTURES=optional to run offline and skip the tests that need them. The optional versioned pre-commit hook runs app-lint; installation of shared Git hooks is an explicit repository maintenance operation, not part of a child checkout's setup.

Production image builds use this repository's Docker assets. API CI runs disposable services from docker/compose.ci.yml, with a Compose project name unique to the pipeline and job. These services publish no host ports. The job's after_script removes only that project's containers, network and volumes, including after cancellation. The local task runtime is operated only through workspace commands.

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 app-exec COMMAND="php artisan make:module Example" or follow existing patterns
4. Test your changes - Write tests, run make app-test
5. Verify quality - Run make app-lint app-test 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 app-lint app-test 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

Platform support

PLATFORM_TENANT_SLUG names the platform tenant. Run php artisan app:sync-reference-data --tenant=<platform-slug> after deploying permission changes to existing tenants. The platform admin role receives platform.support; other roles, including superadmin, need an explicit grant. A deny revokes support even for elevated roles.

Support requests name the target ID or slug in X-Act-As-Tenant. Ownership uses TenantService::actingTenantId(), while permissions and account operations use the identity's home tenant. X-Tenant-ID is only an unauthenticated tenant hint. Requests outside home write a Platform support request entry to the configured Laravel log with real identity, home and target tenant IDs, method, path and time. The Admin partner URL selects the support target and shows a persistent warning.