# Gramia Handover Document ## 1. Project overview This repository is a PHP-based education platform for schools and institutions. The main application runs from the [public](public) folder and uses a custom PHP MVC/router setup. The project includes: - Web portal for administration, academic management, student records, finance, notifications, and reports. - Public API endpoints for mobile/web clients. - Authentication and password reset flow. - Mobile update integration for Android/iOS via OTA manifest and update API. The main application entry point is [public/index.php](public/index.php), and the router/route registration is managed from [public/src/App/Router.php](public/src/App/Router.php) and the route files under [public/routes](public/routes). --- ## 2. Tech stack ### Web / backend - Language: PHP - Framework style: custom MVC pattern without a full framework - Database: MySQL / PDO - Session/auth: custom cookie-based user auth and login logic - Views: PHP view files in [public/views](public/views) - Routing: custom router in [public/src/App/Router.php](public/src/App/Router.php) - Server bootstrap: [public/index.php](public/index.php) ### Frontend - Mostly server-rendered PHP views - Bootstrap/JQuery-based UI is present in the public assets folder - Many UI interactions are generated through server-side templates and JavaScript files in [public/assets](public/assets) ### Mobile This repository does not contain a standalone native mobile app codebase (React Native, Flutter, Capacitor, Android Java/Kotlin, or iOS Swift/Xcode project). What is present instead: - OTA/mobile update metadata in [public/assets/mobile-updates/manifest.json](public/assets/mobile-updates/manifest.json) - Mobile update endpoint in [public/routes/api.php](public/routes/api.php) - App store and Play Store URLs in the manifest - App bundle update hooks for Android/iOS in the API layer This means the mobile app appears to be maintained externally, while this repo provides the backend and the mobile update mechanism. --- ## 3. Project structure ### Root - [composer.json](composer.json): Composer file for PHP dependencies - [index.php](index.php): site entry for the broader web root - [public](public): main application source - [assets](assets): CSS, JS, images, uploads, OTA update staging, other static files - [scripts](scripts): maintenance/task scripts - [storage](storage): logs and generated files - [backups](backups): old deployments and historical versions - [dev](dev): development/public copy or alternate build area ### Main application - [public/index.php](public/index.php): bootstrap and route loader - [public/routes](public/routes): all route definitions, grouped by feature - [public/src/App](public/src/App): application logic - [public/src/App/Controllers](public/src/App/Controllers): controller classes - [public/src/App/Models](public/src/App/Models): database models - [public/src/App/Helpers](public/src/App/Helpers): helper functions and config utilities - [public/views](public/views): UI templates and pages - [public/assets](public/assets): frontend assets and supporting files --- ## 4. Authentication and user flows ### Login The main login logic is in [public/src/App/Controllers/AccountController.php](public/src/App/Controllers/AccountController.php). Important notes: - The login lookup accepts email, ID number, account number, or institution-user account number. - The app resolves the matching user and checks the password hash. - It sets auth cookies and redirects users after successful login. - Failed login attempts can lock the account after a threshold. ### Password reset flow The reset flow currently uses SMS OTP logic, not email-based reset links. Relevant code: - [public/src/App/Controllers/AccountController.php](public/src/App/Controllers/AccountController.php#L466-L572) - [public/src/App/Controllers/AccountController.php](public/src/App/Controllers/AccountController.php#L594-L672) - [public/src/App/Controllers/ResetTokensController.php](public/src/App/Controllers/ResetTokensController.php) What the app does today: 1. Takes an account identifier. 2. Looks up the institution user by account number. 3. Generates a reset token / OTP. 4. Sends the token via SMS. 5. User submits OTP and a new password. 6. Password is updated and token is invalidated. This is important for handover because the reset experience is not implemented as a classic email-reset-link flow. --- ## 5. Mobile-specific notes There is no complete mobile app source here, but the backend supports mobile update checks and app distribution metadata. ### Mobile update API The endpoint is registered in [public/routes/api.php](public/routes/api.php) and exposes a check for Android and iOS updates. - Endpoint: /api/mobile-app-update - Platform accepted: android or ios - Response: latest app version, update status, app store/Play Store URLs, and optional web bundle updates ### Mobile update manifest The manifest is stored in [public/assets/mobile-updates/manifest.json](public/assets/mobile-updates/manifest.json). It contains: - current Android version metadata - current iOS version metadata - store URLs - optional force-update rules - web bundle metadata ### Mobile bundles The repository has folders like [public/assets/apk](public/assets/apk), [public/assets/ipa](public/assets/ipa), and [public/assets/mobile-updates](public/assets/mobile-updates). These appear to be distribution artifacts and update payloads rather than full source code for an app project. --- ## 6. Core application modules This codebase contains a large set of feature modules. Commonly named route groups include: - account management - institutions and institution users - students and guardians - teachers and subjects - attendance, reports, lessons, timetables - finance and invoices - communications, notices, and chat - library and ebooks - stock and purchases - payments, reconciliations, and statements Examples of route folder names: - [public/routes/account_routes.php](public/routes/account_routes.php) - [public/routes/institution_routes.php](public/routes/institution_routes.php) - [public/routes/studentreport_routes.php](public/routes/studentreport_routes.php) - [public/routes/invoice_routes.php](public/routes/invoice_routes.php) - [public/routes/notification_routes.php](public/routes/notification_routes.php) - [public/routes/finance_mobile_routes.php](public/routes/finance_mobile_routes.php) This is a broad school management platform rather than a small app. --- ## 7. Database and model pattern The project uses a model-per-table approach under [public/src/App/Models](public/src/App/Models). Most models extend a generic base model and expose CRUD helpers. Typical patterns: - model with a table name - query helpers - page/list results - findByQuery calls for custom SQL - controller methods call the models and then render or return JSON Examples: - [public/src/App/Models/ResetToken.php](public/src/App/Models/ResetToken.php) - [public/src/App/Models/User.php](public/src/App/Models/User.php) - [public/src/App/Models/Institution_user.php](public/src/App/Models/Institution_user.php) --- ## 8. Configuration and environment The project relies on environment variables and app-level config setup. The main bootstrap in [public/index.php](public/index.php) sets: - site URL - asset URL - site name - default email - debug mode - database connection values via app config The site configuration helper is in [public/src/App/Helpers/SiteConfig.php](public/src/App/Helpers/SiteConfig.php). Important handover note: - There is no obvious central .env file in the main app root shown in this workspace snapshot. - Configuration appears to be environment-driven or embedded in bootstrap logic. - Any deployment handover should confirm the real environment variables used in production. --- ## 9. Recommended handover checklist ### Before handover - Confirm the production database credentials and host - Confirm the public domain and base URL configuration - Confirm the actual mobile app repository or external maintainer for Android/iOS - Verify email and SMS service credentials - Check whether the reset OTP is expected to stay SMS-based or be migrated to email-based links - Review any cron/task scripts in [scripts](scripts) - Test the login and reset flow against the real database - Confirm access to hosting and deployment scripts ### Operational notes - This repo is not a full mobile app source tree. - The mobile app seems to be externally maintained, while this repo serves the backend and update contract. - The web platform is the primary codebase and is much more complete than the mobile update integration. --- ## 10. Known handover risk areas These are the most important areas for a new maintainer to review quickly: 1. Authentication and reset flow in [public/src/App/Controllers/AccountController.php](public/src/App/Controllers/AccountController.php) 2. Route registration and auth middleware in [public/src/App/Router.php](public/src/App/Router.php) 3. Database model conventions and query behavior in [public/src/App/Models](public/src/App/Models) 4. Mobile update compatibility in [public/routes/api.php](public/routes/api.php) and [public/assets/mobile-updates/manifest.json](public/assets/mobile-updates/manifest.json) 5. Deployment config and environment variables used by the live app --- ## 11. Summary This project is a large PHP-based school management platform with a custom web app architecture and a backend/mobile update layer. The main business logic and user flows live in the PHP application under [public](public), while mobile support is limited to OTA update metadata and app-store integration rather than a native source tree. For a new handover engineer, the most important starting points are: - [public/index.php](public/index.php) - [public/routes](public/routes) - [public/src/App/Router.php](public/src/App/Router.php) - [public/src/App/Controllers/AccountController.php](public/src/App/Controllers/AccountController.php) - [public/src/App/Controllers/ResetTokensController.php](public/src/App/Controllers/ResetTokensController.php) - [public/assets/mobile-updates/manifest.json](public/assets/mobile-updates/manifest.json) This file should be updated as the project evolves during maintenance.