# Project Rules

These rules must be followed throughout the entire project.

## 1. Minimal Token / Context Usage

Highest priority: before scanning files, ask whether the whole project really needs to be inspected for the task.

If not, inspect only the files directly related to the requested module. For example, if changing Books, inspect only relevant Book Controller, Service, Repository, Model, routes, views, and migrations.

Prefer targeted searches and partial file reads over reading the entire repository. Only scan the whole project when absolutely necessary.

## 2. Architecture

All backend modules must follow:

```text
Controller -> Service -> Repository -> Model
```

Controllers handle requests/responses, validation, and calling Services. Controllers must not contain business logic or direct database queries.

Services contain business logic, transactions, and workflow coordination.

Repositories contain database queries, filters, joins, search, and persistence.

Models contain relationships, casts, and table configuration.

Do not bypass this architecture without approval.

## 3. structure.md

Maintain `structure.md` in the project root. It must always represent the current project structure and include:

- Project Overview
- Frontend Structure
- Backend Structure
- Routes
- Database Tables
- `# ALL JOINS`

For every important table document table name, model, important columns, primary key, foreign keys, and relationships.

Whenever project structure changes, update only the affected part of `structure.md`. Do not rewrite the whole file unnecessarily.

## 4. Keep structure.md Synchronized

Update `structure.md` whenever any of these change:

- Controller
- Service
- Repository
- Model
- Route
- View/page
- Component
- Table
- Important database column
- Foreign key
- Relationship
- Join
- Major folder structure

If nothing structural changed, do not modify `structure.md`.

## 5. Backend Logging

Every meaningful backend process must contain useful debugging logs. Use Laravel logging and `storage/logs/`.

Log important points such as:

- Process started
- Important IDs/context
- Database operation failures
- Process success
- Exceptions

Do not log passwords, tokens, API secrets, private keys, or sensitive data. Avoid noisy logs.

Project logging guidance lives in `config/logs.php`.

## 6. Critical Changes Require Approval

Before making a critical change, stop and ask for approval. Briefly explain:

1. What will change
2. Why
3. Files affected
4. Database impact
5. Possible risk

Critical changes include dropping tables/columns, renaming important columns, changing foreign keys, significantly changing relationships, major architecture changes, authentication changes, removing existing functionality, breaking route/API changes, large refactors, destructive migrations, and mass delete/update operations.

Do not implement critical changes until approved.

## 7. Database Safety

Never use destructive database operations without approval.

Avoid:

- `DROP`
- `TRUNCATE`
- `DELETE` without proper conditions
- `migrate:fresh`
- destructive migrations

Use transactions for multi-step database operations where appropriate.

Never invent database fields or relationships. Verify them from Models, migrations, or schema.

## 8. Frontend Consistency

All new pages must follow the existing Homepage design.

Reuse the existing navbar/header, footer, layout, colors, typography, buttons, spacing, cards, responsive breakpoints, and English/Assamese language system.

Do not redesign global UI unless specifically requested.

## 9. Do Not Modify Unrelated Code

Only modify files required for the current task.

Do not refactor unrelated modules. If another issue is found, mention it separately instead of changing it automatically.

Preserve existing working functionality.

## 10. Validation, Security & Error Handling

Validate all external input. Prefer Laravel Form Requests for important forms.

Follow Laravel security practices:

- Never hardcode secrets
- Never trust user input blindly
- Never build unsafe SQL
- Never expose sensitive errors

Handle exceptions properly and log useful debugging information.

## 11. Performance

Avoid N+1 queries, loading unnecessary data, and fetching whole tables when pagination is appropriate.

Use eager loading, pagination, targeted selects, and efficient repository queries.

## 12. Workflow

Before each task:

1. Read `rules.md` only if needed.
2. Read only the relevant part of `structure.md`.
3. Inspect the minimum necessary files.
4. Implement the requested change.
5. Test/check the affected functionality.
6. Update only the affected section of `structure.md` if structure changed.

Keep responses concise. Do not explain every trivial action. Token efficiency is very important.

## Source of Truth

Actual working project code/database structure is the source of truth.

If `structure.md` becomes outdated, update `structure.md` to match the real project. Do not modify correct working code just to match outdated documentation.