update project

README.md

@@ -1,93 +1,289 @@
-# laravel_school_api
+# Laravel SchoolContext Phase 1 Implementation
 
+This package-style scaffold implements Phase 1 of the SchoolContext foundation for a Laravel app.
 
+It includes:
 
-## Getting started
+- immutable `SchoolContext` value object;
+- context factory, resolver, validator, store, and exception;
+- `ResolveSchoolContext` middleware;
+- service provider bindings;
+- helper for legacy adapters only;
+- query scoping trait;
+- first student read/list slice;
+- payment-file access slice that resolves files through payment context, not arbitrary filenames;
+- context payload helper for jobs/events;
+- unit, feature, and architecture tests.
 
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+## Install into an existing Laravel app
 
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+Copy the `app`, `config`, `routes`, and `tests` folders into your Laravel project.
 
-## Add your files
+Register the provider in `config/app.php` if your Laravel version does not auto-discover app providers:
 
-* [Create](https://docs.gitlab.com/user/project/repository/web_editor/#create-a-file) or [upload](https://docs.gitlab.com/user/project/repository/web_editor/#upload-a-file) files
-* [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
-
-```
-cd existing_repo
-git remote add origin https://gitlab.rentaldrivego.ma/alrahma_school/laravel_school_api.git
-git branch -M main
-git push -uf origin main
+```php
+App\Providers\SchoolContextServiceProvider::class,
 ```
 
-## Integrate with your tools
+For Laravel 10 and older, you may also register the middleware alias in `app/Http/Kernel.php`:
 
-* [Set up project integrations](https://gitlab.rentaldrivego.ma/alrahma_school/laravel_school_api/-/settings/integrations)
+```php
+protected $middlewareAliases = [
+    'school.context' => \App\Http\Middleware\ResolveSchoolContext::class,
+];
+```
 
-## Collaborate with your team
+For Laravel 11+, register it in `bootstrap/app.php`:
 
-* [Invite team members and collaborators](https://docs.gitlab.com/user/project/members/)
-* [Create a new merge request](https://docs.gitlab.com/user/project/merge_requests/creating_merge_requests/)
-* [Automatically close issues from merge requests](https://docs.gitlab.com/user/project/issues/managing_issues/#closing-issues-automatically)
-* [Enable merge request approvals](https://docs.gitlab.com/user/project/merge_requests/approvals/)
-* [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
+```php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->alias([
+        'school.context' => \App\Http\Middleware\ResolveSchoolContext::class,
+    ]);
+})
+```
 
-## Test and Deploy
+Load the example routes only after adapting controllers/model names to your app:
 
-Use the built-in continuous integration in GitLab.
+```php
+require base_path('routes/school_context_examples.php');
+```
 
-* [Get started with GitLab CI/CD](https://docs.gitlab.com/ci/quick_start/)
-* [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/user/application_security/sast/)
-* [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/topics/autodevops/requirements/)
-* [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/user/clusters/agent/)
-* [Set up protected environments](https://docs.gitlab.com/ci/environments/protected_environments/)
+## Required model assumptions
 
-***
+This scaffold expects these model concepts to exist or be adapted:
 
-# Editing this README
+- `App\Models\School` with optional `timezone`, `locale`, `currency`, `domain_profile`, `active` fields.
+- `App\Models\Configuration::getConfig($key)` during migration only.
+- `App\Models\Student` with `school_id`.
+- `App\Models\Payment` with `school_id` and a `files()` relationship.
+- user model with `school_id`, optional `role_id`, optional `roles()`, optional `schools()`, optional `is_platform_admin`.
 
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
+## Migration policy
 
-## Suggestions for a good README
+New SchoolCore services should accept `SchoolContext` explicitly. Do not call `auth()`, `request()`, or `Configuration::getConfig()` inside SchoolCore services. The architecture test exists to catch that predictable human shortcut.
 
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+## Route middleware order
 
-## Name
-Choose a self-explaining name for your project.
+Use this order:
 
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+```txt
+auth:api
+school.context
+permission/policy/controller
+```
 
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+Do not run `school.context` before authentication for protected routes.
 
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+## Important note
 
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+`SchoolContext::isIslamicSundaySchool()` exists as a convenience check, but SchoolCore should not branch into Islamic-specific concepts. Domain-specific behavior belongs in policies, bindings, labels, calendars, and extension providers.
 
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
 
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+# Phase 2 Add-on: Core Contracts and Module Boundaries
 
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
+This scaffold now includes the Phase 2 contract layer:
 
-## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
+- neutral `SchoolCore` contracts for students, guardians, enrollment, attendance, academics, finance, files, communication, and reporting;
+- immutable DTO/read-model skeletons for cross-module payloads;
+- `SchoolCoreServiceProvider` with default core bindings;
+- `IslamicSundaySchoolServiceProvider` with extension policy/provider overrides;
+- race-safe student identifier generation through `StudentIdentifierGeneratorContract`;
+- payment file access through `FileAccessPolicyContract` and `FileStorageServiceContract`;
+- attendance policy and academic calendar provider stubs;
+- architecture tests for forbidden dependency direction, raw request leakage, `auth()` leakage, and non-neutral contract vocabulary;
+- a migration stub for `unique(school_id, school_id_number)`.
 
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+## Register Phase 2 providers
 
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+Add these after `SchoolContextServiceProvider`:
 
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
+```php
+App\Providers\SchoolCoreServiceProvider::class,
+App\Providers\IslamicSundaySchoolServiceProvider::class,
+```
 
-## License
-For open source projects, say how it is licensed.
+Enable the extension policy overrides only when the school profile requires them:
 
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+```env
+ISLAMIC_SUNDAY_SCHOOL_EXTENSION_ENABLED=true
+```
+
+## Student identifier slice
+
+`StudentService` creates the student row first, then calls `StudentIdentifierGeneratorContract` with the persisted ID. This avoids the classic `max(id) + 1` race. The migration stub adds a database unique constraint, because relying on application code alone for uniqueness is how duplicates sneak in wearing a fake mustache.
+
+## Payment file access slice
+
+Use payment IDs and stored file references. Do not serve files by guessed filename. The policy checks school context first, then role/relationship metadata. Adapt relationship metadata to your actual finance schema.
+
+## Attendance policy stub
+
+Core scanner logic should call `AttendancePolicyContract` and `AcademicCalendarProviderContract`. The extension provider supplies domain-specific attendance behavior without making `SchoolCore` speak extension vocabulary.
+
+
+## Phase 3: Modular Finance Extraction
+
+Phase 3 adds a reusable `SchoolCore\Finance` module. The core owns financial correctness: invoices, payments, refunds, payment files, audit events, balance calculation, idempotency, and transaction boundaries. Islamic Sunday School behavior is extension-owned through finance policies and reports.
+
+Register these providers after the Phase 1/2 providers:
+
+```php
+App\Providers\SchoolCoreFinanceServiceProvider::class,
+App\Domain\IslamicSundaySchool\Finance\Providers\IslamicSundaySchoolFinanceServiceProvider::class,
+```
+
+Add `routes/finance_phase3.php` to your route loader, then migrate one vertical slice at a time. Start with payment-file access, then payment recording, payment editing, invoice recalculation, refunds/reversals, and only then reports. Reports consume finance truth. They do not invent it, despite humanity's long-running spreadsheet addiction.
+
+Important integration notes:
+
+- Finance services require `SchoolContext`.
+- Finance mutation services use `FinanceTransactionRunner`.
+- Payment files are downloaded by payment ID, never by arbitrary filename.
+- `Money` stores integer minor units and rejects float math.
+- `finance_audit_logs` are append-only.
+- Existing legacy finance methods should be labeled `canonical`, `adapter`, `deprecated`, or `remove` before migration continues.
+
+
+## Phase 4: Modular Attendance and Scanner Extraction
+
+Phase 4 adds `SchoolCore\\Attendance` as the neutral attendance/scanner module. It includes scanner delegation, school-scoped badge lookup, scan idempotency, student/staff attendance services, session resolution, status policies, audit logging, migrations, HTTP requests/controllers, route examples, provider bindings, and Islamic Sunday School extension overrides.
+
+Register these providers after the base SchoolCore providers:
+
+```php
+App\\Providers\\SchoolCoreAttendanceServiceProvider::class,
+App\\Domain\\IslamicSundaySchool\\Attendance\\Providers\\IslamicSundaySchoolAttendanceServiceProvider::class, // only for the Islamic Sunday School profile/app
+```
+
+Load the example routes from `routes/attendance_phase4.php` or merge them into your API route file. Keep legacy scanner endpoints as adapters only until compatibility tests pass. Controllers should delegate to `ScannerServiceContract`, not recreate attendance logic in private methods.
+
+
+## Phase 5: Modular Student Lifecycle Extraction
+
+Phase 5 adds a neutral `SchoolCore\Students` lifecycle module for race-safe identifiers, student creation/update/status transitions, guardians, households, enrollment, assignments, promotion, read models, audit logging, and Islamic Sunday School profile extension points.
+
+Core student lifecycle stays reusable: no Qur'an, Arabic, Islamic studies, halaqa, masjid/community, or sensitive religious/community note fields belong in `SchoolCore\Students`. Those live in `App\Domain\IslamicSundaySchool\Students`. The point is not aesthetic purity; it is avoiding a global student model that secretly belongs to one domain and then acts innocent.
+
+Register:
+
+```php
+App\Providers\SchoolCoreStudentServiceProvider::class,
+App\Domain\IslamicSundaySchool\Students\Providers\IslamicSundaySchoolStudentServiceProvider::class,
+```
+
+Example routes: `routes/student_lifecycle_phase5.php`.
+
+
+## Phase 6: Modular Communication Extraction
+
+Phase 6 adds `SchoolCore\Communication` as the neutral communication engine. Bulk communication now uses a preview-first path: resolve recipients, dedupe, apply preferences, store a snapshot, confirm with a token, then send through channel contracts. This prevents accidental mass sends, duplicate deliveries, and cross-school recipient leakage.
+
+Register:
+
+```php
+App\Providers\SchoolCoreCommunicationServiceProvider::class,
+App\Domain\IslamicSundaySchool\Communication\Providers\IslamicSundaySchoolCommunicationServiceProvider::class,
+```
+
+Routes are in `routes/communication_phase6.php`. Include them only after authentication and `ResolveSchoolContext` are active.
+
+Key rules: bulk sends require `preview_id` and `confirmation_token`; recipient queries live in resolvers, not controllers; email/SMS/WhatsApp/notification delivery lives behind channel contracts; Islamic Sunday School recipient behavior is extension-owned.
+
+
+## Phase 7: Modular Reporting Extraction
+
+Phase 7 adds `SchoolCore\Reporting` as the reporting boundary. Reports are read-only, require `SchoolContext`, and must consume read models instead of inventing finance, attendance, communication, or student lifecycle truth with ad hoc queries.
+
+Added provider:
+
+```php
+App\Providers\SchoolCoreReportingServiceProvider::class,
+App\Domain\IslamicSundaySchool\Reporting\Providers\IslamicSundaySchoolReportingServiceProvider::class,
+```
+
+Added route file:
+
+```php
+require base_path('routes/reporting_phase7.php');
+```
+
+The core reporting registry supports tagged report definitions using `schoolcore.reports`. Islamic Sunday School reports register through the extension provider and are only available when the context domain profile is `islamic_sunday_school`.
+
+Phase 7 deliberately treats exports as controlled access, not a casual CSV vending machine. Export paths go through `ReportExportServiceContract`, audit hooks exist, snapshots are school-scoped, and architecture tests prevent `SchoolCore\Reporting` from importing extension classes.
+
+
+## Phase 8: Controller and API Cleanup
+
+Phase 8 adds the HTTP cleanup layer:
+
+- v2 route file: `routes/api_phase8.php`
+- standardized API response envelope: `App\Support\Api\ApiResponse`
+- centralized exception rendering helper: `App\Support\Api\ApiExceptionRenderer`
+- domain-profile middleware: `EnsureDomainProfile`
+- deprecation header middleware: `DeprecationHeaders`
+- route inventory generator: `php artisan api:route-inventory --markdown`
+- controller classification map: `config/api_controller_classification.php`
+- OpenAPI baseline: `docs/openapi.phase8.yaml`
+- route inventory docs: `docs/api-route-inventory.md`
+- v2 canonical controllers for finance, attendance, students, communication, reporting, and Islamic Sunday School extension routes
+- architecture tests blocking raw DB/provider/controller business logic patterns
+
+Phase 8 does not erase legacy routes. It creates canonical v2 delivery adapters and gives old routes a sane path to become adapters or deprecated endpoints. Because breaking clients for “architecture” is still breaking clients, just with nicer folder names.
+
+
+## Phase 9: Boundary Enforcement and Modular Governance
+
+Phase 9 adds enforceable modular governance on top of the Phase 1-8 scaffold.
+
+Installed governance pieces:
+
+- `app:architecture-scan` artisan command for forbidden imports, HTTP leakage, controller/provider calls, finance float usage, unsafe file routes, extension vocabulary, and critical modular rules.
+- `app:dependency-map` command for dependency map artifacts.
+- `app:route-inventory-check` command for route inventory governance.
+- `app:docs-coverage` command for route/OpenAPI/deprecation coverage checks.
+- `tests/Architecture/*BoundaryTest.php` suites for module, controller, service, finance, attendance, student, communication, reporting, Islamic Sunday School, route inventory, and deprecation rules.
+- `.github/CODEOWNERS`, PR checklist, architecture workflow, and release gate workflow.
+- `docs/architecture/*`, `docs/modules/*`, `docs/deprecations.md`, and `docs/release-checklist.md`.
+
+Recommended rollout:
+
+```bash
+php artisan app:architecture-scan --fail-on=none
+php artisan test tests/Architecture
+php artisan api:route-inventory --markdown
+php artisan app:route-inventory-check
+php artisan app:dependency-map --markdown
+php artisan app:docs-coverage
+```
+
+Start in warning mode for existing legacy code. Critical new violations should fail immediately. Letting legacy code break every build on day one is not governance; it is a morale experiment with predictable results.
+
+
+## Phase 10: Migration, Release, and Production Readiness
+
+Phase 10 adds production rollout governance for the modular platform:
+
+- feature flag rollout map
+- migration validation commands
+- shadow comparison scaffolding
+- release readiness gate
+- rollback playbooks
+- monitoring and alerting docs
+- security/performance readiness checklists
+- UAT scenarios
+- support playbooks
+- pilot and Islamic Sunday School production rollout plans
+- legacy unsafe route audit
+
+Useful commands:
+
+```bash
+php artisan app:release-feature-flags
+php artisan app:release-migration-validate
+php artisan app:release-shadow-compare
+php artisan app:legacy-unsafe-route-audit
+php artisan app:release-readiness-gate --warning-mode
+```
+
+Phase 10 is not a magic permission slip to ship everything. It is the checklist that stops the team from discovering rollback strategy during an incident, which is traditionally when everyone becomes philosophical and useless.