# RELAMS System Architecture

## 1. Project Overview

RELAMS is an enterprise Real Estate & Land Management System for managing real-estate assets and business operations. It is built as a monolithic web application with server-rendered Blade views and a module-based backend.

## 2. Technology Stack

- PHP ^8.2
- Laravel 12
- Blade templating engine
- Vite frontend build
- Bootstrap CSS
- Axios for AJAX requests
- spatie/laravel-permission for roles and permissions
- barryvdh/laravel-dompdf for PDF generation
- maatwebsite/excel and rap2hpoutre/fast-excel for Excel exports
- Livewire available in dependencies

## 3. Application Structure

### Main directories

- `app/Http/Controllers/V1/Web/` - main web controllers by module
- `app/Models/` - Eloquent models and domain entities
- `app/Enum/` - status and type enums used across the app
- `app/Services/` - business service classes
- `app/Traits/` - shared reusable traits
- `app/Helpers/Helper.php` - global helper functions
- `resources/views/` - Blade templates organized by module
- `resources/js/` - frontend entry points
- `routes/web.php` - web route definitions
- `composer.json` / `package.json` - dependency and script definitions

## 4. Routing and Controller Architecture

### Public authentication

Routes:
- `/` and `/auth` → `AuthController@showSignin`
- `/auth/signin` → `AuthController@signin`

Protected app routes are grouped under `/app` and guarded by `auth:web` middleware.

### Modules and route prefixes

- `/app/` → dashboard (`HomeController@index`)
- `/app/users` → user management
- `/app/settings` → profile, password, permission, role, commission settings
- `/app/agents` → agent CRUD, export, PDF
- `/app/commissions` → commission CRUD, approval, payouts, export
- `/app/customers` → customer CRUD, activity, orders, transactions, export
- `/app/areas` → area CRUD, map, plots, export
- `/app/plots` → plot CRUD, status, availability, export
- `/app/orders` → order CRUD, cart, payments, invoices, export
- `/app/payments` → payment approval, history, printing, export
- `/app/accounts` → account management and transactions
- `/app/shops` → shop catalog, inventory, item sales, and order management
- `/app/transfers` → transfer approval, history, export
- `/app/transactions` → transaction receipts and export

### Controller pattern

Controllers are placed in `app/Http/Controllers/V1/Web/` and correspond with route modules. Each controller handles:
- list views
- create/edit forms
- store/update actions
- view/detail pages
- activation/deactivation and status toggles
- exports and PDF generation

## 5. Modules and Domain Areas

### Authentication & Access Control

- `AuthController` manages sign-in and sign-out.
- `spatie/laravel-permission` manages roles and permissions.
- `auth:web` middleware protects all `/app` routes.

### User Management

- `UsersController`
- CRUD operations for internal users
- password management
- activation and deactivation

### Settings

- `SettingController`
- user profile and password updates
- permission and role management
- agent commission configuration

### Agent Management

- `AgentController`
- agent profile management
- export and PDF profile generation

### Commission Management

- `CommissionController`
- commission creation and administration
- approve, pay, disapprove, cancel workflows
- export reporting

### Customer Management

- `CustomerController`
- customer onboarding and lifecycle
- activity, order history, payment history, PDF reports

### Area and Plot Management

- `AreaController` and `PlotController`
- geographic area records and plot assignment
- status management, export, and PDF reports
- area-specific plot views and map pages

### Order, Payment, and Transaction Management

- `OrderController`, `PaymentController`, `TransactionController`
- order creation, cart handling, cancellations
- invoice receipts, payment approval, print and export
- transaction receipt PDF and print workflows

### Accounts and Transfers

- `AccountController` and `TransferController`
- account record management
- transfer approval and cancellation workflows
- export history

### Shop Management

- `ShopController` (or optionally `ShopItemController`, `ShopOrderController`)
- manages store catalogs, inventory items, and internal shop orders
- supports store creation, item listing, stock management, and order tracking
- integrates with customers, payments, invoices, and reports for shop sales

#### Shop module design

- Purpose: provide an internal shop where agents or customers can purchase goods and services, maintain inventory, and record shop sales.
- Data columns for a `shops` table:
  - `id`
  - `name`
  - `description`
  - `location`
  - `status` (`Active`, `Inactive`)
  - `business_id`
  - `created_by`
  - `updated_by`
  - `created_at`, `updated_at`

- Data columns for a `shop_items` table:
  - `id`
  - `shop_id`
  - `code`
  - `name`
  - `description`
  - `category`
  - `price`
  - `cost`
  - `quantity`
  - `status`
  - `created_by`
  - `updated_by`
  - `created_at`, `updated_at`

- Data columns for a `shop_orders` table:
  - `id`
  - `shop_id`
  - `customer_id`
  - `order_code`
  - `total`
  - `status` (`Pending`, `Completed`, `Cancelled`)
  - `payment_status`
  - `payment_reference`
  - `created_by`
  - `updated_by`
  - `created_at`, `updated_at`

- Data columns for a `shop_order_items` table:
  - `id`
  - `shop_order_id`
  - `shop_item_id`
  - `quantity`
  - `price`
  - `subtotal`
  - `created_at`, `updated_at`

#### Shop endpoints

- `/app/shops` → list shops
- `/app/shops/add` → show add shop form
- `/app/shops/store` → save new shop
- `/app/shops/view/{id}` → view shop detail
- `/app/shops/edit/{id}` → edit shop
- `/app/shops/update/{id}` → update shop
- `/app/shops/activate/{id}` → activate shop
- `/app/shops/deactivate/{id}` → deactivate shop
- `/app/shops/delete/{id}` → delete shop
- `/app/shops/{id}/items` → list inventory items for a shop
- `/app/shops/{id}/items/add` → add item to shop
- `/app/shops/{id}/items/store` → save item
- `/app/shops/{id}/orders` → list shop orders
- `/app/shops/{id}/orders/add` → create shop order
- `/app/shops/orders/{code}/view` → view order
- `/app/shops/orders/{code}/invoice` → shop order invoice/PDF

### Reports, Ownership, Voucher, Invoice

- `ReportController`, `OwnershipController`, `VoucherController`, `InvoiceController`
- reserved controllers for additional reporting, ownership records, vouchers, and invoice generation

## 6. Data Layer and Models

### Primary Models

- `User` - application users, roles, business and audit relations
- `Agent` - sales agents and agent profiles
- `Customer` - end customers and customer types
- `Area` - geographic inventory areas
- `Plot` - individual land plots and availability
- `Shop` - store or shop entity for internal catalog and sales
- `ShopItem` - inventory item or product sold through a shop
- `ShopOrder` - shop order records and sales transactions
- `ShopOrderItem` - line item details for shop orders
- `Order`, `OrderItem` - orders and order item details
- `Payment` - payment records and statuses
- `Transactions` - transaction receipts and references
- `Transfer` - transfer requests between accounts
- `Commission` - agent commission entries and balances
- `Account` - account records and transaction histories
- `Ownership` - ownership records for plot assignments
- `Invoice`, `Voucher` - financial document support
- `Setting` - application configuration and commission rate settings
- `Business`, `Department` - business metadata and departments
- `AuthLog` - authentication logging
- `UserAgent` - user-agent relationship support

### Relationships and patterns

- `User` uses `HasRoles` and `HasFactory`
- models commonly define `createdBy()` and `updatedBy()` for audit tracking
- `Agent` links to `Order` and other sales data
- `Customer` and `Plot` likely connect through orders and ownership

### Enum usage

`app/Enum/` holds typed value sets for:
- `CommissionStatus`
- `OrderStatus`
- `PlotStatus`
- `PaymentStatus`
- `VoucherStatus`
- `OwnershipStatus`
- `OwnershipType`
- `StateLGA`
- `GeneralStatus`

Use enums to centralize status logic and avoid hard-coded strings.

## 7. View Layer and Frontend

### Blade templates

- Views organized by functional module under `resources/views/`
- each module has a dedicated directory such as `agents/`, `customers/`, `orders/`, `payments/`, etc.
- reusable components exist in `resources/views/components/`
- email templates are under `resources/views/emails/`

### Frontend assets

- `resources/js/app.js` - main frontend entry
- `resources/js/bootstrap.js` - frontend bootstrap logic
- `vite.config.js` - Vite asset bundling configuration
- `package.json` scripts: `npm run dev`, `npm run build`

### UI assumptions

- The application is mainly server-rendered with Blade
- likely uses Tailwind CSS utility classes
- AJAX and dynamic interactions via `axios`

## 8. Services and Helpers

### Business services

- `CommissionService` is a domain service for:
  - commission calculation
  - commission allocation and persistence
- place non-trivial business logic in `app/Services/`

### Shared traits

- `ActivityLogger` logs actions to the `Activity` model
- reusable by controllers and other classes for audit trails

### Global helpers

`app/Helpers/Helper.php` provides utility functions such as:
- unique code generation for areas, orders, vouchers, commissions, transfers, transactions, payments, ownerships, and plots
- price formatting
- customer name resolution
- amount-to-words conversion

These helpers are autoloaded by Composer and can be invoked anywhere in the app.

## 9. Configuration and Package Integration

### Composer packages

- Laravel framework
- Permissions and roles
- PDF generation
- Excel export and import
- Livewire support

### Frontend packages

- Tailwind CSS
- Vite
- Axios
- concurrently for local dev orchestration

### Testing

- `phpunit.xml` for PHPUnit
- Pest test support via `Pest.php`
- `tests/Feature/` and `tests/Unit/`

## 10. Developer Guidelines

### Adding a new feature
1. Add routes in `routes/web.php` under the appropriate `/app/<module>` group.
2. Create a controller in `app/Http/Controllers/V1/Web/`.
3. Add or extend the model in `app/Models/` if domain data needs persistence.
4. Add views in `resources/views/<module>/`.
5. Add exports or PDF flows if needed.
6. Add service classes for shared domain logic in `app/Services/`.
7. Use `ActivityLogger` to record audits.
8. Use enums in `app/Enum/` for status or type values.

### Security and quality

- Keep all `/app` routes behind `auth:web`.
- Prefer POST/PUT/DELETE for state-changing actions instead of GET.
- Centralize business rules in services instead of controllers when logic becomes complex.
- Keep Blade templates modular and component-based.
- Keep helper functions generic and reusable.

## 11. Architecture Notes

- The app is an MVC monolith with clear module separation by controller and view directories.
- The route definitions are the main entry point for application workflows.
- The model layer is standard Eloquent with audit relations and status enums.
- Shared services and helpers enable consistent business logic across controllers.
- The frontend is primarily Blade-rendered, with Vite used for asset compilation.

## 12. Recommended Improvements

- Consider moving destructive `GET` action endpoints to `POST`/`PUT`/`DELETE`.
- Add API-style controllers or JSON endpoints if a REST API is needed.
- Introduce request validation classes to centralize validation logic.
- Add a dedicated `app/Http/Requests/` directory for form requests.
- Use Livewire or Vue only where interactive UI flows require reactive components.

---

This document describes the current architecture, module layout, routing structure, model design, view organization, and developer workflow guidelines for the SKAN_LMS application.