Why an AI Contract Guide?
Domain-System is architected to work seamlessly with AI coding assistants (Gemini, Claude, ChatGPT, Copilot, Cursor). To ensure AI-generated code strictly respects our SOLID and Clean Architecture boundaries, every extension follows explicit interface contracts.
1. Non-Negotiable Architectural Rules
- Zero Superglobals in Controllers: Never access
$_GET,$_POST,$_SESSION,$_FILES, or$_SERVERdirectly inside Controllers. Always use constructor-injectedRequest($request->input(),$request->json()) andSessionManagerInterface(enforced byNoSuperglobalsInControllersTest). - Dependency Inversion (DIP): Services and Controllers depend strictly on interfaces under
Contracts/, never on concrete PDO repositories or raw external HTTP clients. - Ring Isolation (Ring 0 vs. Ring 3): Plugins in
src/Plugins/(Ring 3) interact with the Kernel (Ring 0) exclusively viaOsExtensionInterface(osRegisterandosBoot) and hooks. - Database-Agnostic SQL (MySQL & SQLite): PDO repositories must use standard SQL compatible with both MySQL/MariaDB (production) and in-memory SQLite (PHPUnit test suite).
2. CLI Boilerplate Generator
To scaffold a compliant plugin structure automatically, run:
php os-cli.php make:plugin my_plugin
This generates plugin.json (version 2.7.0 / os_version: 2.7), Plugin.php implementing OsExtensionInterface, and the auto-discovered manual module manual/module.php (ManualModuleInterface).
3. Standard Plugin Directory Tree
src/Plugins/my_plugin/
βββ plugin.json
βββ Plugin.php
βββ Contracts/
β βββ MyRepositoryInterface.php
βββ Repositories/
β βββ PdoMyRepository.php
βββ Services/
β βββ MyService.php
βββ Controllers/
β βββ MyController.php
βββ manual/
β βββ module.php
βββ views/
βββ admin/
βββ front/
4. Automated Verification
Before deploying any AI-assisted change, run the architecture and unit test suites:
php phpunit.phar tests/Architecture
php phpunit.phar