# AGENTS.md

## 1. Project Overview

This project is a PHP web application for managing university business processes.

The main business domains include:

* Students
* Teachers
* Departments
* Academic programs
* Enrollments
* Courses
* Examinations
* Budget management
* Budget categories
* Budget types
* Financial operations
* University resources
* Administrative operations

The application uses:

* PHP
* HTML
* Bootstrap
* JavaScript
* CSS
* SQL/MySQL

The application is role-based. Each role has its own authentication, GUI, layouts, menus and CSS.

---

# 2. Main Project Architecture

The project follows a layered architecture.

```text
model/
├── dao/
├── service/
└── api/

app/
├── cnx/
├── css/
├── view/
└── layouts/

db/
├── db-structure.sql
├── db-data.sql
└── db-structure-data.sql
```

The responsibilities are:

| Directory       | Responsibility              |
| --------------- | --------------------------- |
| `model/dao`     | Database access             |
| `model/service` | Business logic              |
| `model/api`     | API / Web Services          |
| `app/cnx`       | Authentication / connection |
| `app/view`      | Graphical user interfaces   |
| `app/layouts`   | Menus and layouts           |
| `app/css`       | CSS                         |
| `db`            | Database scripts            |

---

# 3. DAO Rules

All DAO files MUST be located in:

```text
model/dao/
```

Examples:

```text
model/dao/StudentDao.php
model/dao/BudgetTypeDao.php
model/dao/BudgetCategoryDao.php
```

DAO responsibilities:

* Database queries
* CRUD operations
* Data persistence
* Data retrieval

DAO classes MUST NOT contain business logic.

---

# 4. Service Rules

All business services MUST be located in:

```text
model/service/
```

Examples:

```text
model/service/StudentService.php
model/service/BudgetTypeService.php
model/service/BudgetCategoryService.php
```

Services are responsible for:

* Business rules
* Validation
* Business calculations
* Coordination between DAOs
* Application-level operations

Services SHOULD use DAO classes for persistence.

---

# 5. API / Web Service Rules

All API or Web Service classes MUST be located in:

```text
model/api/
```

Examples:

```text
model/api/StudentApi.php
model/api/BudgetTypeApi.php
model/api/BudgetCategoryApi.php
```

The normal application flow is:

```text
GUI
 ↓
API
 ↓
Service
 ↓
DAO
 ↓
Database
```

API classes MUST NOT contain complex business logic.

---

# 6. Role-Based Application Structure

The application is organized by role.

Example:

```text
app/
├── cnx/
│   ├── admin/
│   ├── student/
│   └── teacher/
│
├── css/
│   ├── admin/
│   ├── student/
│   └── teacher/
│
├── view/
│   ├── admin/
│   ├── student/
│   └── teacher/
│
└── layouts/
    ├── admin/
    ├── student/
    └── teacher/
```

Each role has its own:

* Authentication
* GUI
* CSS
* Layout
* Menu

For example:

```text
app/cnx/admin/
app/css/admin/
app/view/admin/
app/layouts/admin/
```

and:

```text
app/cnx/student/
app/css/student/
app/view/student/
app/layouts/student/
```

Role-specific resources MUST remain inside the corresponding role directory.

---

# 7. GUI Organization by Role and Module

The GUI is organized hierarchically:

```text
Role
 ↓
Module / Space
 ↓
Database Table
 ↓
CRUD operation
```

For example, the administrator budget module is:

```text
app/view/admin/budget-space/
```

Inside a module, there is a folder for each database table managed by that module.

Example:

```text
app/view/admin/budget-space/
├── budget-type/
├── budget-category/
└── ...
```

Therefore:

```text
app/view/admin/budget-space/budget-type/
```

represents the GUI for the `budget_type` database table.

Similarly:

```text
app/view/admin/budget-space/budget-category/
```

represents the GUI for the `budget_category` database table.

---

# 8. Table GUI Structure

Each table folder MUST contain three main folders:

```text
create-edit/
list/
view/
```

Example:

```text
app/view/admin/budget-space/budget-type/
├── create-edit/
├── list/
└── view/
```

The responsibilities are:

| Folder        | Responsibility        |
| ------------- | --------------------- |
| `create-edit` | Create and edit forms |
| `list`        | List/table interface  |
| `view`        | Detailed entity view  |

---

# 9. List Folder Rules

The `list` folder contains the list interface for the table.

Example:

```text
app/view/admin/budget-space/budget-type/list/
├── index.php
└── main.js
```

The `index.php` file contains the list-page logic.

It MUST include the corresponding:

```text
main.js
```

The list page is responsible for displaying and managing the collection of entities.

For example:

```text
app/view/admin/budget-space/budget-type/list/index.php
```

displays the list of budget types.

---

# 10. Modal Organization

The list page uses the create/edit and view modals.

For example:

```text
app/view/admin/budget-space/budget-type/
├── create-edit/
│   └── modal.php
│
├── list/
│   ├── index.php
│   └── main.js
│
└── view/
    └── modal.php
```

The relationship is:

```text
list/index.php
     │
     ├── include create-edit/modal.php
     │
     └── include view/modal.php
```

The list page therefore acts as the main entry point for the CRUD interface.

---

# 11. Standard CRUD GUI Structure

Every table GUI SHOULD follow this structure:

```text
<table-name>/
├── create-edit/
│   └── modal.php
│
├── list/
│   ├── index.php
│   └── main.js
│
└── view/
    └── modal.php
```

Example:

```text
budget-type/
├── create-edit/
│   └── modal.php
├── list/
│   ├── index.php
│   └── main.js
└── view/
    └── modal.php
```

Another example:

```text
budget-category/
├── create-edit/
│   └── modal.php
├── list/
│   ├── index.php
│   └── main.js
└── view/
    └── modal.php
```

Agents MUST preserve this organization.

---

# 12. GUI Generation Rules

When creating a GUI for a new database table:

### Step 1

Identify the application role.

Example:

```text
admin
```

### Step 2

Identify the business module/space.

Example:

```text
budget-space
```

### Step 3

Identify the database table.

Example:

```text
budget-type
```

### Step 4

Create the GUI structure:

```text
app/view/admin/budget-space/budget-type/
├── create-edit/
│   └── modal.php
├── list/
│   ├── index.php
│   └── main.js
└── view/
    └── modal.php
```

### Step 5

Connect the list page to:

```text
create-edit/modal.php
view/modal.php
main.js
```

### Step 6

Connect the GUI to the appropriate API/service.

---

# 13. Database Structure

The database scripts are located in:

```text
db/
```

The project contains three important SQL files.

## Database Structure

```text
db/db-structure.sql
```

This file contains the database structure.

It should be used to understand:

* Tables
* Columns
* Primary keys
* Foreign keys
* Relationships
* Constraints
* Database schema

When implementing a feature related to a database table, the agent SHOULD inspect this file first.

---

# 14. Database Data

The file:

```text
db/db-data.sql
```

contains database data.

It can be used to understand:

* Existing records
* Example values
* Reference data
* Relationships between existing records

Agents SHOULD inspect this file when understanding existing data or debugging data-related behavior.

---

# 15. Complete Database Structure and Data

The file:

```text
db/db-structure-data.sql
```

contains both:

* Database structure
* Database data

It can be used when a complete representation of the database is required.

Conceptually:

```text
db-structure.sql
       +
db-data.sql
       =
db-structure-data.sql
```

Do not assume that these files are identical in every detail; inspect the actual project files before modifying database-related functionality.

---

# 16. Database-Driven GUI Rule

The GUI structure should reflect the business and database organization.

For example, if the database contains:

```text
budget_type
budget_category
budget
```

and they belong to the administrator budget module, the GUI should follow:

```text
app/view/admin/budget-space/
├── budget-type/
├── budget-category/
└── budget/
```

Each table then follows the standard CRUD structure:

```text
<table>/
├── create-edit/
├── list/
└── view/
```

This creates a predictable relationship:

```text
Database Table
      ↓
Business Model
      ↓
DAO
      ↓
Service
      ↓
API
      ↓
Role
      ↓
Module / Space
      ↓
GUI Table Folder
```

---

# 17. Example: Budget Type

For the `budget_type` table, the expected architecture is:

```text
model/
├── dao/
│   └── BudgetTypeDao.php
│
├── service/
│   └── BudgetTypeService.php
│
└── api/
    └── BudgetTypeApi.php
```

Administrator GUI:

```text
app/view/admin/budget-space/budget-type/
├── create-edit/
│   └── modal.php
├── list/
│   ├── index.php
│   └── main.js
└── view/
    └── modal.php
```

Administrator styling:

```text
app/css/admin/
```

Administrator navigation:

```text
app/layouts/admin/
```

The complete flow is:

```text
budget_type
    │
    ↓
BudgetTypeDao
    │
    ↓
BudgetTypeService
    │
    ↓
BudgetTypeApi
    │
    ↓
app/view/admin/budget-space/budget-type/list/index.php
    │
    ├── create-edit/modal.php
    │
    └── view/modal.php
```

---

# 18. Example: Student Management

If the administrator manages students, the GUI could follow:

```text
app/view/admin/student-space/student/
├── create-edit/
│   └── modal.php
├── list/
│   ├── index.php
│   └── main.js
└── view/
    └── modal.php
```

The corresponding backend should follow:

```text
model/dao/StudentDao.php
model/service/StudentService.php
model/api/StudentApi.php
```

The exact module/space name MUST follow the existing project conventions.

Do not invent a different structure if the project already has an established convention.

---

# 19. CSS Organization

CSS is organized by role.

For the administrator:

```text
app/css/admin/
```

For the student:

```text
app/css/student/
```

For other roles:

```text
app/css/<role>/
```

When creating CSS for an administrator module, place it under:

```text
app/css/admin/
```

Do not put administrator-specific CSS in:

```text
app/css/student/
```

or another role's directory.

Shared CSS can be placed in:

```text
app/css/
```

when it is genuinely shared between roles.

---

# 20. Layout and Menu Organization

Menus and layouts are organized by role.

Administrator:

```text
app/layouts/admin/
```

Student:

```text
app/layouts/student/
```

When adding a new module to the administrator interface, the corresponding navigation should be added to the administrator layout/menu.

For example:

```text
Budget
├── Budget
├── Budget Type
└── Budget Category
```

should be represented in the appropriate administrator menu.

Do not modify another role's menu unless the feature is explicitly intended for that role.

---

# 21. Authentication Organization

Authentication pages are organized by role:

```text
app/cnx/admin/
app/cnx/student/
app/cnx/teacher/
```

For example:

```text
app/cnx/admin/
    → Administrator authentication

app/cnx/student/
    → Student authentication
```

Role-specific authentication MUST remain isolated.

Authentication and authorization MUST NOT be bypassed.

---

# 22. File Placement Rules

Before creating a file, determine:

```text
1. What is the file's responsibility?
2. Is it backend or frontend?
3. Which layer does it belong to?
4. Which role does it belong to?
5. Which business module does it belong to?
6. Which database table does it represent?
```

Then place it according to these rules:

```text
DAO
→ model/dao/

Service
→ model/service/

API / WS
→ model/api/

Authentication
→ app/cnx/<role>/

GUI
→ app/view/<role>/<space>/<table>/

Menu / Layout
→ app/layouts/<role>/

CSS
→ app/css/<role>/

Database structure
→ db/db-structure.sql

Database data
→ db/db-data.sql

Database structure + data
→ db/db-structure-data.sql
```

---

# 23. Existing Code First

Before creating new files, the agent MUST inspect the existing project.

The agent SHOULD search for:

* Similar tables
* Similar DAO classes
* Similar services
* Similar APIs
* Similar GUI modules
* Similar `create-edit/modal.php`
* Similar `list/index.php`
* Similar `list/main.js`
* Similar `view/modal.php`
* Existing CSS
* Existing menus
* Existing database tables

When a similar implementation exists, reuse its structure and conventions.

The existing project is the source of truth.

---

# 24. Do Not Invent Architecture

The agent MUST NOT introduce a new architecture without explicit instruction.

For example, do not replace:

```text
model/dao
model/service
model/api
```

with:

```text
repositories/
controllers/
usecases/
```

unless explicitly requested.

Similarly, do not replace:

```text
create-edit/
list/
view/
```

with another GUI organization.

The existing architecture MUST be preserved.

---

# 25. Business Logic Rules

Business logic belongs primarily in:

```text
model/service/
```

Avoid putting business logic in:

```text
app/view/
app/layouts/
app/cnx/
model/dao/
```

Views should present information and interact with the API.

DAOs should manage persistence.

Services should manage business rules.

APIs should coordinate HTTP/API communication.

---

# 26. Security Rules

Agents MUST:

* Validate user input.
* Prevent SQL injection.
* Use safe database queries.
* Validate authentication.
* Validate authorization.
* Protect role-specific pages.
* Escape user-generated HTML output.
* Never expose passwords or sensitive credentials.
* Never bypass authorization to make a feature work.

Server-side validation is mandatory even if client-side JavaScript validation exists.

---

# 27. Modification Rules

When modifying an existing feature:

1. Understand the existing implementation first.
2. Preserve the existing architecture.
3. Modify only what is necessary.
4. Avoid unrelated refactoring.
5. Reuse existing components.
6. Preserve existing naming conventions.
7. Preserve existing role separation.
8. Verify that existing functionality still works.

---

# 28. New Feature Checklist

For every new feature, verify:

```text
[ ] Identify the business domain.
[ ] Identify the database table(s).
[ ] Inspect db/db-structure.sql.
[ ] Inspect existing data if necessary.
[ ] Identify the application role(s).
[ ] Identify the module/space.
[ ] Check for an existing similar implementation.
[ ] Create/modify DAO.
[ ] Create/modify Service.
[ ] Create/modify API.
[ ] Create the role-specific GUI.
[ ] Create create-edit/modal.php.
[ ] Create list/index.php.
[ ] Create list/main.js.
[ ] Create view/modal.php.
[ ] Update role-specific menu/layout.
[ ] Add/update role-specific CSS.
[ ] Verify authentication.
[ ] Verify authorization.
[ ] Test CRUD operations.
[ ] Test the complete GUI → API → Service → DAO flow.
```

---

# 29. Canonical GUI Pattern

The canonical GUI pattern for a database table is:

```text
app/view/<role>/<space>/<table>/
│
├── create-edit/
│   └── modal.php
│
├── list/
│   ├── index.php
│   └── main.js
│
└── view/
    └── modal.php
```

Example:

```text
app/view/admin/budget-space/budget-type/
│
├── create-edit/
│   └── modal.php
│
├── list/
│   ├── index.php
│   └── main.js
│
└── view/
    └── modal.php
```

`list/index.php` is the main page and includes:

```text
list/main.js
create-edit/modal.php
view/modal.php
```

---

# 30. Final Rules for the Agent

The following rules have priority when modifying this project:

1. **Inspect before modifying.**
2. **Respect the existing architecture.**
3. **Respect the role.**
4. **Respect the business module/space.**
5. **Respect the database table organization.**
6. **Keep DAO, Service and API responsibilities separated.**
7. **Keep GUI organized as `create-edit`, `list`, and `view`.**
8. **Keep role-specific CSS, layouts, authentication and views isolated.**
9. **Use the database SQL files as the source of truth for database structure.**
10. **Reuse existing patterns instead of inventing new ones.**
11. **Do not introduce frameworks or architectural patterns without explicit approval.**
12. **Never bypass authentication or authorization.**
13. **Prefer small, focused modifications over unnecessary rewrites.**
14. **When creating a new CRUD feature, implement the complete flow from GUI to database.**

The fundamental architecture is:

```text
                        UNIVERSITY BUSINESS
                                │
                                ▼
                         DATABASE TABLE
                                │
             ┌──────────────────┼──────────────────┐
             ▼                  ▼                  ▼
            DAO              SERVICE              API
             │                  │                  │
             └──────────────────┼──────────────────┘
                                │
                                ▼
                         ROLE / MODULE
                                │
                                ▼
                       GUI TABLE FOLDER
                                │
              ┌─────────────────┼─────────────────┐
              ▼                 ▼                 ▼
        create-edit/          list/              view/
              │                 │
         modal.php        index.php + main.js
```

This structure MUST be preserved throughout the project unless the user explicitly requests an architectural change.