laravel_school_api/config/architecture_governance.php

<?php declare(strict_types=1);

return [
    'mode' => env('ARCHITECTURE_GOVERNANCE_MODE', 'warning'),
    'controller_thresholds' => [
        'max_class_lines' => 250,
        'max_action_lines' => 40,
        'private_methods' => 'discouraged',
    ],
    'service_context_required_modules' => [
        'app/Domain/SchoolCore/Finance/Services',
        'app/Domain/SchoolCore/Attendance/Services',
        'app/Domain/SchoolCore/Students/Services',
        'app/Domain/SchoolCore/Communication/Services',
        'app/Domain/SchoolCore/Reporting/Services',
        'app/Domain/IslamicSundaySchool',
    ],
    'rules' => [
        [
            'id' => 'ARCH-001',
            'description' => 'SchoolCore must not import IslamicSundaySchool.',
            'severity' => 'error',
            'paths' => ['app/Domain/SchoolCore'],
            'patterns' => ['App\\\\Domain\\\\IslamicSundaySchool', 'IslamicSundaySchool\\\\'],
            'message' => 'SchoolCore references IslamicSundaySchool. Extension dependencies only go the other direction.',
            'suggested_fix' => 'Move behavior behind a SchoolCore contract and bind the IslamicSundaySchool implementation in an extension provider.',
        ],
        [
            'id' => 'ARCH-002',
            'description' => 'Domain services must not use HTTP/global request state.',
            'severity' => 'error',
            'paths' => ['app/Domain'],
            'patterns' => ['Illuminate\\\\Http\\\\Request', '\bauth\s*\(', '\brequest\s*\(', '\bsession\s*\(', '\$_GET', '\$_POST', '\$_SERVER'],
            'message' => 'Domain code is reading HTTP/global state directly.',
            'suggested_fix' => 'Pass SchoolContext and validated DTOs from the controller/application layer.',
        ],
        [
            'id' => 'ARCH-003',
            'description' => 'Controllers must not perform domain DB mutations.',
            'severity' => 'warning',
            'paths' => ['app/Http/Controllers'],
            'patterns' => ['DB::table', '->update\s*\(', '->delete\s*\(', '::query\s*\(\)->update'],
            'message' => 'Controller appears to perform direct persistence logic.',
            'suggested_fix' => 'Move mutation into a domain service contract.',
        ],
        [
            'id' => 'ARCH-004',
            'description' => 'Controllers must not call external providers directly.',
            'severity' => 'error',
            'paths' => ['app/Http/Controllers'],
            'patterns' => ['Mail::', 'Notification::send', 'Twilio', 'WhatsApp', 'Vonage', 'Nexmo'],
            'message' => 'Controller calls a provider directly.',
            'suggested_fix' => 'Use Communication channel contracts/adapters.',
        ],
        [
            'id' => 'ARCH-005',
            'description' => 'Core contracts must not contain extension vocabulary.',
            'severity' => 'error',
            'paths' => ['app/Domain/SchoolCore'],
            'patterns' => ['Islamic', 'Quran', "Qur'an", 'ArabicLevel', 'Halaqa', 'Masjid', 'Imam', 'Sadaqah', 'Zakat', 'SundaySchool'],
            'message' => 'Extension vocabulary leaked into SchoolCore.',
            'suggested_fix' => 'Move the term into IslamicSundaySchool extension code or neutralize the core contract name.',
            'exclude_paths' => ['README.md'],
        ],
        [
            'id' => 'FIN-001',
            'description' => 'Finance module must not use float math.',
            'severity' => 'error',
            'paths' => ['app/Domain/SchoolCore/Finance'],
            'patterns' => ['\(float\)', 'floatval\s*\('],
            'message' => 'Finance code uses float math.',
            'suggested_fix' => 'Use Money or integer minor units.',
        ],
        [
            'id' => 'FIN-002',
            'description' => 'Payment files must not be served by filename-only route.',
            'severity' => 'error',
            'paths' => ['routes', 'app/Http/Controllers'],
            'patterns' => ['payment.*\{filename\}', 'serveCheckFile\s*\(\$filename', 'response\(\)->download'],
            'message' => 'Possible unsafe filename-based payment file access.',
            'suggested_fix' => 'Route through FinanceFileServiceContract using payment ID or file ID.',
        ],
        [
            'id' => 'STU-001',
            'description' => 'Student identifier must not use max(id)+1.',
            'severity' => 'error',
            'paths' => ['app'],
            'patterns' => ['max\s*\(\s*[\'\"]id[\'\"]\s*\)', 'MAX\(id\)'],
            'message' => 'Potential unsafe max(id)+1 identifier generation.',
            'suggested_fix' => 'Generate identifiers after insert through StudentIdentifierGeneratorContract and enforce a unique constraint.',
        ],
        [
            'id' => 'COM-001',
            'description' => 'Bulk sends must require preview.',
            'severity' => 'error',
            'paths' => ['app/Http/Controllers', 'routes'],
            'patterns' => ['bulk.*send.*without.*preview', 'sendBulkMessage\s*\([^;]*new\s+BulkSendMessageData'],
            'message' => 'Bulk send path may bypass recipient preview.',
            'suggested_fix' => 'Require RecipientPreviewServiceContract preview_id and confirmation_token.',
        ],
        [
            'id' => 'REP-001',
            'description' => 'Report exports must be audited.',
            'severity' => 'warning',
            'paths' => ['app/Domain/SchoolCore/Reporting', 'app/Http/Controllers/Api/V2/Reporting'],
            'patterns' => ['export\s*\(', 'ReportExport'],
            'message' => 'Report export path should be reviewed for authorization and audit logging.',
            'suggested_fix' => 'Use ReportExportServiceContract and ReportAuditLoggerContract.',
        ],
        [
            'id' => 'EXT-001',
            'description' => 'Islamic extension routes require domain profile middleware.',
            'severity' => 'error',
            'paths' => ['routes'],
            'patterns' => ['islamic-sunday-school'],
            'message' => 'Islamic Sunday School route must include ensure.domain.profile middleware.',
            'suggested_fix' => 'Add ensure.domain.profile:islamic_sunday_school to the route group.',
        ],
    ],
];