### Local Setup Commands for Laravel Tenancy SMS (Bash)

Source: https://github.com/rayusamboy/laravel_tenancy_sms/blob/main/README.md

These commands clone the repository, install PHP and JS dependencies, build assets, generate keys, link storage, run migrations with seeding, and start the local server. Requires Composer, NPM, PHP, and a database setup. Serves the app at http://localhost:8000; limitations include non-tenancy seeder usage and manual database configuration.

```bash
# 1. Clone repository
git clone https://github.com/rayusamBoy/Laravel_tenancy_sms.git

# 2. Navigate into project
cd Laravel_tenancy_sms

# 3. Install PHP dependencies
composer install

# 4. Install JS dependencies
npm install

# 5. Build frontend assets
npm run build

# 6. Prepare database
php artisan key:generate
php artisan storage:link
php artisan migrate --seed --seeder=DatabaseSeederNonTenancy

# 7. Serve locally
php artisan serve
```

--------------------------------

### Clone and Install Laravel Tenancy SMS Project

Source: https://github.com/rayusamboy/laravel_tenancy_sms/blob/main/README.md

Commands to clone the repository and install dependencies. Includes steps for Composer and NPM package installation along with initial project setup.

```bash
git clone https://github.com/rayusamBoy/Laravel_tenancy_sms.git
```

```bash
cd Laravel_tenancy_sms
```

```bash
composer install
```

```bash
npm install
```

```bash
npm run build
```

--------------------------------

### Start Application Services

Source: https://github.com/rayusamboy/laravel_tenancy_sms/blob/main/README.md

Commands to start the Laravel application server and Reverb broadcasting service. Essential for running the application in development mode.

```bash
php artisan serve
```

```bash
php artisan reverb:start
```

--------------------------------

### Google Analytics Integration - Laravel Setup and Data Fetching

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Configures and fetches Google Analytics data using Spatie Analytics package. Handles service account credentials upload, property configuration, and data retrieval for visitors, page views, referrers, and browsers. Requires service account credentials file and property ID for setup. Returns JSON response with analytics data for specified periods.

```php
// POST /analytics/google/setup - Configure Google Analytics
// Controller: App\Http\Controllers\SuperAdmin\AnalyticController@google_setup
// Middleware: teamSA, password.confirm

use Spatie\Analytics\Facades\Analytics;
use Spatie\Analytics\Period;

// Setup analytics
public function google_setup(Request $req)
{
    $credentials = $req->file('service_account_credentials');
    $path = storage_path('app/public/analytics-credentials.json');
    $credentials->move(dirname($path), basename($path));

    $data = [
        'google_analytic_service_account_credential_file' =>
            'analytics-credentials.json',
        'google_analytic_property_id' => $req->property_id,
        'google_analytic_tag_id' => $req->tag_id,
        'analytics_enabled' => 1
    ];

    $this->setting->update($data);

    return back()->with('flash_success', 'Analytics configured');
}

// GET /analytics/data/google/fetch - Fetch analytics data
public function fetch_data(Request $req)
{
    if (!Qs::googleAnalyticsSetUpOkAndEnabled()) {
        return response()->json(['error' => 'Analytics not configured']);
    }

    $period = Period::days($req->days ?? 30);

    $data = [
        'visitors' => Analytics::fetchVisitorsAndPageViews($period),
        'most_visited' => Analytics::fetchMostVisitedPages($period, 10),
        'referrers' => Analytics::fetchTopReferrers($period, 10),
        'browsers' => Analytics::fetchTopBrowsers($period, 10)
    ];

    return response()->json($data);
}

// GET /settings/analytics/google/enable - Enable analytics
// GET /settings/analytics/google/disable - Disable analytics
```

--------------------------------

### GET /settings/analytics/google/enable

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Enables Google Analytics tracking in the system settings.

```APIDOC
## GET /settings/analytics/google/enable

### Description
Activates Google Analytics for the application.

### Method
GET

### Endpoint
/settings/analytics/google/enable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
{}

### Response
#### Success Response (200)
- Confirmation of enablement

#### Response Example
{
  "success": true,
  "message": "Analytics enabled"
}
```

--------------------------------

### GET /analytics/data/google/fetch

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Fetches Google Analytics data for a specified period, including visitors, top pages, referrers, and browsers. Requires analytics to be configured and enabled.

```APIDOC
## GET /analytics/data/google/fetch

### Description
Retrieves usage analytics data from Google Analytics for the last N days.

### Method
GET

### Endpoint
/analytics/data/google/fetch

### Parameters
#### Path Parameters
None

#### Query Parameters
- **days** (integer) - Optional - Number of days for the period (default: 30)

#### Request Body
None

### Request Example
?days=30

### Response
#### Success Response (200)
- **visitors** (array) - Visitors and page views data
- **most_visited** (array) - Top visited pages
- **referrers** (array) - Top referrers
- **browsers** (array) - Top browsers

#### Response Example
{
  "visitors": [
    {"date": "2023-01-01", "visitors": 100, "pageviews": 500}
  ],
  "most_visited": [
    {"url": "/home", "pageviews": 200}
  ],
  "referrers": [
    {"url": "google.com", "sessions": 50}
  ],
  "browsers": [
    {"browser": "Chrome", "sessions": 80}
  ]
}
```

--------------------------------

### GET /query_builder/index

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

This endpoint serves as the query builder interface for support team members. It allows access to the UI for constructing custom queries on staff and student data. The endpoint is protected by teamSA middleware.

```APIDOC
## GET /query_builder/index

### Description
Provides the query builder interface for generating custom staff and student reports dynamically.

### Method
GET

### Endpoint
/query_builder/index

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
No request body required.

### Response
#### Success Response (200)
Returns the query builder view or interface data.

#### Response Example
HTML view or JSON with available tables and columns.
```

--------------------------------

### GET /payments/pdf_receipts/{id}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Downloads a PDF version of payment receipts for offline storage and printing. Ensures proper documentation of financial transactions.

```APIDOC
## GET /payments/pdf_receipts/{id}

### Description
Downloads a PDF version of payment receipts for offline storage, printing, and official documentation of financial transactions.

### Method
GET

### Endpoint
/payments/pdf_receipts/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Payment record identifier

### Response
#### Success Response (200)
- **pdf** (file) - PDF document of the payment receipt
```

--------------------------------

### GET /students/graduated

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Retrieves a list of graduated students with their details.

```APIDOC
## GET /students/graduated

### Description
Fetches all students marked as graduated.

### Method
GET

### Endpoint
/students/graduated

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
{}

### Response
#### Success Response (200)
- **students** (array) - List of graduated student records

#### Response Example
{
  "students": [
    {
      "id": 1,
      "name": "John Doe",
      "grad_date": "2023-01-01"
    }
  ]
}
```

--------------------------------

### GET /payments/invoice/{st_id}/{year?}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Generates a comprehensive invoice for a student showing cleared and uncleared payments. Useful for financial tracking and parent communication.

```APIDOC
## GET /payments/invoice/{st_id}/{year?}

### Description
Generates a comprehensive invoice for a student showing cleared and uncleared payments for financial tracking and parent communication.

### Method
GET

### Endpoint
/payments/invoice/{st_id}/{year?}

### Parameters
#### Path Parameters
- **st_id** (integer) - Required - Student identifier
- **year** (string) - Optional - Academic year

### Response
#### Success Response (200)
- **invoice** (object) - Student invoice with cleared and uncleared payments

#### Response Example
{
  "student": "JOHN DOE (SMS/F2/2024/2024001)",
  "class": "Form 2A",
  "cleared": [
    {
      "title": "School Fees Term 1",
      "amount": 500000,
      "date": "2024-03-15"
    }
  ],
  "uncleared": [
    {
      "title": "Library Fees",
      "amount": 50000,
      "due": "2024-04-30"
    }
  ]
}
```

--------------------------------

### Generate Payment Invoice Data Structure

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Example data structure for generating student payment invoices. Contains cleared and uncleared payments with titles, amounts, and due dates. Supports student identification with class information.

```php
$invoice = [
    'student' => 'JOHN DOE (SMS/F2/2024/2024001)',
    'class' => 'Form 2A',
    'cleared' => [
        ['title' => 'School Fees Term 1', 'amount' => 500000, 'date' => '2024-03-15'],
    ],
    'uncleared' => [
        ['title' => 'Library Fees', 'amount' => 50000, 'due' => '2024-04-30'],
    ]
];
```

--------------------------------

### GET /marks/print/{id}/{exam_id}/{year}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Generates and returns a PDF version of a student's marksheet for printing. Useful for official documentation and record keeping.

```APIDOC
## GET /marks/print/{id}/{exam_id}/{year}

### Description
Generates and returns a PDF version of a student's marksheet for the specified exam and year, suitable for printing and official documentation.

### Method
GET

### Endpoint
/marks/print/{id}/{exam_id}/{year}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Student identifier
- **exam_id** (integer) - Required - Exam identifier
- **year** (string) - Required - Academic year

### Response
#### Success Response (200)
- **pdf** (file) - PDF document of the student's marksheet
```

--------------------------------

### GET /marks/show/{id}/{year}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Retrieves a student's marksheet for a specific year. Returns detailed examination results and performance data.

```APIDOC
## GET /marks/show/{id}/{year}

### Description
Retrieves a student's marksheet for a specific year, including detailed examination results and performance data.

### Method
GET

### Endpoint
/marks/show/{id}/{year}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Student identifier
- **year** (string) - Required - Academic year

### Response
#### Success Response (200)
- **marksheet** (object) - Student's marksheet data for the specified year
```

--------------------------------

### GET /payments/receipts/{id}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Retrieves payment receipts for a specific payment record. Provides detailed transaction information for accounting purposes.

```APIDOC
## GET /payments/receipts/{id}

### Description
Retrieves payment receipts for a specific payment record, providing detailed transaction information for accounting and verification purposes.

### Method
GET

### Endpoint
/payments/receipts/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Payment record identifier

### Response
#### Success Response (200)
- **receipt** (object) - Payment receipt details
```

--------------------------------

### GET /students/list/{class_id}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Retrieves a paginated list of students enrolled in a specific class. This endpoint supports filtering and pagination for efficient student record retrieval in the school system. It returns comprehensive student information for administrative purposes.

```APIDOC
## GET /students/list/{class_id}

### Description
Fetches paginated student records for a given class ID, enabling class-wise student management and reporting.

### Method
GET

### Endpoint
/students/list/{class_id}

### Parameters
#### Path Parameters
- **class_id** (integer) - Required - ID of the class to filter students (e.g., 5)

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination
- **per_page** (integer) - Optional - Number of records per page

#### Request Body
None

### Request Example
GET /students/list/5?page=1&per_page=10

### Response
#### Success Response (200)
- **data** (array) - Array of student objects with details like name, email, admission number
- **current_page** (integer) - Current page in pagination
- **total** (integer) - Total number of students

#### Response Example
{
  "data": [
    {
      "name": "JOHN DOE",
      "email": "john.doe@student.com",
      "adm_no": "2024001"
    }
  ],
  "current_page": 1,
  "total": 50
}
```

--------------------------------

### Configure Environment and Generate Keys

Source: https://github.com/rayusamboy/laravel_tenancy_sms/blob/main/README.md

Commands for setting up the .env file and generating necessary application keys. Includes storage linking and key generation steps.

```bash
cp .env.example .env
```

```bash
php artisan key:generate
```

```bash
php artisan storage:link
```

--------------------------------

### GET /settings/analytics/google/disable

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Disables Google Analytics tracking in the system settings.

```APIDOC
## GET /settings/analytics/google/disable

### Description
Deactivates Google Analytics for the application.

### Method
GET

### Endpoint
/settings/analytics/google/disable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
{}

### Response
#### Success Response (200)
- Confirmation of disablement

#### Response Example
{
  "success": true,
  "message": "Analytics disabled"
}
```

--------------------------------

### POST /analytics/google/setup

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Configures Google Analytics by uploading service account credentials and setting property/tag IDs. Enables analytics tracking by updating system settings.

```APIDOC
## POST /analytics/google/setup

### Description
Sets up Google Analytics integration by storing credentials and configuration details.

### Method
POST

### Endpoint
/analytics/google/setup

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **service_account_credentials** (file) - Required - JSON file with Google service account credentials
- **property_id** (string) - Required - Google Analytics property ID
- **tag_id** (string) - Required - Google Analytics tag ID

### Request Example
{
  "property_id": "GA_MEASUREMENT_ID",
  "tag_id": "G-XXXXXXXXXX"
}
(File upload for credentials)

### Response
#### Success Response (200)
- Redirect with success message

#### Response Example
Redirect to previous page with flash message: 'Analytics configured'
```

--------------------------------

### Database Migration and Seeding Commands

Source: https://github.com/rayusamboy/laravel_tenancy_sms/blob/main/README.md

Commands to set up the database structure and populate initial data. Includes migration and seeding for non-tenancy database.

```bash
php artisan migrate
```

```bash
php artisan db:seed --class=DatabaseSeederNonTenancy
```

--------------------------------

### Create timetable in PHP

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Demonstrates data structure for creating a school timetable. Includes name, class ID, term, and academic year. Requires teamSA middleware authorization.

```php
$timetableData = [
    'name' => 'FORM 2A TIMETABLE - TERM 1',
    'my_class_id' => 5,
    'term' => 'First Term',
    'year' => '2024-2025'
];
```

--------------------------------

### POST /tenants

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Creates a new tenant for an independent school with its own database and domain. This endpoint is used by the central IT Guy account to set up new educational institutions. It ensures data isolation and handles domain configuration during tenant provisioning.

```APIDOC
## POST /tenants

### Description
Creates a new tenant for an independent school, isolating its database and domain for secure multi-tenancy operations.

### Method
POST

### Endpoint
/tenants

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (string) - Required - Unique tenant identifier (e.g., 'school-alpha')
- **domain** (string) - Required - Custom domain for the tenant (e.g., 'schoolalpha.sms.edu')
- **data.name** (string) - Required - Name of the school (e.g., 'Alpha School')
- **data.account_status** (string) - Required - Status of the tenant account (e.g., 'active')

### Request Example
{
  "id": "school-alpha",
  "domain": "schoolalpha.sms.edu",
  "data": {
    "name": "Alpha School",
    "account_status": "active"
  }
}

### Response
#### Success Response (200)
- **message** (string) - Success confirmation (e.g., 'Tenant created successfully')

#### Response Example
{
  "pop_success": "msg.store_ok"
}
```

--------------------------------

### Create new tenant with isolated database using Laravel Tenancy (PHP)

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

This snippet demonstrates how to handle a POST request to create a new school tenant, assign a domain, and manage potential errors. It relies on the Tenancy for Laravel package and Laravel's request validation. Input includes tenant ID, domain, and metadata; output redirects with success or error messages.

```PHP
// POST /tenants - Create a new tenant
// Controller: App\Http\Controllers\ItGuy\TenantController@store
// Route: Route::resource('tenants', 'TenantController')

// Example request
$request = [
    'id' => 'school-alpha',
    'domain' => 'schoolalpha.sms.edu',
    'data' => [
        'name' => 'Alpha School',
        'account_status' => 'active'
    ]
];

// Implementation example
public function store(TenantRequest $request)
{
    set_time_limit(600); // 10 minutes for tenant creation
    $data = $request->except(['_token', '_method', 'domain']);

    try {
        $tenant = $this->tenant->create($data);
        $tenant->createDomain(['domain' => $request->domain]);
        return back()->with('pop_success', __('msg.store_ok'));
    } catch (\Exception $e) {
        if (session()->has("created_tenant_id")) {
            $this->tenant->delete(session()->get("created_tenant_id"));
        }
        return redirect()->back()->withErrors(['tenant_create_error' => $e->getMessage()]);
    }
}

// Access tenant: http://schoolalpha.sms.edu
// Default central domain: http://localhost
```

--------------------------------

### Create Payment Record in PHP Laravel

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Processes student payment records with amount, method, and academic year details. Uses Pay helper and supports multi-tenant environments. Includes payment category creation with title and description fields.

```php
use App\Helpers\Pay;

// Create payment category
$paymentData = [
    'title' => 'School Fees Term 1',
    'amount' => 500000, // TSH
    'description' => 'First term tuition fees',
    'method' => 'Bank Transfer',
    'my_class_id' => 5,
    'year' => '2024-2025'
];
```

--------------------------------

### POST /login

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Handles user authentication using username and password credentials. Validates tenant account status before allowing login. Returns a session or token upon successful authentication.

```APIDOC
## POST /login

### Description
User authentication endpoint for logging in with username and password. Checks tenant account status and aborts if inactive.

### Method
POST

### Endpoint
/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

### Request Example
{
  "username": "superadmin",
  "password": "superadmin"
}

### Response
#### Success Response (200)
- **authenticated** (boolean) - Indicates successful login.

#### Response Example
{
  "ok": true,
  "msg": "Login successful"
}
```

--------------------------------

### Core Helper Functions

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Utility functions for system-wide operations including user role checking, system settings retrieval, ID hashing, response helpers, date formatting, file paths, notification channels, and user code generation. These functions provide consistent functionality across the application.

```php
use App\Helpers\Qs;

// User role checking
if (Qs::userIsTeamSA()) {
    // User is Super Admin or Admin
}

if (Qs::userIsStudent()) {
    $student_record = Qs::findStudentRecord(auth()->id());
}

// Get system settings
$current_session = Qs::getCurrentSession(); // "2024-2025"
$system_name = Qs::getSystemName(); // "Alpha Secondary School"
$app_code = Qs::getAppCode(); // "SMS"

// Hash IDs for URLs (security)
$hashed_id = Qs::hash(123); // Returns: "xR9kLm2pW4"
$decoded_id = Qs::decodeHash('xR9kLm2pW4'); // Returns: "123"

// Response helpers
return Qs::jsonStoreOk(); // {"ok": true, "msg": "Record saved successfully"}
return Qs::jsonUpdateOk(); // {"ok": true, "msg": "Record updated successfully"}
return Qs::goWithSuccess('dashboard', 'Operation completed');
return Qs::goWithDanger('dashboard', 'Record not found');

// Date formatting
$formatted = Qs::onlyDateFormat('2024-03-15 14:30:00');
// Output: "Friday, 15 March 2024"

$full = Qs::fullDateTimeFormat('2024-03-15 14:30:00');
// Output: "Friday, 15 March 2024. 02:30 PM"

// File upload paths
$path = Qs::getUserUploadPath(); // "uploads/2024/03/15/"
$student_path = Qs::getUploadPath('student'); // "uploads/student"

// Notification channels
$channels = Qs::getActiveNotificationChannels(
    $user,
    include_database: true,
    include_email: true,
    include_push_notification: true
);
// Returns: ['database', 'mail', FcmChannel::class]

// Generate user code
$code = Qs::generateUserCode(); // Returns: "7a4K9m2"
```

--------------------------------

### Add book to library in PHP

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Data structure for adding new books to the library system. Tracks details like author, description, location, and copy counts. Requires librarian-level permissions.

```php
$bookData = [
    'name' => 'Introduction to Algorithms',
    'author' => 'Thomas H. Cormen',
    'description' => 'Comprehensive guide to algorithms',
    'book_type' => 'Computer Science',
    'url' => 'https://mitpress.mit.edu/books/introduction-algorithms',
    'location' => 'Shelf A3',
    'total_copies' => 10,
    'issued_copies' => 0,
    'about_author' => 'Professor at Dartmouth College'
];
```

--------------------------------

### Rebuild Node Packages After Environment Changes

Source: https://github.com/rayusamboy/laravel_tenancy_sms/blob/main/README.md

Command to rebuild Node packages when VITE environment variables are updated. Required after changing broadcast connections or VITE keys.

```bash
npm run build
```

--------------------------------

### Process Student Payment in PHP Laravel

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Updates payment records to mark as paid with proof documentation. Includes student notification functionality through the Qs helper. Returns JSON response for AJAX compatibility.

```php
public function pay_now($id, Request $req)
{
    $id = Qs::decodeHash($id);
    $data = ['paid' => 1, 'proof' => $req->proof];

    $pr = $this->pay->updatePaymentRecord($id, $data);

    // Send notification
    $student = $pr->student->user;
    if (Qs::getActiveNotificationChannels($student)) {
        $student->notify(new StudentPaymentPaid($pr));
    }

    return Qs::jsonStoreOk();
}
```

--------------------------------

### Create student record with auto-generated credentials (PHP)

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

This snippet shows how to process a POST request to store a new student, generating a unique username, password hash, and avatar. It uses helper classes for data extraction and Laravel's hashing. Inputs are student details; the function returns a JSON success response after creating user and student records.

```PHP
// POST /students - Create student record
// Controller: App\Http\Controllers\SupportTeam\StudentRecordController@store
// Middleware: teamSA (Admin, Super Admin)

use App\Helpers\Qs;
use App\Helpers\Usr;

// Example student creation
$studentData = [
    'name' => 'JOHN DOE',
    'email' => 'john.doe@student.com',
    'phone' => '+255789123456',
    'dob' => '2008-05-15',
    'gender' => 'Male',
    'address' => '123 Main Street, Dar es Salaam',
    'my_class_id' => 5, // Form 2
    'section_id' => 3,
    'adm_no' => '2024001',
    'my_parent_id' => 45,
    'dorm_id' => 2,
    'date_admitted' => '2024-01-10',
    'religion' => 'Christian'
];

// In controller
public function store(StudentRecordCreate $req)
{
    $data = $req->only(Qs::getUserRecord());
    $sr =req->only(Qs::getStudentData());

    $ct = $this->my_class->findTypeByClass($req->my_class_id)->code;

    $data['user_type'] = 'student';
    $data['name'] = strtoupper($req->name);
    $data['code'] = strtoupper(Str::random(10));
    $data['password'] = Hash::make('student');
    $data['photo'] = Usr::create($name, $code, 'student');

    // Generate username: SMS/F2/2024/2024001
    $data['username'] = strtoupper(Qs::getAppCode() . '/' . $ct . '/' .
        date('Y', strtotime($sr['date_admitted'])) . '/' . $req->adm_no);

    $user = $this->user->create($data);
    $sr['user_id'] = $user->id;
    $this->student->createRecord($sr);

    return Qs::jsonStoreOk();
}

// GET /students/list/{class_id} - List students by class
// Returns: JSON with paginated student records
```

--------------------------------

### POST /query_builder/select/query

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Executes a custom database query based on provided table, columns, and conditions. Supports joins for related tables like student_records with users and classes. Returns selected data in a structured JSON format suitable for reports.

```APIDOC
## POST /query_builder/select/query

### Description
Executes a dynamic query to fetch custom report data for staff or students, applying filters and joins as needed.

### Method
POST

### Endpoint
/query_builder/select/query

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **table_name** (string) - Required - The target table (e.g., 'student_records', 'staff_records').
- **columns** (array) - Required - Array of column names to select (e.g., ['name', 'email', 'phone']).
- **conditions** (array) - Optional - Key-value pairs for WHERE clauses (e.g., {'gender': 'Male', 'class': 'Form 2'}).

### Request Example
{
  "table_name": "student_records",
  "columns": ["name", "email", "phone"],
  "conditions": {"gender": "Male", "class": "Form 2"}
}

### Response
#### Success Response (200)
- **columns** (array) - Presentable column names for display.
- **data** (array) - Array of result rows from the query.

#### Response Example
{
  "columns": ["Full Name", "Email", "Phone"],
  "data": [
    {"name": "John Doe", "email": "john@example.com", "phone": "123456"}
  ]
}
```

--------------------------------

### POST /messages

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Creates a new message thread with initial message and adds participants. Broadcasts the new message in real-time using Laravel Reverb for updates to other users.

```APIDOC
## POST /messages

### Description
Creates a message thread, adds the first message, and invites participants. Triggers real-time broadcast to participants via Laravel Echo and Reverb.

### Method
POST

### Endpoint
/messages

### Parameters
#### Request Body
- **subject** (string) - Required - Thread subject line.
- **message** (string) - Required - Body of the initial message.
- **recipients** (array) - Required - Array of user IDs to add as participants.

### Request Example
{
  "subject": "Meeting Update",
  "message": "Please review the agenda.",
  "recipients": [2, 3]
}

### Response
#### Success Response (200)
- **ok** (boolean) - True on successful creation.
- **msg** (string) - Success message.

#### Response Example
{
  "ok": true,
  "msg": "Record saved successfully"
}
```

--------------------------------

### POST /students/promotion/{status}/{from_class}/{from_section}/{to_class}/{to_section}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Promotes selected students to a new class or section, creates promotion records, and updates student records based on status (promoted, not-promoted, graduated). Requires an array of student IDs in the request body. Handles graduation by marking students as graduated.

```APIDOC
## POST /students/promotion/{status}/{from_class}/{from_section}/{to_class}/{to_section}

### Description
Promotes or handles status changes for selected students by creating promotion records and updating their class/section or graduation status.

### Method
POST

### Endpoint
/students/promotion/{status}/{from_class}/{from_section}/{to_class}/{to_section}

### Parameters
#### Path Parameters
- **status** (string) - Required - Promotion status: promoted, not-promoted, graduated
- **from_class** (string) - Required - Encoded hash of the from class ID
- **from_section** (string) - Required - Encoded hash of the from section ID
- **to_class** (string) - Required - Encoded hash of the to class ID
- **to_section** (string) - Required - Encoded hash of the to section ID

#### Query Parameters
None

#### Request Body
- **students** (array) - Required - Array of student IDs to process

### Request Example
{
  "students": [1, 2, 3]
}

### Response
#### Success Response (200)
- Returns JSON success message

#### Response Example
{
  "success": true,
  "message": "Promotion processed successfully"
}
```

--------------------------------

### AJAX Endpoints

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Provides endpoints for dynamic data loading for forms and UI components.

```APIDOC
## GET /ajax/get_class_sections/{class_id}

### Description
Retrieves a list of sections for a given class.

### Method
GET

### Endpoint
/ajax/get_class_sections/{class_id}

### Parameters
#### Path Parameters
- **class_id** (integer) - Required - The ID of the class to retrieve sections for.

### Response
#### Success Response (200)
- **sections** (array) - An array of section objects, each containing id, name, and teacher information.
  - **id** (integer) - The ID of the section.
  - **name** (string) - The name of the section.
  - **teacher** (object | null) - Information about the teacher, or null if not assigned.
    - **name** (string) - The name of the teacher.

### Response Example
{
  "sections": [
    {
      "id": 1,
      "name": "Section A",
      "teacher": {
        "name": "Mr. Smith"
      }
    }
  ]
}

## GET /ajax/get_class_students/{class_id}

### Description
Retrieves a list of students for a given class.

### Method
GET

### Endpoint
/ajax/get_class_students/{class_id}

### Parameters
#### Path Parameters
- **class_id** (integer) - Required - The ID of the class to retrieve students for.

### Response
#### Success Response (200)
- **students** (array) - An array of student objects.
  - **id** (integer) - The ID of the student.
  - **name** (string) - The name of the student.
  - **adm_no** (string) - The admission number of the student.

### Response Example
[
  {
    "id": 101,
    "name": "JOHN DOE",
    "adm_no": "2024001"
  }
]

## GET /ajax/get_class_subjects/{class_id}

### Description
Retrieves a list of subjects for a given class.

### Method
GET

### Endpoint
/ajax/get_class_subjects/{class_id}

### Parameters
#### Path Parameters
- **class_id** (integer) - Required - The ID of the class to retrieve subjects for.

## GET /ajax/get_year_exams/{year}

### Description
Retrieves a list of exams for a specific year.

### Method
GET

### Endpoint
/ajax/get_year_exams/{year}

### Parameters
#### Path Parameters
- **year** (string) - Required - The year to retrieve exams for (e.g., '2024').

## GET /ajax/get_state/{nal_id}

### Description
Retrieves a list of states based on a given nationality ID.

### Method
GET

### Endpoint
/ajax/get_state/{nal_id}

### Parameters
#### Path Parameters
- **nal_id** (integer) - Required - The ID of the nationality.

## GET /ajax/get_lga/{state_id}

### Description
Retrieves a list of Local Government Areas (LGAs) based on a given state ID.

### Method
GET

### Endpoint
/ajax/get_lga/{state_id}

### Parameters
#### Path Parameters
- **state_id** (integer) - Required - The ID of the state.

```

--------------------------------

### User Authentication with 2FA

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Handles user login with optional Two-Factor Authentication using Google Authenticator. Includes login form customization based on tenant settings and 2FA setup/verification. Requires PragmaRX Google2FA package and tenant-specific account status checks.

```php
// POST /login - User authentication
// Controller: App\Http\Controllers\Auth\LoginController@login

// Example login
$credentials = [
    'username' => 'superadmin',
    'password' => 'superadmin'
];

// Show login form with custom colors
public function showLoginForm()
{
    $settings = Qs::getSettings();
    $account_status = tenant('account_status');

    // Check tenant account status
    if (in_array($account_status, Usr::getAccountStatuses(['active']))) {
        abort(403, 'ACCOUNT ' . strtoupper($account_status));
    }

    $data['colors'] = $colors = $settings
        ->where('type', 'login_and_related_pgs_txts_and_bg_colors')
        ->value('description');

    return view('auth.login', $data);
}

// POST /auth/2fa/authenticate - Verify 2FA token
// Controller: App\Http\Controllers\Auth\AccountSecurityController@authenticate
// Middleware: throttle:5,1 (max 5 attempts per minute)

use PragmaRX\Google2FA\Google2FA;

// Setup 2FA
public function update_secret_codes(Request $req)
{
    $google2fa = new Google2FA();
    $secret = $google2fa->generateSecretKey();

    $user = auth()->user();
    $user->google2fa_secret = $secret;
    $user->save();

    // Generate QR code
    $qrCodeUrl = $google2fa->getQRCodeUrl(
        Qs::getSystemName(),
        $user->email,
        $secret
    );

    return response()->json([
        'secret' => $secret,
        'qr_code_url' => $qrCodeUrl
    ]);
}

// Verify token
public function authenticate(Request $req)
{
    $google2fa = new Google2FA();
    $valid = $google2fa->verifyKey(
        auth()->user()->google2fa_secret,
        $req->one_time_password
    );

    if ($valid) {
        session(['2fa_verified' => true]);
        return redirect()->route('dashboard');
    }

    return back()->withErrors(['Invalid verification code']);
}
```

--------------------------------

### POST /students/promotion/remarks/{id}

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Adds remarks to a specific promotion record identified by ID. Used for tracking additional notes on student promotions.

```APIDOC
## POST /students/promotion/remarks/{id}

### Description
Adds remarks or notes to an existing promotion record for a student.

### Method
POST

### Endpoint
/students/promotion/remarks/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Promotion record ID

#### Query Parameters
None

#### Request Body
- **remarks** (string) - Required - The remark text to add

### Request Example
{
  "remarks": "Promoted with honors"
}

### Response
#### Success Response (200)
- Confirmation of remark addition

#### Response Example
{
  "success": true,
  "message": "Remarks added"
}
```

--------------------------------

### Student Promotion System - Laravel Controller

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Manages student promotions to next class levels with status tracking and grade updates. Handles promotion records creation, student record updates, and graduation status. Supports multiple promotion statuses including promoted, not-promoted, and graduated. Includes methods for adding promotion remarks and resetting all promotions.

```php
// POST /students/promote/selector - Select class for promotion
// GET /students/promotion/{status}/{from_class}/{from_section}/{to_class}/{to_section}
// Controller: App\Http\Controllers\SupportTeam\PromotionController

// Promote students
public function promote($status, $fc, $fs, $tc, $ts, Request $req)
{
    $from_class = Qs::decodeHash($fc);
    $from_section = Qs::decodeHash($fs);
    $to_class = Qs::decodeHash($tc);
    $to_section = Qs::decodeHash($ts);

    $students = $req->input('students'); // Array of student IDs

    foreach ($students as $student_id) {
        $sr = $this->student->getRecord(['user_id' => $student_id])->first();

        // Create promotion record
        $this->student->createPromotion([
            'from_class' => $from_class,
            'from_section' => $from_section,
            'to_class' => $to_class,
            'to_section' => $to_section,
            'student_id' => $student_id,
            'session' => Qs::getCurrentSession(),
            'status' => $status, // promoted, not-promoted, graduated
        ]);

        // Update student record if promoted
        if ($status === 'promoted') {
            $sr->my_class_id = $to_class;
            $sr->section_id = $to_section;
            $sr->save();
        } elseif ($status === 'graduated') {
            $sr->grad = 1;
            $sr->grad_date = now();
            $sr->save();
        }
    }

    return Qs::jsonStoreOk();
}

// POST /students/promotion/remarks/{id} - Add promotion remarks
// DELETE /students/promotion/reset/all - Reset all promotions
// GET /students/graduated - View graduated students
// PUT /students/not_graduated/{s_id}/{prom_id} - Reverse graduation
```

--------------------------------

### POST /students

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Creates a new student record with demographic, academic, and contact information. This endpoint is restricted to Admin and Super Admin roles and generates necessary user credentials, usernames, and avatars. It links the student to classes, sections, parents, and dorms for comprehensive management.

```APIDOC
## POST /students

### Description
Registers a new student with full profile details, including academic assignments and user account creation for the school management system.

### Method
POST

### Endpoint
/students

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - Full name of the student (e.g., 'JOHN DOE')
- **email** (string) - Required - Student email address
- **phone** (string) - Required - Contact phone number
- **dob** (date) - Required - Date of birth
- **gender** (string) - Required - Gender (e.g., 'Male')
- **address** (string) - Required - Residential address
- **my_class_id** (integer) - Required - Class ID (e.g., 5 for Form 2)
- **section_id** (integer) - Required - Section ID
- **adm_no** (string) - Required - Admission number (e.g., '2024001')
- **my_parent_id** (integer) - Required - Parent ID
- **dorm_id** (integer) - Optional - Dormitory ID
- **date_admitted** (date) - Required - Admission date
- **religion** (string) - Optional - Religion

### Request Example
{
  "name": "JOHN DOE",
  "email": "john.doe@student.com",
  "phone": "+255789123456",
  "dob": "2008-05-15",
  "gender": "Male",
  "address": "123 Main Street, Dar es Salaam",
  "my_class_id": 5,
  "section_id": 3,
  "adm_no": "2024001",
  "my_parent_id": 45,
  "dorm_id": 2,
  "date_admitted": "2024-01-10",
  "religion": "Christian"
}

### Response
#### Success Response (200)
- **message** (string) - Success message for student creation
- **data** (object) - Created student record details

#### Response Example
{
  "message": "Student created successfully"
}
```

--------------------------------

### POST /payments

Source: https://context7.com/rayusamboy/laravel_tenancy_sms/llms.txt

Creates a new payment record for student fees. Supports various payment methods and includes notification capabilities for payment confirmation.

```APIDOC
## POST /payments

### Description
Creates a new payment record for student fees with support for multiple payment methods. Includes automatic notification system for payment confirmation.

### Method
POST

### Endpoint
/payments

### Parameters
#### Request Body
- **title** (string) - Required - Payment title/description
- **amount** (integer) - Required - Payment amount in TSH
- **description** (string) - Required - Detailed payment description
- **method** (string) - Required - Payment method (e.g., Bank Transfer)
- **my_class_id** (integer) - Required - Class identifier
- **year** (string) - Required - Academic year

### Request Example
{
  "title": "School Fees Term 1",
  "amount": 500000,
  "description": "First term tuition fees",
  "method": "Bank Transfer",
  "my_class_id": 5,
  "year": "2024-2025"
}

### Response
#### Success Response (200)
- **payment_record** (object) - Created payment record details
```