# AGENTS.md

AI Development Rules for This Project

## Project Overview

This project follows a **Service Layer Architecture** using:

* Backend: Laravel
* Frontend: Vue.js
* Routing: Inertia.js
* UI Components: shadcn/ui
* Pattern: Modular Architecture

All modules must follow the same architecture structure.

---

# Module Development Rules

Whenever creating a new module (Example: Category, Product, Student, Teacher), always follow this structure.

---

# 1. Database Layer

Create a migration for the module.

Location:

database/migrations/

Example:

create_categories_table.php

Typical fields:

* id
* parent_id (optional)
* code (unique)
* name
* status
* sort
* image
* timestamps

Rules:

* Always use proper foreign keys.
* Use indexes for searchable fields.
* Use nullable fields only when necessary.

---

# 2. Model Layer

Location:

app/Models/

Example:

Category.php

Rules:

* Define `$guarded=['id']` fields.
* Define relationships (parent, children, belongsTo, hasMany).
* Keep models clean and lightweight.

Example relationships:

* parent()
* children()

---

# 3. Request Validation Layer

Location:

app/Http/Requests/

Example:

CategoryRequest.php

Rules:

* Use FormRequest validation.
* Do not place validation in controllers.
* Validate fields such as name, code, status, etc.

---

# 4. Service Layer

Location:

app/Services/

Example:

CategoryService.php

Purpose:

Handle all business logic.

Responsibilities:
* getAll()
* getById()
* getByCode()
* getByStatus()
* getByParentId()
* getBySearch()
* getBySort() 
* store()
* update()
* delete()
* image upload
* complex logic

Rules:

* Controllers must never contain business logic.
* All heavy logic must go inside Services.

---

# 5. Controller Layer

Location:

app/Http/Controllers/Admin/

Example:

CategoryController.php

Controller Responsibilities:

* Receive requests
* Call Service methods
* Return Inertia responses

Typical methods:

* index
* store
* update
* destroy

Rules:

Controllers must stay thin.

---

# 6. Routing

Location:

routes/web.php

All admin modules must be placed under admin routes.

Example:

Route::middleware(['auth'])
->prefix('admin')
->group(function () {

```
    Route::resource('categories', CategoryController::class);

});
```

---

# 7. Frontend Structure

Frontend pages must follow this structure.

Pages:

resources/js/pages/Admin/{ModuleName}/

Example:

resources/js/pages/Admin/Categories/Index.vue

Components:

resources/js/components/Admin/{ModuleName}/

Example:

CategoryCard.vue
CategoryModal.vue

---

# 7.1 Sidebar Integration
 Always add new modules under the relevant main category.
Use meaningful icons from your icon library (e.g., PackageIcon, FolderTree).

Route names must match Laravel routes to ensure Inertia links work correctly.

Sub-items are optional but recommended for modules with multiple views (e.g., index, reports).

Keep the sidebar consistent and organized, avoid duplicate entries.

# 8. UI Rules

UI must use:

* shadcn/ui components
* grid based layout
* reusable components

Example components:

* Card component
* Modal/Dialog component
* Form component

---

# 9. Page Layout Pattern

Every module page must contain:

* Search input
* Filter (optional)
* Create Button
* Grid/List view
* Edit action
* Delete action

---

# 10. Modal Form Pattern

Forms must use a reusable modal component.

Fields example:

* name
* code
* parent select
* color picker
* sort
* status toggle
* image upload

Use Inertia forms for submission.

---

# 11. Image Handling

All image upload logic must be handled in the Service layer.

Rules:

* Store images in storage/app/public
* Save only the image path in database.

---

# 12. Status Handling

Status fields must be boolean.

Example:

true = active
false = inactive

UI must show:

* Active badge
* Inactive badge

---

# 13. Reusability Rules

Always create reusable components when possible.

Examples:

* Modal
* Card
* Form elements

Avoid duplicated UI logic.

---

# 14. Code Quality Rules

Always follow:

* Clean Architecture
* Single Responsibility Principle
* Thin Controllers
* Service Layer Business Logic

Never:

* Put business logic in controllers
* Duplicate code across modules

---

# 15. Testing / Verification

Whenever a new module is created, verify:

* Create works
* Update works
* Delete works
* Image upload works
* UI grid renders correctly

---

# 16. Example Module Flow

Example: Creating a Category module

Steps:

1. Create Migration
2. Create Model
3. Create Request Validation
4. Create Service
5. Create Controller
6. Add Routes
7. Create Vue Page
8. Create UI Components
9. Connect Inertia Forms
10. Test CRUD operations

---

# Final Rule

All modules must strictly follow this architecture pattern.

Do not invent new structures unless absolutely necessary.

Consistency across modules is required.