# Architecture Rules

## Core Architecture
This project must follow:
- OOP
- Repository Pattern
- Service Pattern
- Controller Layer
- Form Request Validation
- API Resource / Response Card formatting

## Database
- Database engine: MySQL
- ORM: Eloquent Models

## Layer Responsibilities

### Controllers
Controllers are responsible for:
- receiving HTTP requests
- calling services
- returning HTTP responses only
- returning standardized response shape
- using resources / response cards for formatting

Controllers must NOT:
- contain business logic
- contain direct database queries
- access Eloquent models directly
- perform heavy transformation that belongs to service/resource layers

### Services
Services are responsible for:
- business logic
- workflow orchestration
- coordinating between repositories
- transactions when required
- domain-level decisions
- reusable application use cases

Services must NOT:
- return HTTP responses
- perform request validation
- access Eloquent models directly

### Repositories
Repositories are responsible for:
- all database access
- all Eloquent model interaction
- query building
- data persistence
- reusable query logic
- eager loading when needed

Repositories must NOT:
- contain business decisions
- return HTTP response objects
- perform request validation

### Models
Models should only represent entities and relationships.

Allowed in models:
- relationships
- casts
- scopes
- accessors / mutators
- small model helpers

Avoid heavy business logic in models.

## Non-Negotiable Rules
- No direct model calls in controllers
- No direct model calls in services
- Eloquent models are allowed ONLY inside repositories
- No HTTP response outside controllers
- No large validation rules inside controllers
- Validation must be handled using dedicated Form Request classes
- Response shape must be standardized
- API and Dashboard must stay separated
- Business logic must not be duplicated between API and Dashboard

## Response System
The project must use:
- a shared Response Trait for standardized API responses
- Resource / Response Card classes for output formatting

Do not return inconsistent ad-hoc JSON structures.

## API and Dashboard Separation

### API Layer
Should contain:
- API Controllers
- API Requests
- API Resources / Response Cards
- Services
- Repositories
- Shared Traits

### Dashboard Layer
Should contain:
- Livewire components
- dashboard views
- services
- repositories
- reusable validation strategy where appropriate

Dashboard should not duplicate API business logic.

## Dynamic Calculation Engine Rules
The calculations system is fully dynamic end-to-end.


## Filtering Rules
List pages in dashboard should support filtering where relevant.

## Soft Delete Rules
Soft delete should be used where appropriate for dashboard-managed entities.

## Error Handling
- Use exceptions for business failures
- Use meaningful exceptions
- Do not return raw strings from services
- Keep controller responses standardized

## Testing Rules
Unit tests are mandatory.

## Multi-language Rules
The system must support Arabic and English.

- Do not hardcode text in one language
- Use translation-ready fields where needed
- API responses should be language-aware
- Validation messages should support localization
- Dashboard UI should be translatable

## Role Management Rule
The admin system must rely on `role_id` only for admin authorization structure.

Do NOT introduce or keep a separate `admin_type` or `type` field in the admin entity.

## Shared Dashboard Layout Rule
All admin pages must use a shared dashboard layout.

This layout should contain:
- persistent sidebar
- header
- toolbar / breadcrumb area
- content wrapper

## Multi-language Display Rule
The application should display one active language at a time based on the selected locale.

## Metronic-Compatible UI Rule
The admin dashboard must be built in a Metronic-compatible structure.

## Persistent Sidebar Rule
The admin sidebar must be rendered from the shared admin layout only.

## Live Filter/Search Rule
For dashboard listing pages, text search should support automatic filtering while typing where appropriate.

## Export Rule
Relevant dashboard tables should support exporting data to sheet format.

## Livewire Rule
Interactive dashboard pages must use Livewire where appropriate.

Livewire responsibilities:
- manage UI state
- handle interactive dashboard behavior
- trigger service calls
- render reactive views

Livewire must NOT:
- access Eloquent models directly
- contain business logic
- replace services or repositories

The correct flow is:
Livewire Component -> Service -> Repository -> Model

Use Livewire especially for:
- live search
- reactive filters
- reactive pagination
- smooth admin table interactions
- dynamic flow builder preview
- simulation/test run UI

## Dashboard Form UX Rule
Interactive admin forms should provide a smooth validation experience.

## Standard Dashboard Actions Rule
Dashboard row actions must be standardized across modules.

## Settings Validation Rule
All settings fields must be required.

## Rich Text Editor Rule
Fields that contain long-form content must use a text editor instead of a plain input.

## Rich Text Rendering Rule
Rich text fields must be displayed differently depending on context.