docs: update README with new features on guarded deletes and navigation badges; add documentation for guarded deletes and navigation badge counts

Author: mahmoudmohamedramadan

README.md

@@ -1,6 +1,8 @@
 # Course Hub
 
-> **Filament admin authentication:** Filament admins use a dedicated **`admins`** table and **`admin`** guard, separate from student **`users`** / **`web`**. See **[`docs/FILAMENT_ADMIN_AUTH.md`](docs/FILAMENT_ADMIN_AUTH.md)**.
+> **Filament Admin Authentication** — Uses a dedicated **`admins`** table and **`admin`** guard, isolated from student **`users`** / **`web`**. See **[`docs/FILAMENT_ADMIN_AUTH.md`](docs/FILAMENT_ADMIN_AUTH.md)**.  
+> **Guarded Deletes** — Bulk deletes are blocked when records have **active related data** (e.g. published content or enrollments). See **[`docs/DELETE_ACTIVE_RELATIONS.md`](docs/DELETE_ACTIVE_RELATIONS.md)**.  
+> **Navigation Badges** — Sidebar badges show model counts, cached and updated on create/delete. See **[`docs/FILAMENT_NAVIGATION_BADGE.md`](docs/FILAMENT_NAVIGATION_BADGE.md)**.
 
 A Laravel-based Learning Management System featuring a **student-facing course experience** and a **Filament-powered admin panel**.
 

docs/DELETE_ACTIVE_RELATIONS.md

@@ -0,0 +1,30 @@
+# Guarded Deletes (Filament)
+
+Bulk deletes can break live data (e.g. active courses or enrolled students).
+To prevent this, `DeleteBulkAction` uses a **`before()` hook** to validate each selected record.
+
+If a record has **active relations** (published content, enrollments, etc.):
+
+* A danger **notification** is shown
+* The action is stopped using **`$action->halt()`**
+* Nothing gets deleted
+
+---
+
+## What counts as “active”
+
+* Published courses or lessons
+* Courses with enrolled students
+* Any related data that shouldn’t be removed
+
+---
+
+## Where it’s implemented
+
+* `CategoriesTable`
+* `LevelsTable`
+* `CoursesTable`
+* `LessonsTable`
+* `InstructorsTable`
+
+Path: `app/Filament/Resources/*/Tables/`

docs/FILAMENT_NAVIGATION_BADGE.md

@@ -0,0 +1,29 @@
+# Filament navigation badge counts
+
+Sidebar resources can show a **numeric badge** next to the nav label (total rows for that resource).
+
+## `HasNavigationBadgeCount` (Filament resources)
+
+**File:** `app/Traits/Filament/HasNavigationBadgeCount.php`
+
+Used on **`Resource`** classes (for example `CategoryResource`). It implements:
+
+* **getNavigationBadge()** — returns a string count from **Cache::rememberForever()**. The cache key is the string `filament:nav-badge:` plus the plural lowercased model class basename (for example `courses`) plus `:count`.
+* **getNavigationBadgeColor()** — not read from that cache; it runs a fresh **Model::count()** and maps the result to Filament colors: ≤50 success, ≤100 info, ≤200 warning, above danger.
+* **getNavigationBadgeTooltip()** — short static tooltip for the badge.
+
+## Keeping counts fresh: `UpdatesNavigationBadgeCount` (models)
+
+**File:** `app/Traits/Models/UpdatesNavigationBadgeCount.php`
+
+Used on the **same Eloquent models** those resources represent. On **created** / **deleted**, it **Cache::increment** / **Cache::decrement** using a key built as `filament:nav-badge:` plus **getTable()** plus `:count`.
+
+For Laravel’s default table names, that table segment matches the label segment from the resource trait (for example both use `categories`). If you rename a table or use an irregular plural, ensure both traits still target the **same** cache key or badges will drift.
+
+## Where it is used
+
+**Resources:** `CategoryResource`, `CourseResource`, `LevelResource`, `LessonResource`, `InstructorResource`, `UserResource` — each `use HasNavigationBadgeCount`.
+
+**Models:** `Category`, `Course`, `Level`, `Lesson`, `Instructor`, `User` — each `use UpdatesNavigationBadgeCount`.
+
+To add badges for another resource, reuse both traits (resource + model) or adjust the cache key scheme in one place and mirror it in the other.