fix

app/Console/Commands/SyncSurveyUsers.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\User;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Http;
+
+class SyncSurveyUsers extends Command
+{
+    protected $signature = 'survey:sync-users {--token= : Approagency admin token}';
+    protected $description = 'Sync user profile fields (name, age, gender) from approagency for all meditation users with missing data';
+
+    public function handle()
+    {
+        $token = $this->option('token') ?: config('services.approagency.token');
+
+        if (empty($token)) {
+            $this->error('Provide --token=<approagency_admin_token> or set APPROAGENCY_ADMIN_TOKEN in .env');
+            return 1;
+        }
+
+        $users = User::whereNull('first_name')
+            ->whereNotNull('mobile')
+            ->get();
+
+        $this->info("Found {$users->count()} users with missing first_name. Syncing...");
+
+        $synced = 0;
+        $failed = 0;
+
+        foreach ($users as $user) {
+            $retries = 0;
+            while ($retries <= 3) {
+                try {
+                    $response = Http::withToken($token)
+                        ->retry(2, 2000)
+                        ->get('https://api.approagency.ir/api/admin/users', [
+                            'mobile' => $user->mobile,
+                            'per_page' => 1,
+                        ]);
+
+                    if ($response->status() === 429) {
+                        $retries++;
+                        $wait = $retries * 3;
+                        $this->warn("  rate limited on {$user->mobile}, waiting {$wait}s...");
+                        sleep($wait);
+                        continue;
+                    }
+
+                    if ($response->successful()) {
+                        $data = $response->json('data.0');
+                        if ($data) {
+                            $user->update([
+                                'first_name' => $data['first_name'] ?? $user->first_name,
+                                'last_name' => $data['last_name'] ?? $user->last_name,
+                                'age' => $data['age'] ?? $user->age,
+                                'gender' => $data['gender'] ?? $user->gender,
+                                'birthday' => $data['birthday'] ?? $user->birthday,
+                                'identifier' => $data['uuid'] ?? $user->identifier,
+                            ]);
+                            $name = $data['first_name'] ?? 'null';
+                            $this->line("  synced: {$user->mobile} → {$name}");
+                            $synced++;
+                        }
+                    } else {
+                        $this->warn("  skip: {$user->mobile} (HTTP {$response->status()})");
+                        $failed++;
+                    }
+                    break;
+                } catch (\Exception $e) {
+                    $retries++;
+                    if ($retries > 3) {
+                        $this->error("  failed: {$user->mobile} — {$e->getMessage()}");
+                        $failed++;
+                    } else {
+                        sleep($retries * 2);
+                    }
+                }
+            }
+
+            sleep(3); // 3s between requests
+        }
+
+        $this->info("Done. Synced: {$synced}, Failed: {$failed}");
+        return 0;
+    }
+}

app/Http/Controllers/AnnouncementController.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\Announcement;
+use App\Traits\HandlesImageUpload;
+use Illuminate\Http\Request;
+
+class AnnouncementController extends Controller
+{
+    use HandlesImageUpload;
+
+    // Admin list — every announcement, newest first.
+    public function index()
+    {
+        return response()->json([
+            'data' => Announcement::with('image')->latest()->get(),
+        ]);
+    }
+
+    // App side: only the single latest currently-active announcement (or null).
+    public function latest()
+    {
+        $announcement = Announcement::with('image')
+            ->active()
+            ->orderByDesc('start_date')
+            ->latest()
+            ->first();
+
+        return response()->json(['data' => $announcement]);
+    }
+
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'title' => 'required|string|max:255',
+            'description' => 'nullable|string',
+            'link' => 'nullable|string|max:500',
+            'button_text' => 'nullable|string|max:255',
+            'start_date' => 'nullable|date',
+            'end_date' => 'nullable|date|after_or_equal:start_date',
+            'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+        ]);
+
+        // An uploaded image file takes precedence over a provided image_id.
+        $data['image_id'] = $this->uploadedImageId($request) ?? ($data['image_id'] ?? null);
+
+        $announcement = Announcement::create($data);
+
+        return response()->json([
+            'message' => 'Announcement created successfully',
+            'data' => $announcement->load('image'),
+        ], 201);
+    }
+
+    public function show($id)
+    {
+        return response()->json(
+            Announcement::with('image')->findOrFail($id)
+        );
+    }
+
+    public function update(Request $request, $id)
+    {
+        $announcement = Announcement::findOrFail($id);
+
+        $data = $request->validate([
+            'title' => 'sometimes|string|max:255',
+            'description' => 'nullable|string',
+            'link' => 'nullable|string|max:500',
+            'button_text' => 'nullable|string|max:255',
+            'start_date' => 'nullable|date',
+            'end_date' => 'nullable|date|after_or_equal:start_date',
+            'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+        ]);
+
+        // An uploaded image file takes precedence over a provided image_id.
+        if (($uploadedImageId = $this->uploadedImageId($request)) !== null) {
+            $data['image_id'] = $uploadedImageId;
+        }
+
+        $announcement->update($data);
+
+        return response()->json([
+            'message' => 'Announcement updated successfully',
+            'data' => $announcement->load('image'),
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        $announcement = Announcement::findOrFail($id);
+        $announcement->delete();
+
+        return response()->json(['message' => 'Announcement deleted successfully']);
+    }
+}

app/Http/Controllers/AppFeedbackController.php

@@ -0,0 +1,85 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\AppFeedback;
+use Illuminate\Http\Request;
+use Illuminate\Validation\ValidationException;
+
+class AppFeedbackController extends Controller
+{
+    // USER: get the current user's feedback (null if none yet).
+    public function mine()
+    {
+        $feedback = AppFeedback::where('user_id', auth()->id())->first();
+
+        return response()->json($feedback);
+    }
+
+    // USER: submit or update feedback (one editable row per user).
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'stars' => 'nullable|integer|min:1|max:5',
+            'content' => 'nullable|string|max:2000',
+        ]);
+
+        if (!$request->filled('stars') && !$request->filled('content')) {
+            throw ValidationException::withMessages([
+                'content' => ['Either a rating or a comment is required.'],
+            ]);
+        }
+
+        $feedback = AppFeedback::firstOrNew(['user_id' => auth()->id()]);
+
+        if ($request->has('stars')) {
+            $feedback->stars = $data['stars'] ?? null;
+        }
+        if ($request->has('content')) {
+            $feedback->content = $data['content'] ?? null;
+        }
+
+        $feedback->save();
+
+        return response()->json([
+            'message' => 'Feedback submitted successfully',
+            'feedback' => $feedback,
+        ]);
+    }
+
+    // ADMIN: monitor all feedback, with a summary header.
+    public function adminIndex(Request $request)
+    {
+        $query = AppFeedback::with('user');
+
+        if ($request->filled('has_comment')) {
+            $query->whereNotNull('content')->where('content', '!=', '');
+        }
+        if ($request->filled('stars')) {
+            $query->where('stars', $request->integer('stars'));
+        }
+
+        $feedback = $query->latest()->paginate($request->integer('per_page', 20));
+
+        $base = AppFeedback::query();
+
+        return response()->json([
+            'summary' => [
+                'total' => (clone $base)->count(),
+                'rated' => (clone $base)->whereNotNull('stars')->count(),
+                'with_comment' => (clone $base)->whereNotNull('content')->where('content', '!=', '')->count(),
+                'average_stars' => round((float) (clone $base)->whereNotNull('stars')->avg('stars'), 2),
+            ],
+            'feedback' => $feedback,
+        ]);
+    }
+
+    // ADMIN: remove a feedback entry (moderation).
+    public function adminDestroy($id)
+    {
+        $feedback = AppFeedback::findOrFail($id);
+        $feedback->delete();
+
+        return response()->json(['message' => 'Feedback deleted successfully']);
+    }
+}

app/Http/Controllers/AppVersionController.php

@@ -0,0 +1,95 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\AppVersion;
+use App\Traits\HandlesImageUpload;
+use Illuminate\Http\Request;
+
+class AppVersionController extends Controller
+{
+    use HandlesImageUpload;
+
+    // Admin list — every version, highest version_code first.
+    public function index()
+    {
+        return response()->json([
+            'data' => AppVersion::with('image')->orderByDesc('version_code')->get(),
+        ]);
+    }
+
+    // App side: the newest version (highest version_code) for update checks.
+    public function latest()
+    {
+        return response()->json([
+            'data' => AppVersion::with('image')->orderByDesc('version_code')->first(),
+        ]);
+    }
+
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'title' => 'required|string|max:255',
+            'description' => 'nullable|string',
+            'version_name' => 'required|string|max:255',
+            'version_code' => 'required|integer|min:0',
+            'link' => 'nullable|string|max:500',
+            'button_text' => 'nullable|string|max:255',
+            'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+        ]);
+
+        // An uploaded image file takes precedence over a provided image_id.
+        $data['image_id'] = $this->uploadedImageId($request) ?? ($data['image_id'] ?? null);
+
+        $version = AppVersion::create($data);
+
+        return response()->json([
+            'message' => 'Version created successfully',
+            'data' => $version->load('image'),
+        ], 201);
+    }
+
+    public function show($id)
+    {
+        return response()->json(
+            AppVersion::with('image')->findOrFail($id)
+        );
+    }
+
+    public function update(Request $request, $id)
+    {
+        $version = AppVersion::findOrFail($id);
+
+        $data = $request->validate([
+            'title' => 'sometimes|string|max:255',
+            'description' => 'nullable|string',
+            'version_name' => 'sometimes|string|max:255',
+            'version_code' => 'sometimes|integer|min:0',
+            'link' => 'nullable|string|max:500',
+            'button_text' => 'nullable|string|max:255',
+            'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+        ]);
+
+        // An uploaded image file takes precedence over a provided image_id.
+        if (($uploadedImageId = $this->uploadedImageId($request)) !== null) {
+            $data['image_id'] = $uploadedImageId;
+        }
+
+        $version->update($data);
+
+        return response()->json([
+            'message' => 'Version updated successfully',
+            'data' => $version->load('image'),
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        $version = AppVersion::findOrFail($id);
+        $version->delete();
+
+        return response()->json(['message' => 'Version deleted successfully']);
+    }
+}

app/Http/Controllers/BackgroundSoundController.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\BackgroundSound;
+
+class BackgroundSoundController extends CatalogController
+{
+    protected function modelClass(): string
+    {
+        return BackgroundSound::class;
+    }
+
+    protected function fileFields(): array
+    {
+        return [
+            'sound' => ['column' => 'sound_path', 'folder' => 'background-sounds/sounds', 'rules' => 'nullable|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma|max:102400'],
+            'image' => ['column' => 'image_path', 'folder' => 'background-sounds/images', 'rules' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192'],
+        ];
+    }
+}

app/Http/Controllers/BellSoundController.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\BellSound;
+
+class BellSoundController extends CatalogController
+{
+    protected function modelClass(): string
+    {
+        return BellSound::class;
+    }
+
+    protected function fileFields(): array
+    {
+        return [
+            'sound' => ['column' => 'sound_path', 'folder' => 'bells/sounds', 'rules' => 'nullable|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma|max:51200'],
+            'image' => ['column' => 'image_path', 'folder' => 'bells/images', 'rules' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192'],
+        ];
+    }
+}

app/Http/Controllers/BreathingColorController.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\BreathingColor;
+use Illuminate\Http\Request;
+
+class BreathingColorController extends Controller
+{
+    // Palette the app shows when creating a breathing template.
+    public function index(Request $request)
+    {
+        $query = BreathingColor::query();
+
+        if (!$request->boolean('include_inactive')) {
+            $query->where('is_active', true);
+        }
+
+        return response()->json($query->orderBy('order')->get());
+    }
+
+    public function show($id)
+    {
+        return response()->json(BreathingColor::findOrFail($id));
+    }
+
+    public function store(Request $request)
+    {
+        $data = $this->validateData($request, true);
+
+        $color = BreathingColor::create($data);
+
+        return response()->json([
+            'message' => 'Color created successfully',
+            'color' => $color,
+        ], 201);
+    }
+
+    public function update(Request $request, $id)
+    {
+        $color = BreathingColor::findOrFail($id);
+
+        $color->update($this->validateData($request, false));
+
+        return response()->json([
+            'message' => 'Color updated successfully',
+            'color' => $color,
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        BreathingColor::findOrFail($id)->delete();
+
+        return response()->json(['message' => 'Color deleted successfully']);
+    }
+
+    private function validateData(Request $request, bool $creating): array
+    {
+        return $request->validate([
+            'name' => 'nullable|string|max:255',
+            'colors' => ($creating ? 'required' : 'sometimes') . '|array|min:1',
+            'colors.*' => ['string', 'regex:/^#([A-Fa-f0-9]{3}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/'],
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ]);
+    }
+}

app/Http/Controllers/BreathingExerciseController.php

@@ -19,7 +19,9 @@ public function createTemplate(Request $request)
             'duration' => 'sometimes|integer|min:0',
             'description' => 'sometimes|string|nullable',
             'image_id' => 'nullable|exists:images,id',
-            'source' => 'nullable|string'
+            'source' => 'nullable|string',
+            // The chosen color from the /breathing-colors palette.
+            'breathing_color_id' => 'nullable|exists:breathing_colors,id',
         ]);
 
         $template = BreathingTemplate::create([
@@ -31,16 +33,20 @@ public function createTemplate(Request $request)
             'duration'=> $data['duration'] ?? 60,
             'description' => $data['description'] ?? null,
             'image_id' => $data['image_id'] ?? null,
-            'source' => 'nullable|string'
+            'source' => $data['source'] ?? null,
+            'breathing_color_id' => $data['breathing_color_id'] ?? null,
         ]);
 
-        return response()->json(['message' => 'Template created', 'template' => $template->load('image')]);
+        return response()->json(['message' => 'Template created', 'template' => $template->load('image', 'breathingColor')]);
     }
 
   public function updateTemplate(Request $request, $id)
 {
+    // Editable: the user's own templates OR the shared/global ones (user_id null).
     $template = BreathingTemplate::where('id', $id)
-        ->where('user_id', auth()->id())
+        ->where(function ($q) {
+            $q->where('user_id', auth()->id())->orWhereNull('user_id');
+        })
         ->firstOrFail();
 
     $data = $request->validate([
@@ -51,17 +57,20 @@ public function updateTemplate(Request $request, $id)
         'duration' => 'sometimes|integer|min:0',
         'description' => 'sometimes|string|nullable',
         'image_id' => 'nullable|exists:images,id',
-        'source' => 'nullable|string'
+        'source' => 'nullable|string',
+        'breathing_color_id' => 'nullable|exists:breathing_colors,id',
     ]);
 
     $template->update($data);
 
-    return response()->json(['message' => 'Template updated', 'template' => $template->load('image')]);
+    return response()->json(['message' => 'Template updated', 'template' => $template->load('image', 'breathingColor')]);
 }
     public function deleteTemplate($id)
     {
         $template = BreathingTemplate::where('id', $id)
-            ->where('user_id', auth()->id())
+            ->where(function ($q) {
+                $q->where('user_id', auth()->id())->orWhereNull('user_id');
+            })
             ->firstOrFail();
 
         $template->delete();
@@ -75,7 +84,7 @@ public function getTemplates()
 
     $templates = BreathingTemplate::whereNull('user_id')
         ->orWhere('user_id', $userId)
-        ->with('image') // eager load image
+        ->with(['image', 'breathingColor']) // eager load image + color
         ->get()
         ->map(function ($template) {
             if ($template->image) {
@@ -83,6 +92,8 @@ public function getTemplates()
             } else {
                 $template->image_url = null;
             }
+            // Old app expects a non-null description string.
+            $template->description = $template->description ?? '';
             return $template;
         });
 
@@ -92,7 +103,7 @@ public function getTemplates()
 public function getUserTemplates()
 {
     $templates = BreathingTemplate::where('user_id', auth()->id())
-        ->with('image') // eager load image
+        ->with(['image', 'breathingColor']) // eager load image + color
         ->get()
         ->map(function ($template) {
             if ($template->image) {
@@ -100,6 +111,8 @@ public function getUserTemplates()
             } else {
                 $template->image_url = null;
             }
+            // Old app expects a non-null description string.
+            $template->description = $template->description ?? '';
             return $template;
         });
 
@@ -148,8 +161,8 @@ public function completeSession(Request $request)
             'duration' => $data['duration'] ?? $template->duration,
         ]);
 
-        // Increase XP
-        auth()->user()->increment('xp', 10);
+        // Increase XP (also credits the referrer's 10% share)
+        auth()->user()->awardXp(10);
 
         return response()->json(['message' => 'Session completed', 'session' => $session]);
     }

app/Http/Controllers/CatalogController.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Traits\StoresUploads;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+
+/**
+ * Base controller for simple admin-managed catalogs that hold a name plus
+ * one or more uploaded files (image/sound). Subclasses declare the model
+ * and the file fields.
+ */
+abstract class CatalogController extends Controller
+{
+    use StoresUploads;
+
+    /** @return class-string<\Illuminate\Database\Eloquent\Model> */
+    abstract protected function modelClass(): string;
+
+    /**
+     * Map of request file field => ['column' => db column, 'folder' => storage folder, 'rules' => validation].
+     */
+    abstract protected function fileFields(): array;
+
+    public function index(Request $request)
+    {
+        $query = ($this->modelClass())::query();
+
+        if (!$request->boolean('include_inactive')) {
+            $query->where('is_active', true);
+        }
+
+        return response()->json($query->orderBy('order')->get());
+    }
+
+    public function show($id)
+    {
+        return response()->json(($this->modelClass())::findOrFail($id));
+    }
+
+    public function store(Request $request)
+    {
+        $data = $request->validate(array_merge([
+            'name' => 'required|string|max:255',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ], $this->fileRules()));
+
+        $attributes = [
+            'name' => $data['name'],
+            'order' => $data['order'] ?? 0,
+            'is_active' => $data['is_active'] ?? true,
+        ];
+
+        foreach ($this->fileFields() as $field => $config) {
+            $attributes[$config['column']] = $request->hasFile($field)
+                ? $this->storeUpload($request->file($field), $config['folder'])
+                : null;
+        }
+
+        $item = ($this->modelClass())::create($attributes);
+
+        return response()->json(['message' => 'Created successfully', 'item' => $item], 201);
+    }
+
+    public function update(Request $request, $id)
+    {
+        $item = ($this->modelClass())::findOrFail($id);
+
+        $data = $request->validate(array_merge([
+            'name' => 'sometimes|string|max:255',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ], $this->fileRules()));
+
+        foreach (['name', 'order', 'is_active'] as $field) {
+            if ($request->has($field)) {
+                $item->$field = $data[$field];
+            }
+        }
+
+        foreach ($this->fileFields() as $field => $config) {
+            if ($request->hasFile($field)) {
+                if ($item->{$config['column']}) {
+                    Storage::disk('public')->delete($item->{$config['column']});
+                }
+                $item->{$config['column']} = $this->storeUpload($request->file($field), $config['folder']);
+            }
+        }
+
+        $item->save();
+
+        return response()->json(['message' => 'Updated successfully', 'item' => $item]);
+    }
+
+    public function destroy($id)
+    {
+        $item = ($this->modelClass())::findOrFail($id);
+
+        foreach ($this->fileFields() as $config) {
+            if ($item->{$config['column']}) {
+                Storage::disk('public')->delete($item->{$config['column']});
+            }
+        }
+
+        $item->delete();
+
+        return response()->json(['message' => 'Deleted successfully']);
+    }
+
+    private function fileRules(): array
+    {
+        $rules = [];
+        foreach ($this->fileFields() as $field => $config) {
+            $rules[$field] = $config['rules'];
+        }
+
+        return $rules;
+    }
+}

app/Http/Controllers/CategoryController.php

@@ -3,30 +3,105 @@
 namespace App\Http\Controllers;
 
 use App\Models\Category;
+use App\Models\MusicCategory;
+use App\Traits\StoresUploads;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Validation\Rule;
 
 class CategoryController extends Controller
 {
+    use StoresUploads;
+
     public function index(Request $request)
     {
+        $type = $request->input('type');
+
+        // Playlist categories live in their own table (music_categories); serve
+        // them here too so the front has one /categories entry point.
+        if ($type === Category::TYPE_PLAYLIST) {
+            return response()->json($this->playlistCategories($request)->values());
+        }
+
         $query = Category::query()->withCount('subcategories');
 
+        if ($request->filled('type')) {
+            $query->where('type', $type);
+        }
+
         if ($request->boolean('with_subcategories')) {
             $query->with('subcategories');
         }
 
-        return response()->json(
-            $query->orderBy('name')->get()
-        );
+        $categories = $query->orderBy('order')->orderBy('name')->get();
+
+        // No type filter → also fold in the playlist (music) categories so the
+        // response contains every category across both tables.
+        if (!$request->filled('type')) {
+            $categories = $categories
+                ->concat($this->playlistCategories($request))
+                ->sortBy([['order', 'asc'], ['name', 'asc']])
+                ->values();
+        }
+
+        return response()->json($categories);
+    }
+
+    // Music categories normalized to the generic category shape.
+    private function playlistCategories(Request $request)
+    {
+        $query = MusicCategory::query()->with('image')->withCount('subcategories');
+
+        if (!$request->boolean('include_inactive')) {
+            $query->where('is_active', true);
+        }
+
+        if ($request->boolean('with_subcategories')) {
+            $query->with('subcategories.image');
+        }
+
+        return $query->orderBy('order')->get()->map(function ($c) use ($request) {
+            return [
+                'id' => $c->id,
+                'name' => $c->name,
+                'type' => Category::TYPE_PLAYLIST,
+                'description' => $c->description,
+                'icon' => $c->image?->path,
+                'icon_url' => $c->image?->url,
+                'order' => $c->order,
+                'is_active' => $c->is_active,
+                'subcategories_count' => $c->subcategories_count,
+                'subcategories' => $request->boolean('with_subcategories') ? $c->subcategories : null,
+                'created_at' => $c->created_at,
+                'updated_at' => $c->updated_at,
+            ];
+        });
     }
 
     public function store(Request $request)
     {
         $data = $request->validate([
-            'name' => 'required|string|max:255|unique:categories,name',
+            'name' => [
+                'required',
+                'string',
+                'max:255',
+                Rule::unique('categories', 'name')->where('type', $request->input('type', Category::TYPE_MEDIA)),
+            ],
+            'type' => ['nullable', Rule::in(Category::TYPES)],
+            'order' => 'nullable|integer',
+            'description' => 'nullable|string',
+            'icon' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         ]);
 
-        $category = Category::create($data);
+        $category = Category::create([
+            'name' => $data['name'],
+            'type' => $data['type'] ?? Category::TYPE_MEDIA,
+            'order' => $data['order'] ?? 0,
+            'description' => $data['description'] ?? null,
+            'icon' => $request->hasFile('icon')
+                ? $this->storeUpload($request->file('icon'), 'categories/icons')
+                : null,
+        ]);
 
         return response()->json([
             'message' => 'Category created successfully',
@@ -41,15 +116,75 @@ public function show($id)
         return response()->json($category);
     }
 
+    // Category with each of its sub-categories and that sub-category's medias.
+    public function grouped($id)
+    {
+        $category = Category::with(['subcategories' => function ($q) {
+            $q->orderBy('name')->with(['media' => function ($m) {
+                $m->with(['image', 'detailImage', 'tags'])->latest();
+            }]);
+        }])->findOrFail($id);
+
+        return response()->json([
+            'category' => [
+                'id' => $category->id,
+                'name' => $category->name,
+                'description' => $category->description,
+                'icon_url' => $category->icon_url,
+                'type' => $category->type,
+            ],
+            'sub_categories' => $category->subcategories->map(fn ($sub) => [
+                'sub_category' => [
+                    'id' => $sub->id,
+                    'name' => $sub->name,
+                    'description' => $sub->description,
+                ],
+                'medias' => $sub->media,
+            ])->values(),
+        ]);
+    }
+
     public function update(Request $request, $id)
     {
         $category = Category::findOrFail($id);
 
+        $targetType = $request->input('type', $category->type);
+
         $data = $request->validate([
-            'name' => 'required|string|max:255|unique:categories,name,' . $category->id,
+            'name' => [
+                'sometimes',
+                'string',
+                'max:255',
+                Rule::unique('categories', 'name')
+                    ->where('type', $targetType)
+                    ->ignore($category->id),
+            ],
+            'type' => ['nullable', Rule::in(Category::TYPES)],
+            'order' => 'nullable|integer',
+            'description' => 'nullable|string',
+            'icon' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         ]);
 
-        $category->update($data);
+        if (array_key_exists('type', $data) && $data['type'] !== null) {
+            $category->type = $data['type'];
+        }
+        if (array_key_exists('order', $data) && $data['order'] !== null) {
+            $category->order = $data['order'];
+        }
+        if (array_key_exists('name', $data)) {
+            $category->name = $data['name'];
+        }
+        if (array_key_exists('description', $data)) {
+            $category->description = $data['description'];
+        }
+        if ($request->hasFile('icon')) {
+            if ($category->icon) {
+                Storage::disk('public')->delete($category->icon);
+            }
+            $category->icon = $this->storeUpload($request->file('icon'), 'categories/icons');
+        }
+
+        $category->save();
 
         return response()->json([
             'message' => 'Category updated successfully',
@@ -60,6 +195,11 @@ public function update(Request $request, $id)
     public function destroy($id)
     {
         $category = Category::findOrFail($id);
+
+        if ($category->icon) {
+            Storage::disk('public')->delete($category->icon);
+        }
+
         $category->delete();
 
         return response()->json(['message' => 'Category deleted successfully']);

app/Http/Controllers/ChatTopicController.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\ChatTopic;
+use Illuminate\Http\Request;
+
+class ChatTopicController extends Controller
+{
+    // Suggested chat topics (موضوعات پیشنهادی). Active only unless include_inactive=1.
+    public function index(Request $request)
+    {
+        $query = ChatTopic::query();
+
+        if (!$request->boolean('include_inactive')) {
+            $query->where('is_active', true);
+        }
+
+        return response()->json($query->orderBy('order')->get());
+    }
+
+    public function show($id)
+    {
+        return response()->json(ChatTopic::findOrFail($id));
+    }
+
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'title' => 'required|string|max:255',
+            'description' => 'nullable|string',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        $topic = ChatTopic::create($data);
+
+        return response()->json([
+            'message' => 'Topic created successfully',
+            'topic' => $topic,
+        ], 201);
+    }
+
+    public function update(Request $request, $id)
+    {
+        $topic = ChatTopic::findOrFail($id);
+
+        $data = $request->validate([
+            'title' => 'sometimes|string|max:255',
+            'description' => 'nullable|string',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        $topic->update($data);
+
+        return response()->json([
+            'message' => 'Topic updated successfully',
+            'topic' => $topic,
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        $topic = ChatTopic::findOrFail($id);
+        $topic->delete();
+
+        return response()->json(['message' => 'Topic deleted successfully']);
+    }
+}

app/Http/Controllers/FaqCategoryController.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\FaqCategory;
+use Illuminate\Http\Request;
+
+class FaqCategoryController extends Controller
+{
+    public function index(Request $request)
+    {
+        $query = FaqCategory::query()->withCount('faqs');
+
+        if (!$request->boolean('include_inactive')) {
+            $query->where('is_active', true);
+        }
+
+        return response()->json($query->orderBy('order')->get());
+    }
+
+    public function show($id)
+    {
+        return response()->json(FaqCategory::with('faqs')->withCount('faqs')->findOrFail($id));
+    }
+
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'name' => 'required|string|max:255',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        $category = FaqCategory::create($data);
+
+        return response()->json(['message' => 'FAQ category created', 'category' => $category], 201);
+    }
+
+    public function update(Request $request, $id)
+    {
+        $category = FaqCategory::findOrFail($id);
+
+        $data = $request->validate([
+            'name' => 'sometimes|string|max:255',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        $category->update($data);
+
+        return response()->json(['message' => 'FAQ category updated', 'category' => $category]);
+    }
+
+    public function destroy($id)
+    {
+        FaqCategory::findOrFail($id)->delete(); // faqs cascade
+
+        return response()->json(['message' => 'FAQ category deleted']);
+    }
+}

app/Http/Controllers/FaqController.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\Faq;
+use App\Models\FaqCategory;
+use Illuminate\Http\Request;
+
+class FaqController extends Controller
+{
+    // APP: active FAQ categories, each with their active questions (grouped).
+    // Pass ?include_inactive=1 (admin) to get everything.
+    public function index(Request $request)
+    {
+        $includeInactive = $request->boolean('include_inactive');
+
+        $categories = FaqCategory::query()
+            ->with(['faqs' => function ($q) use ($includeInactive) {
+                if (!$includeInactive) {
+                    $q->where('is_active', true);
+                }
+                $q->orderBy('order');
+            }])
+            ->when(!$includeInactive, fn ($q) => $q->where('is_active', true))
+            ->orderBy('order')
+            ->get();
+
+        return response()->json($categories);
+    }
+
+    public function show($id)
+    {
+        return response()->json(Faq::with('category')->findOrFail($id));
+    }
+
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'faq_category_id' => 'required|exists:faq_categories,id',
+            'question' => 'required|string|max:500',
+            'answer' => 'required|string',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        $faq = Faq::create($data);
+
+        return response()->json(['message' => 'FAQ created', 'faq' => $faq->load('category')], 201);
+    }
+
+    public function update(Request $request, $id)
+    {
+        $faq = Faq::findOrFail($id);
+
+        $data = $request->validate([
+            'faq_category_id' => 'sometimes|exists:faq_categories,id',
+            'question' => 'sometimes|string|max:500',
+            'answer' => 'sometimes|string',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+        ]);
+
+        $faq->update($data);
+
+        return response()->json(['message' => 'FAQ updated', 'faq' => $faq->load('category')]);
+    }
+
+    public function destroy($id)
+    {
+        Faq::findOrFail($id)->delete();
+
+        return response()->json(['message' => 'FAQ deleted']);
+    }
+}

app/Http/Controllers/ImageController.php

@@ -4,21 +4,24 @@
 namespace App\Http\Controllers;
 
 use App\Models\Image;
+use App\Traits\StoresUploads;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Storage;
 
 class ImageController extends Controller
 {
+    use StoresUploads;
+
    public function store(Request $request)
 {
     $data = $request->validate([
-        'image' => 'required|image|max:2048',
+        'image' => 'required|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         'title' => 'nullable|string|max:255',
         'description' => 'nullable|string|max:500',
         'type' => 'nullable|in:public,private',
     ]);
 
-    $path = $request->file('image')->store('images', 'public');
+    $path = $this->storeUpload($request->file('image'), 'images');
 
     $image = Image::create([
         'user_id' => auth()->id(),
@@ -83,7 +86,7 @@ public function update(Request $request, $id)
             'title' => 'nullable|string|max:255',
             'description' => 'nullable|string|max:500',
             'type' => 'nullable|in:public,private',
-            'image' => 'nullable|image|max:2048',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         ]);
 
         if ($request->hasFile('image')) {
@@ -91,7 +94,7 @@ public function update(Request $request, $id)
             Storage::disk('public')->delete($image->path);
 
             // store new one
-            $path = $request->file('image')->store('images', 'public');
+            $path = $this->storeUpload($request->file('image'), 'images');
             $image->path = $path;
         }
 

app/Http/Controllers/InteractionController.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Illuminate\Validation\ValidationException;
+
+class InteractionController extends Controller
+{
+    /**
+     * Comment and/or rate an item in a single request.
+     * Body: { content?: string, stars?: int (1-5) }
+     * - content → adds a comment
+     * - stars   → sets/updates this user's rating
+     * At least one is required.
+     */
+    public function store(Request $request, $type, $id)
+    {
+        $data = $request->validate([
+            'content' => 'nullable|string|max:1000',
+            'stars' => 'nullable|integer|min:1|max:5',
+        ]);
+
+        if (!$request->filled('content') && !$request->filled('stars')) {
+            throw ValidationException::withMessages([
+                'content' => ['Provide a comment (content) and/or a rating (stars).'],
+            ]);
+        }
+
+        $model = $this->getModel($type, $id);
+        if (!$model) {
+            return response()->json(['message' => 'Item not found'], 404);
+        }
+
+        $comment = null;
+        if ($request->filled('content')) {
+            $comment = $model->comments()->create([
+                'user_id' => auth()->id(),
+                'content' => $data['content'],
+            ])->load('user');
+        }
+
+        $rating = null;
+        if ($request->filled('stars')) {
+            $rating = $model->ratings()->updateOrCreate(
+                ['user_id' => auth()->id()],
+                ['stars' => $data['stars']]
+            );
+        }
+
+        $model = $model->fresh();
+
+        return response()->json([
+            'message' => 'Interaction saved successfully',
+            'comment' => $comment,
+            'your_rating' => $rating?->stars,
+            'average_rating' => $model->average_rating,
+            'ratings_count' => $model->ratings_count,
+            'comments_count' => $model->comments_count,
+        ]);
+    }
+
+    private function getModel($type, $id)
+    {
+        // media, music and playlist all support comments + ratings.
+        $models = [
+            'music' => \App\Models\Music::class,
+            'media' => \App\Models\Media::class,
+            'playlist' => \App\Models\MusicPlaylist::class,
+        ];
+
+        $class = $models[$type] ?? null;
+
+        return $class ? $class::find($id) : null;
+    }
+}

app/Http/Controllers/LikeController.php

@@ -3,6 +3,7 @@
 namespace App\Http\Controllers;
 use App\Models\Like;
 use Illuminate\Http\Request;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 class LikeController extends Controller
 {
@@ -94,7 +95,11 @@ public function myLikedItems(Request $request)
     {
         $type = $request->get('type'); // Optional filter by type (music or media)
         
-        $query = Like::with('likeable')
+        $query = Like::with(['likeable' => fn (MorphTo $m) => $m->morphWith([
+                \App\Models\Media::class => ['image', 'detailImage', 'categories', 'subCategories', 'tags'],
+                \App\Models\Music::class => ['image', 'playlists', 'tags'],
+                \App\Models\MusicPlaylist::class => ['image', 'detailImage', 'categories', 'subcategories'],
+            ])])
             ->where('user_id', auth()->id());
         
         if ($type) {

app/Http/Controllers/MediaController.php

@@ -7,12 +7,16 @@
 use App\Models\Category;
 use App\Models\SubCategory;
 use App\Models\Tag;
+use App\Traits\HandlesImageUpload;
+use App\Traits\StoresUploads;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Storage;
 
 class MediaController extends Controller
 {
+    use HandlesImageUpload, StoresUploads;
+
     // CREATE media
     public function store(Request $request)
     {
@@ -25,9 +29,12 @@ public function store(Request $request)
             'subcategory_ids' => 'nullable|array',
             'subcategory_ids.*' => 'integer|exists:sub_categories,id',
             'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+            'detail_image_id' => 'nullable|exists:images,id',
+            'detail_image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
             'duration' => 'nullable|integer',
             'is_premium' => 'nullable|boolean',
-            'file' => 'nullable|mimes:mp3,wav,mp4,mov|max:512000',
+            'file' => 'nullable|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma,mp4,mov,m4v,webm,mkv,avi,3gp|max:512000',
             'external_url' => 'nullable|string',
             'visibility' => 'nullable|in:public,private',
 
@@ -37,17 +44,26 @@ public function store(Request $request)
 
         $path = null;
         if ($request->hasFile('file')) {
-            $path = $request->file('file')->store('media', 'public');
+            $path = $this->storeUpload($request->file('file'), 'media');
         }
 
+        // An uploaded image file takes precedence over a provided image_id.
+        $imageId = $this->uploadedImageId($request) ?? ($data['image_id'] ?? null);
+        $detailImageId = $this->uploadedImageId($request, 'detail_image') ?? ($data['detail_image_id'] ?? null);
+
+        // When a file is uploaded, expose its public URL as external_url too
+        // (older front-end versions read external_url for the playable source).
+        $externalUrl = $path ? asset('storage/' . $path) : ($data['external_url'] ?? null);
+
         $media = Media::create([
             'user_id' => auth()->id(),
             'title' => $data['title'],
             'caption' => $data['caption'] ?? null,
             'type' => $data['type'],
             'file_path' => $path,
-            'external_url' => $data['external_url'] ?? null,
-            'image_id' => $data['image_id'] ?? null,
+            'external_url' => $externalUrl,
+            'image_id' => $imageId,
+            'detail_image_id' => $detailImageId,
             'duration' => $data['duration'] ?? null,
             'visibility' => $data['visibility'] ?? 'public',
             'is_premium'=> $data['is_premium'] ?? false
@@ -68,23 +84,40 @@ public function store(Request $request)
         }
         return response()->json([
             'message' => 'Media created successfully',
-            'media' => $media->load(['image', 'categories', 'subCategories', 'tags']),
+            'media' => $media->load(['image', 'detailImage', 'categories', 'subCategories', 'tags']),
         ]);
     }
 public function index(Request $request)
 {
-    $query = Media::with(['image', 'categories', 'subCategories', 'myNote', 'tags','comments'])
+    $query = Media::with(['image', 'detailImage', 'categories', 'subCategories', 'myNote', 'tags','comments'])
         ->where(function ($q) {
             $q->where('visibility', 'public')
               ->orWhere('user_id', auth()->id());
         });
 
-    /*
-    |--------------------------------------------------------------------------
-    | 1️⃣ Multi Category
-    |--------------------------------------------------------------------------
-    */
+    $this->applyMediaFilters($query, $request);
 
+    $query->orderBy('created_at', 'desc');
+
+    // Optional cap: ?count=10 returns only the first 10 items.
+    if ($request->filled('count')) {
+        $query->limit(max(1, (int) $request->input('count')));
+    }
+
+    $media = $query->get();
+
+    // Old app expects a non-null external_url; fall back to the playable url.
+    $media->each(function ($m) {
+        $m->external_url = $m->external_url ?: ($m->url ?? '');
+    });
+
+    return response()->json($media);
+}
+
+// Apply the category / subcategory / duration / tag / search filters shared by
+// the media list (index) and the filters screen.
+private function applyMediaFilters($query, Request $request)
+{
     if ($request->filled('categories')) {
         $categories = explode(',', $request->categories);
         $query->whereHas('categories', function ($q) use ($categories) {
@@ -99,77 +132,39 @@ public function index(Request $request)
         });
     }
 
-    /*
-    |--------------------------------------------------------------------------
-    | 2️⃣ Multi Duration Ranges
-    |--------------------------------------------------------------------------
-    | duration stored in minutes (integer)
-    |--------------------------------------------------------------------------
-    */
-
+    // Duration ranges (duration stored in minutes). Keys come from durationRanges().
     if ($request->filled('durations')) {
+        $defs = $this->durationRanges();
+        // Keep only known range keys so an unknown value can't produce an empty
+        // (match-everything) WHERE group.
+        $ranges = array_filter(
+            explode(',', $request->durations),
+            fn ($r) => $r === '120-' || isset($defs[$r])
+        );
 
-        $ranges = explode(',', $request->durations);
-
-        $query->where(function ($q) use ($ranges) {
-
+        if (!empty($ranges)) {
+            $query->where(function ($q) use ($ranges, $defs) {
                 foreach ($ranges as $range) {
-
-                if ($range === '1-2') {
-                    $q->orWhereBetween('duration', [1, 2]);
-                }
-
-                if ($range === '2-5') {
-                    $q->orWhereBetween('duration', [3, 5]);
-                }
-
-                if ($range === '5-10') {
-                    $q->orWhereBetween('duration', [6, 10]);
-                }
-                if ($range === '10-30') {
-                    $q->orWhereBetween('duration', [10, 30]);
-                }
-                if ($range === '30-60') {
-                    $q->orWhereBetween('duration', [30, 60]);
-                }
-                 if ($range === '60-120') {
-                    $q->orWhereBetween('duration', [60, 120]);
-                }
-
-                if ($range === 'other') {
-                    $q->orWhere('duration', '>', 120);
+                    if ($range === '120-') {
+                        $q->orWhere('duration', '>', $this->durationOtherMin());
+                    } else {
+                        $q->orWhereBetween('duration', $defs[$range]);
                     }
                 }
-
             });
         }
-
-    /*
-    |--------------------------------------------------------------------------
-    | 3️⃣ Tags
-    |--------------------------------------------------------------------------
-    */
+    }
 
     if ($request->filled('tags')) {
         $tags = explode(',', $request->tags);
-
         $query->whereHas('tags', function ($q) use ($tags) {
             $q->whereIn('name', $tags);
         });
     }
 
-    /*
-    |--------------------------------------------------------------------------
-    | 4️⃣ Search
-    |--------------------------------------------------------------------------
-    */
-
     if ($request->filled('search')) {
-
         $search = $request->search;
-
         $query->where(function ($q) use ($search) {
-
             $q->where('title', 'LIKE', "%$search%")
               ->orWhere('caption', 'LIKE', "%$search%")
               ->orWhereHas('categories', function ($c) use ($search) {
@@ -181,13 +176,47 @@ public function index(Request $request)
               ->orWhereHas('tags', function ($t) use ($search) {
                   $t->where('name', 'LIKE', "%$search%");
               });
-
         });
     }
 
-    return response()->json(
-        $query->orderBy('created_at', 'desc')->get()
-    );
+    return $query;
+}
+
+// Single source of truth for duration buckets (minutes), used by both the
+// filter facet (/media/filters) and the search filter. Non-overlapping.
+// Anything above durationOtherMin() falls into the 'other' bucket.
+private function durationRanges(): array
+{
+    return [
+        '1-2'    => [1, 2],
+        '2-5'    => [3, 5],
+        '5-10'   => [6, 10],
+        '10-30'  => [11, 30],
+        '30-60'  => [31, 60],
+        '60-120' => [61, 120],
+    ];
+}
+
+private function durationOtherMin(): int
+{
+    return 120;
+}
+
+// NEWEST media, paginated (?per_page=, ?page=). Same visibility scope as index.
+public function newest(Request $request)
+{
+    $perPage = (int) $request->input('per_page', 20);
+    $perPage = max(1, min($perPage, 100));
+
+    $media = Media::with(['image', 'detailImage', 'categories', 'subCategories', 'myNote', 'tags'])
+        ->where(function ($q) {
+            $q->where('visibility', 'public')
+              ->orWhere('user_id', auth()->id());
+        })
+        ->orderBy('created_at', 'desc')
+        ->paginate($perPage);
+
+    return response()->json($media);
 }
 
 public function submitFeedback(Request $request, $mediaId)
@@ -287,7 +316,7 @@ public function filters(Request $request)
     $categories = Category::query()
         ->withCount(['media as media_count' => $visibleMedia])
         ->orderByDesc('media_count')
-        ->get(['id', 'name']);
+        ->get(['id', 'name', 'description', 'icon']);
 
     /*
     |--------------------------------------------------------------------------
@@ -298,7 +327,7 @@ public function filters(Request $request)
     $subcategories = SubCategory::query()
         ->withCount(['media as media_count' => $visibleMedia])
         ->orderByDesc('media_count')
-        ->get(['id', 'category_id', 'name']);
+        ->get(['id', 'category_id', 'name', 'description']);
 
 
     /*
@@ -309,27 +338,33 @@ public function filters(Request $request)
     |--------------------------------------------------------------------------
     */
 
-    $durations = Media::select(
-            DB::raw("
-                CASE
-                    WHEN duration BETWEEN 1 AND 2 THEN '1-2'
-                    WHEN duration BETWEEN 3 AND 5 THEN '2-5'
-                    WHEN duration BETWEEN 5 AND 10 THEN '5-10'
-                    WHEN duration BETWEEN 10 AND 20 THEN '10-20'
-                    WHEN duration BETWEEN 20 AND 30 THEN '20-30'
-                    WHEN duration BETWEEN 60 AND 120 THEN '60-120'
-                    ELSE 'other'
-                END as duration_range
-            "),
-            DB::raw('COUNT(*) as total')
-        )
-        ->whereNotNull('duration')
+    // Build the CASE from the same range definitions the search filter uses,
+    // so the facet keys (e.g. "10-30") always match what /media/search accepts.
+    $caseSql = 'CASE ';
+    foreach ($this->durationRanges() as $key => [$min, $max]) {
+        $caseSql .= "WHEN duration BETWEEN {$min} AND {$max} THEN '{$key}' ";
+    }
+    $caseSql .= "WHEN duration > {$this->durationOtherMin()} THEN '120-' END";
+
+    // Counts only for buckets that currently have media.
+    $counts = Media::query()
+        ->select(DB::raw("{$caseSql} as duration_range"), DB::raw('COUNT(*) as total'))
+        ->where('duration', '>', 0)
         ->where(function ($q) {
             $q->where('visibility', 'public')
               ->orWhere('user_id', auth()->id());
         })
         ->groupBy('duration_range')
-        ->get();
+        ->pluck('total', 'duration_range');
+
+    // Always return every range (the UI needs all of them), with 0 when empty.
+    $durations = collect(array_keys($this->durationRanges()))
+        ->push('120-')
+        ->map(fn ($key) => [
+            'duration_range' => $key,
+            'total' => (int) ($counts[$key] ?? 0),
+        ])
+        ->values();
 
     return response()->json([
         'categories'    => $categories,
@@ -338,10 +373,33 @@ public function filters(Request $request)
     ]);
 }
 
+// SEARCH/filter results — paginated. Accepts the same filters as /media
+// (categories, subcategories, durations, tags, search) plus ?page= & ?per_page=.
+public function search(Request $request)
+{
+    $query = Media::with(['image', 'detailImage', 'categories', 'subCategories', 'myNote', 'tags'])
+        ->where(function ($q) {
+            $q->where('visibility', 'public')
+              ->orWhere('user_id', auth()->id());
+        });
+
+    $this->applyMediaFilters($query, $request);
+
+    $perPage = (int) $request->input('per_page', 20);
+    $perPage = max(1, min($perPage, 100));
+
+    $results = $query->orderBy('created_at', 'desc')
+        ->paginate($perPage)
+        ->withQueryString();
+
+    return response()->json($results);
+}
+
    public function show($id)
 {
     $media = Media::with([
             'image',
+            'detailImage',
             'categories',
             'subCategories',
             'myNote',
@@ -367,6 +425,8 @@ public function show($id)
         ->latest()
         ->paginate(15);
 
+    $similarMedia = $this->similarMedia($media);
+
     return response()->json([
         'id' => $media->id,
         'title' => $media->title,
@@ -380,15 +440,21 @@ public function show($id)
         'updated_at' => $media->updated_at,
         'is_premium' => $media->is_premium,
         'image' => $media->image,
+        'detail_image' => $media->detailImage,
         'categories' => $media->categories,
         'sub_categories' => $media->subCategories,
         'tags' => $media->tags,
         'myNote' => $media->myNote,
         'is_saved' => $media->is_saved,
+        'saved_count' => $media->saved_count,
+        'is_liked' => $media->is_liked,
+        'likes_count' => $media->likes_count,
         'statistics' => [
             'average_rating' => $media->average_rating,
             'total_ratings' => $media->ratings_count,
             'total_comments' => $media->comments_count,
+            'total_likes' => $media->likes_count,
+            'total_saves' => $media->saved_count,
             'rating_distribution' => $media->rating_distribution,
         ],
         'user_interaction' => [
@@ -397,10 +463,61 @@ public function show($id)
             'has_commented' => $media->has_user_commented,
             'user_comment' => $media->user_comment,
             'user_comment_id' => $media->user_comment_id,
+            'has_liked' => $media->is_liked,
+            'has_saved' => $media->is_saved,
         ],
         'comments' => $comments,
+        'similar_media' => $similarMedia,
     ]);
 }
+
+// Media that shares categories / subcategories / tags with the given one,
+// ranked by how much they overlap. Excludes the media itself.
+private function similarMedia(Media $media, int $limit = 5)
+{
+    $categoryIds = $media->categories->pluck('id')->all();
+    $subCategoryIds = $media->subCategories->pluck('id')->all();
+    $tagIds = $media->tags->pluck('id')->all();
+
+    if (!$categoryIds && !$subCategoryIds && !$tagIds) {
+        return collect();
+    }
+
+    $userId = auth()->id();
+
+    return Media::query()
+        ->where('media.id', '!=', $media->id)
+        ->where('media.type', $media->type)
+        ->where(function ($q) use ($userId) {
+            $q->where('visibility', 'public')->orWhere('user_id', $userId);
+        })
+        ->where(function ($q) use ($categoryIds, $subCategoryIds, $tagIds) {
+            if ($categoryIds) {
+                $q->orWhereHas('categories', fn ($c) => $c->whereIn('categories.id', $categoryIds));
+            }
+            if ($subCategoryIds) {
+                $q->orWhereHas('subCategories', fn ($s) => $s->whereIn('sub_categories.id', $subCategoryIds));
+            }
+            if ($tagIds) {
+                $q->orWhereHas('tags', fn ($t) => $t->whereIn('tags.id', $tagIds));
+            }
+        })
+        ->withCount([
+            'categories as category_matches' => fn ($c) => $c->whereIn('categories.id', $categoryIds ?: [0]),
+            'subCategories as subcategory_matches' => fn ($s) => $s->whereIn('sub_categories.id', $subCategoryIds ?: [0]),
+            'tags as tag_matches' => fn ($t) => $t->whereIn('tags.id', $tagIds ?: [0]),
+        ])
+        ->with(['image', 'detailImage', 'categories', 'subCategories', 'tags'])
+        // Pull a recent candidate pool (portable; Postgres can't ORDER BY alias
+        // expressions), then rank by overlap in PHP.
+        ->orderByDesc('created_at')
+        ->limit(60)
+        ->get()
+        ->sortByDesc(fn ($m) => $m->category_matches + $m->subcategory_matches + $m->tag_matches)
+        ->take($limit)
+        ->values();
+}
+
 public function rate(Request $request, $mediaId)
 {
     $request->validate([
@@ -469,8 +586,11 @@ public function update(Request $request, $id)
         'subcategory_ids.*' => 'integer|exists:sub_categories,id',
         'is_premium' => 'nullable|boolean',
         'image_id' => 'nullable|exists:images,id',
+        'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+        'detail_image_id' => 'nullable|exists:images,id',
+        'detail_image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         'duration' => 'nullable|integer',
-        'file' => 'nullable|mimes:mp3,wav,mp4,mov|max:512000',
+        'file' => 'nullable|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma,mp4,mov,m4v,webm,mkv,avi,3gp|max:512000',
         'external_url' => 'nullable|string',
         'visibility' => 'nullable|in:public,private',
         'tags' => 'nullable|array',
@@ -479,8 +599,12 @@ public function update(Request $request, $id)
 
     // --- handle file replace ---
     if ($request->hasFile('file')) {
+        if ($media->file_path) {
             Storage::disk('public')->delete($media->file_path);
-        $data['file_path'] = $request->file('file')->store('media', 'public');
+        }
+        $data['file_path'] = $this->storeUpload($request->file('file'), 'media');
+        // Keep external_url pointing at the newly uploaded file for the old front-end.
+        $data['external_url'] = asset('storage/' . $data['file_path']);
     }
 
     // --- Prepare update data ---
@@ -495,15 +619,28 @@ public function update(Request $request, $id)
         'file_path' => $data['file_path'] ?? $media->file_path,
     ];
 
-    // --- Handle image_id specifically ---
-    // If image_id is provided in request, use it (even if null to remove association)
-    // If not provided, keep the existing value
-    if (array_key_exists('image_id', $data)) {
+    // --- Handle image ---
+    // An uploaded image file wins; otherwise an explicit image_id (even null to
+    // clear) is honored; otherwise the existing value is kept.
+    $uploadedImageId = $this->uploadedImageId($request);
+    if ($uploadedImageId !== null) {
+        $updateData['image_id'] = $uploadedImageId;
+    } elseif (array_key_exists('image_id', $data)) {
         $updateData['image_id'] = $data['image_id'];
     } else {
         $updateData['image_id'] = $media->image_id;
     }
 
+    // --- Handle detail image (shown on the show-by-id screen) ---
+    $uploadedDetailImageId = $this->uploadedImageId($request, 'detail_image');
+    if ($uploadedDetailImageId !== null) {
+        $updateData['detail_image_id'] = $uploadedDetailImageId;
+    } elseif (array_key_exists('detail_image_id', $data)) {
+        $updateData['detail_image_id'] = $data['detail_image_id'];
+    } else {
+        $updateData['detail_image_id'] = $media->detail_image_id;
+    }
+
     // --- update media ---
     $media->update($updateData);
 
@@ -528,7 +665,7 @@ public function update(Request $request, $id)
 
     return response()->json([
         'message' => 'Media updated successfully',
-        'media' => $media->load(['image', 'categories', 'subCategories', 'tags']),
+        'media' => $media->load(['image', 'detailImage', 'categories', 'subCategories', 'tags']),
     ]);
 }
 
@@ -539,33 +676,36 @@ public function destroy($id)
             ->where('user_id', auth()->id())
             ->firstOrFail();
 
+        if ($media->file_path) {
             Storage::disk('public')->delete($media->file_path);
+        }
 
         $media->delete();
 
         return response()->json(['message' => 'Media deleted']);
     }
 
-    // SAVE media
+    // SAVE media — uses the shared saved_items system (HasSaves), same as /saves/*.
 public function toggleSaveMedia($id)
 {
-    $user = auth()->user();
+    $media = Media::findOrFail($id);
 
-    if ($user->savedMedia()->where('media_id', $id)->exists()) {
-        // already saved → unsave
-        $user->savedMedia()->detach($id);
-        return response()->json(['message' => 'Unsaved!']);
-    } else {
-        // not saved → save
-        $user->savedMedia()->attach($id);
-        return response()->json(['message' => 'Saved!']);
-    }
+    $media->toggleSaveStatus();
+
+    return response()->json([
+        'message' => $media->is_saved ? 'Saved!' : 'Unsaved!',
+        'is_saved' => $media->is_saved,
+        'saved_count' => $media->saved_count,
+    ]);
 }
 
-    // GET saved
+    // GET saved — media the user saved via saved_items.
     public function saved()
     {
-        return auth()->user()->savedMedia()->with(['image','categories', 'subCategories', 'myNote' , 'tags'])->get();
+        return Media::whereHas('saves', fn ($q) => $q->where('user_id', auth()->id()))
+            ->with(['image','detailImage','categories', 'subCategories', 'myNote' , 'tags'])
+            ->latest()
+            ->get();
     }
 
     // RECORD a play for the current user (feeds popular + recently played).
@@ -603,7 +743,7 @@ public function popular(Request $request)
             })
             ->withCount('plays as listeners_count')                 // distinct users who played
             ->withSum('plays as plays_count', 'play_count')         // total plays
-            ->with(['image', 'categories', 'subCategories', 'tags'])
+            ->with(['image', 'detailImage', 'categories', 'subCategories', 'tags'])
             ->orderByDesc('plays_count')
             ->orderByDesc('listeners_count')
             ->orderByDesc('created_at')
@@ -620,7 +760,7 @@ public function recentlyPlayed(Request $request)
 
         $plays = MediaPlay::where('user_id', auth()->id())
             ->whereNotNull('last_played_at')
-            ->with(['media' => fn ($q) => $q->with(['image', 'categories', 'subCategories', 'tags'])])
+            ->with(['media' => fn ($q) => $q->with(['image', 'detailImage', 'categories', 'subCategories', 'tags'])])
             ->orderByDesc('last_played_at')
             ->limit($limit)
             ->get();

app/Http/Controllers/MoodController.php

@@ -35,7 +35,7 @@ public function storeUserMood(Request $request)
             );
         }
       
-            $user->increment('xp', 10);
+            $user->awardXp(10);
       
         return response()->json([
             'message' => 'Mood saved successfully',

app/Http/Controllers/MusicCategoryController.php

@@ -3,11 +3,14 @@
 namespace App\Http\Controllers;
 use App\Models\MusicPlaylist;
 use App\Models\MusicCategory;
+use App\Traits\HandlesImageUpload;
 use Illuminate\Support\Str;
 use Illuminate\Http\Request;
 
 class MusicCategoryController extends Controller
 {
+    use HandlesImageUpload;
+
     public function index()
     {
         $categories = MusicCategory::with(['image', 'playlists' => function($q) {
@@ -24,10 +27,14 @@ public function store(Request $request)
                 'name' => 'required|string|max:255',
                 'description' => 'nullable|string',
                 'image_id' => 'nullable|exists:images,id',
+                'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
                 'order' => 'nullable|integer',
                 'is_active' => 'nullable|boolean',
             ]);
 
+            // An uploaded image file takes precedence over a provided image_id.
+            $data['image_id'] = $this->uploadedImageId($request) ?? ($data['image_id'] ?? null);
+
             // Check for duplicate name
             $slug = Str::slug($data['name']);
             $existingCategory = MusicCategory::where('slug', $slug)->first();
@@ -89,6 +96,41 @@ public function show($id)
         return response()->json($category);
     }
     
+    // Category with each of its sub-categories and that sub-category's playlists.
+    public function grouped($id)
+    {
+        $category = MusicCategory::with([
+            'image',
+            'subcategories' => function ($q) {
+                $q->orderBy('order')->with([
+                    'image',
+                    'playlists' => function ($p) {
+                        $p->where('is_active', true)->with('image')->orderBy('order');
+                    },
+                ]);
+            },
+        ])->findOrFail($id);
+
+        return response()->json([
+            'category' => [
+                'id' => $category->id,
+                'name' => $category->name,
+                'description' => $category->description,
+                'icon_url' => $category->image?->url,
+                'type' => 'playlist',
+            ],
+            'sub_categories' => $category->subcategories->map(fn ($sub) => [
+                'sub_category' => [
+                    'id' => $sub->id,
+                    'name' => $sub->name,
+                    'description' => $sub->description,
+                    'image_url' => $sub->image?->url,
+                ],
+                'playlists' => $sub->playlists->each(fn ($p) => $p->append('duration')),
+            ])->values(),
+        ]);
+    }
+
     public function update(Request $request, $id)
     {
         $category = MusicCategory::findOrFail($id);
@@ -97,6 +139,7 @@ public function update(Request $request, $id)
             'name' => 'sometimes|string|max:255',
             'description' => 'nullable|string',
             'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
             'order' => 'nullable|integer',
             'is_active' => 'nullable|boolean',
         ]);
@@ -105,6 +148,11 @@ public function update(Request $request, $id)
             $data['slug'] = Str::slug($data['name']);
         }
 
+        // An uploaded image file takes precedence over a provided image_id.
+        if (($uploadedImageId = $this->uploadedImageId($request)) !== null) {
+            $data['image_id'] = $uploadedImageId;
+        }
+
         $category->update($data);
         
         return response()->json([

app/Http/Controllers/MusicController.php

@@ -5,10 +5,13 @@
 use Illuminate\Http\Request;
 use App\Models\MusicPlaylist;
 use App\Models\Music;
+use App\Traits\HandlesImageUpload;
+use App\Traits\StoresUploads;
 use Illuminate\Support\Facades\Storage;
 
 class MusicController extends Controller
 {
+    use HandlesImageUpload, StoresUploads;
 
     // Add this new method to your MusicController
     public function getAllMusic()
@@ -29,23 +32,29 @@ public function getAllMusic()
         return response()->json($music);
     }
 
-    public function index()
+    public function index(Request $request)
     {
         $userId = auth()->id();
 
+        // Paginated so clients don't pull the whole library at once.
+        $perPage = (int) $request->input('per_page', 20);
+        $perPage = max(1, min($perPage, 100));
+
+        // (public) OR (private AND owned by me) — grouped so it stays correct.
         $music = Music::with(['image', 'playlists'])
-            ->where('type', 'public')
-            ->orWhere(function($query) use ($userId) {
-                $query->where('type', 'private')
+            ->where(function ($query) use ($userId) {
+                $query->where('type', 'public')
+                    ->orWhere(function ($q) use ($userId) {
+                        $q->where('type', 'private')
                           ->where('user_id', $userId);
+                    });
             })
             ->orderBy('created_at', 'desc')
-            ->get();
+            ->paginate($perPage);
 
-        return response()->json([
-            'data' => $music,
-            'total' => $music->count()
-        ]);
+        // Laravel's paginator JSON keeps `data` and `total`, and adds
+        // current_page / last_page / per_page for the client.
+        return response()->json($music);
     }
 
 public function getMusicByPlaylist($playlistId)
@@ -132,9 +141,10 @@ public function store(Request $request)
             $data = $request->validate([
                 'title' => 'required|string|max:255',
                 'artist' => 'nullable|string|max:255',
-                'file' => 'required|mimes:mp3,wav,ogg,flac|max:20971520',
+                'file' => 'required|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma|max:20971520',
                 'type' => 'nullable|in:public,private',
                 'image_id' => 'nullable|exists:images,id',
+                'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
                 'playlist_id' => 'nullable|exists:music_playlists,id', // single (backward compatible)
                 'playlist_ids' => 'nullable|array',                    // multiple
                 'playlist_ids.*' => 'integer|exists:music_playlists,id',
@@ -157,7 +167,7 @@ public function store(Request $request)
                 ], 422);
             }
 
-            $path = $file->store('music', 'public');
+            $path = $this->storeUpload($file, 'music');
 
             if (!$path) {
                 return response()->json([
@@ -165,13 +175,16 @@ public function store(Request $request)
                 ], 500);
             }
 
+            // An uploaded image file takes precedence over a provided image_id.
+            $imageId = $this->uploadedImageId($request) ?? ($data['image_id'] ?? null);
+
             $music = Music::create([
                 'user_id' => auth()->id(),
                 'title' => $data['title'],
                 'artist' => $data['artist'] ?? null,
                 'file_path' => $path,
                 'type' => $data['type'] ?? 'private',
-                'image_id' => $data['image_id'] ?? null,
+                'image_id' => $imageId,
                 'duration' => $data['duration'] ?? null, // Store as string
                 'is_active' => true,
             ]);
@@ -232,21 +245,31 @@ public function update(Request $request, $id)
                 'title' => 'nullable|string|max:255',
                 'artist' => 'nullable|string|max:255',
                 'type' => 'nullable|in:public,private',
-                'file' => 'nullable|mimes:mp3,wav,ogg,flac|max:20971520',
+                'file' => 'nullable|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma|max:20971520',
                 'image_id' => 'nullable|exists:images,id',
+                'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
                 'duration' => 'nullable|integer|min:1',
                 'is_active' => 'nullable|boolean',
             ]);
 
             if ($request->hasFile('file')) {
                 // Delete old file
+                if ($music->file_path) {
                     Storage::disk('public')->delete($music->file_path);
-                $path = $request->file('file')->store('music', 'public');
+                }
+                $path = $this->storeUpload($request->file('file'), 'music');
                 $music->file_path = $path;
             }
 
-            // Update only provided fields
-            $music->fill($data);
+            // Update only provided fields (drop the raw file input from mass-assign).
+            $music->fill(collect($data)->except('image')->toArray());
+
+            // An uploaded image file takes precedence over a provided image_id.
+            $uploadedImageId = $this->uploadedImageId($request);
+            if ($uploadedImageId !== null) {
+                $music->image_id = $uploadedImageId;
+            }
+
             $music->save();
 
             return response()->json([
@@ -319,7 +342,9 @@ public function show($id)
     public function destroy($id)
     {
         $music = Music::where('id', $id)->where('user_id', auth()->id())->firstOrFail();
+        if ($music->file_path) {
             Storage::disk('public')->delete($music->file_path);
+        }
         $music->delete();
 
         return response()->json(['message' => 'Music deleted successfully']);

app/Http/Controllers/MusicPlaylistController.php

@@ -3,14 +3,17 @@
 namespace App\Http\Controllers;
 
 use App\Models\MusicPlaylist;
+use App\Traits\HandlesImageUpload;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
 
 class MusicPlaylistController extends Controller
 {
+    use HandlesImageUpload;
+
    public function index(Request $request, $categoryId = null)
         {
-            $query = MusicPlaylist::with(['categories', 'subcategories', 'image']);
+            $query = MusicPlaylist::with(['categories', 'subcategories', 'image', 'detailImage']);
 
             $categoryId = $categoryId ?? $request->input('category_id');
 
@@ -42,8 +45,12 @@ public function store(Request $request)
         'name' => 'required|string|max:255',
         'description' => 'nullable|string',
         'image_id' => 'nullable|exists:images,id',
+        'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+        'detail_image_id' => 'nullable|exists:images,id',
+        'detail_image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         'order' => 'nullable|integer',
         'is_active' => 'nullable|boolean',
+        'is_premium' => 'nullable|boolean',
     ]);
 
     // Ensure at least one category or subcategory is provided
@@ -53,7 +60,11 @@ public function store(Request $request)
         ], 422);
     }
 
-    $data['slug'] = Str::slug($data['name']);
+    $data['slug'] = $this->uniqueSlug($data['name']);
+
+    // An uploaded image file takes precedence over a provided image_id.
+    $data['image_id'] = $this->uploadedImageId($request) ?? ($data['image_id'] ?? null);
+    $data['detail_image_id'] = $this->uploadedImageId($request, 'detail_image') ?? ($data['detail_image_id'] ?? null);
 
     $playlist = MusicPlaylist::create($data);
 
@@ -62,7 +73,7 @@ public function store(Request $request)
 
     return response()->json([
         'message' => 'Playlist created successfully',
-        'playlist' => $playlist->load(['categories', 'subcategories', 'image'])
+        'playlist' => $playlist->load(['categories', 'subcategories', 'image', 'detailImage'])
     ], 201);
 }
     
@@ -72,6 +83,7 @@ public function show($id)
                 'categories',
                 'subcategories',
                 'image',
+                'detailImage',
                 'musics' => function($q) {
                     $q->where('music.is_active', true)
                     ->with(['image', 'tags'])
@@ -87,14 +99,20 @@ public function show($id)
                 ->latest()
                 ->paginate(15);
             
-            return response()->json([
-                'playlist' => $playlist,
+            $playlist->append('duration');
+
+            return response()->json(array_merge(
+                $playlist->toArray(),
+                [
                     'statistics' => [
                         'total_musics' => $playlist->musics->count(),
                         'total_duration' => $playlist->total_duration,
                         'total_comments' => $playlist->comments_count,
                         'total_likes' => $playlist->likes_count,
                         'total_saves' => $playlist->saved_count,
+                        'average_rating' => $playlist->average_rating,
+                        'total_ratings' => $playlist->ratings_count,
+                        'rating_distribution' => $playlist->rating_distribution,
                     ],
                     'user_interaction' => [
                         'has_commented' => $playlist->has_user_commented,
@@ -102,9 +120,12 @@ public function show($id)
                         'user_comment_id' => $playlist->user_comment_id,
                         'has_liked' => $playlist->is_liked,
                         'has_saved' => $playlist->is_saved,
+                        'has_rated' => $playlist->has_user_rated,
+                        'user_rating' => $playlist->user_rating,
                     ],
                     'comments' => $comments,
-            ]);
+                ]
+            ));
         }
     
     public function update(Request $request, $id)
@@ -119,12 +140,24 @@ public function update(Request $request, $id)
             'name' => 'sometimes|string|max:255',
             'description' => 'nullable|string',
             'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+            'detail_image_id' => 'nullable|exists:images,id',
+            'detail_image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
             'order' => 'nullable|integer',
             'is_active' => 'nullable|boolean',
+            'is_premium' => 'nullable|boolean',
         ]);
 
         if (isset($data['name'])) {
-            $data['slug'] = Str::slug($data['name']);
+            $data['slug'] = $this->uniqueSlug($data['name'], $playlist->id);
+        }
+
+        // An uploaded image file takes precedence over a provided image_id.
+        if (($uploadedImageId = $this->uploadedImageId($request)) !== null) {
+            $data['image_id'] = $uploadedImageId;
+        }
+        if (($uploadedDetailImageId = $this->uploadedImageId($request, 'detail_image')) !== null) {
+            $data['detail_image_id'] = $uploadedDetailImageId;
         }
 
         $playlist->update($data);
@@ -139,10 +172,33 @@ public function update(Request $request, $id)
 
         return response()->json([
             'message' => 'Playlist updated successfully',
-            'playlist' => $playlist->load(['categories', 'subcategories', 'image'])
+            'playlist' => $playlist->load(['categories', 'subcategories', 'image', 'detailImage'])
         ]);
     }
     
+    // Build a slug that is unique within music_playlists. Persian names often
+    // transliterate to the same/empty value, so we fall back and add a counter.
+    private function uniqueSlug(string $name, ?int $ignoreId = null): string
+    {
+        $base = Str::slug($name);
+        if ($base === '') {
+            $base = 'playlist';
+        }
+
+        $slug = $base;
+        $i = 2;
+        while (
+            MusicPlaylist::where('slug', $slug)
+                ->when($ignoreId, fn ($q) => $q->where('id', '!=', $ignoreId))
+                ->exists()
+        ) {
+            $slug = "{$base}-{$i}";
+            $i++;
+        }
+
+        return $slug;
+    }
+
     public function destroy($id)
     {
         $playlist = MusicPlaylist::findOrFail($id);

app/Http/Controllers/QuestionController.php

@@ -41,7 +41,48 @@ public function index(Request $request)
         });
     }
 
-        return response()->json($query->get());
+        return response()->json(
+            $query->get()->map(fn ($q) => $this->formatQuestion($q))->values()
+        );
+    }
+
+    /**
+     * Shape a question into the legacy (old Flutter) response: category_id and
+     * category are always present and non-null, tags is always an array, and
+     * timestamps are always ISO strings — so the old client never hits a null.
+     */
+    private function formatQuestion(Question $question): array
+    {
+        $question->loadMissing(['tags', 'category']);
+
+        $createdAt = optional($question->created_at)->toIso8601String();
+        $updatedAt = optional($question->updated_at)->toIso8601String();
+        $categoryId = $question->category_id ?? 0;
+
+        $category = $question->category;
+        $categoryPayload = $category
+            ? [
+                'id' => $category->id,
+                'name' => $category->name ?? '',
+                'created_at' => optional($category->created_at)->toIso8601String() ?? $createdAt,
+                'updated_at' => optional($category->updated_at)->toIso8601String() ?? $updatedAt,
+            ]
+            : [
+                'id' => $categoryId,
+                'name' => '',
+                'created_at' => $createdAt,
+                'updated_at' => $updatedAt,
+            ];
+
+        return [
+            'id' => $question->id,
+            'title' => $question->title ?? '',
+            'category_id' => $categoryId,
+            'created_at' => $createdAt,
+            'updated_at' => $updatedAt,
+            'tags' => $question->tags->values(),
+            'category' => $categoryPayload,
+        ];
     }
 
     /**
@@ -75,7 +116,7 @@ public function store(Request $request)
             $question->tags()->sync($tagIds);
         }
 
-        return response()->json($question->load(['tags', 'category']), 201);
+        return response()->json($this->formatQuestion($question), 201);
     }
 
     /**
@@ -83,7 +124,7 @@ public function store(Request $request)
      */
     public function show(Question $question)
     {
-        return response()->json($question->load(['tags', 'category']));
+        return response()->json($this->formatQuestion($question));
     }
 
     /**
@@ -120,7 +161,7 @@ public function update(Request $request, Question $question)
             $question->tags()->sync($tagIds);
         }
 
-        return response()->json($question->load(['tags', 'category']));
+        return response()->json($this->formatQuestion($question->fresh()));
     }
 
     /**

app/Http/Controllers/SaveController.php

@@ -4,9 +4,22 @@
 
 use Illuminate\Http\Request;
 use App\Models\SavedItem;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 class SaveController extends Controller
 {
+    // Relations to eager-load for each saveable/likeable type so the full
+    // model (with its categories, images, tags, ...) is returned.
+    public static function morphRelations(): array
+    {
+        return [
+            \App\Models\Media::class => ['image', 'detailImage', 'categories', 'subCategories', 'tags'],
+            \App\Models\Music::class => ['image', 'playlists', 'tags'],
+            \App\Models\MusicPlaylist::class => ['image', 'detailImage', 'categories', 'subcategories'],
+            \App\Models\BreathingTemplate::class => ['image', 'breathingColor'],
+        ];
+    }
+
     /**
      * Save an item (music, media, breathing template, etc.)
      */
@@ -95,7 +108,7 @@ public function mySavedItems(Request $request)
     {
         $type = $request->get('type'); // Optional filter by type
         
-        $query = SavedItem::with('saveable')
+        $query = SavedItem::with(['saveable' => fn (MorphTo $m) => $m->morphWith(self::morphRelations())])
             ->where('user_id', auth()->id());
         
         if ($type) {

app/Http/Controllers/SceneController.php

@@ -0,0 +1,167 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\Scene;
+use App\Models\UserSceneSetting;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+
+class SceneController extends Controller
+{
+    // CONSOLIDATED: everything the scene-settings screen needs in one call.
+    public function settings()
+    {
+        $settings = UserSceneSetting::with('activeScene.theme')
+            ->firstOrNew(['user_id' => auth()->id()]);
+
+        return response()->json([
+            'scenes' => Scene::with('theme')->where('is_active', true)->orderBy('order')->get(),
+            'settings' => [
+                'active_scene_id' => $settings->active_scene_id,
+                'active_scene' => $settings->activeScene,
+                'scene_volume' => $settings->scene_volume ?? 100,
+                'background_play_seconds' => $settings->background_play_seconds ?? 0,
+                'video_enabled' => (bool) ($settings->video_enabled ?? false),
+            ],
+        ]);
+    }
+
+    // Persist the current user's scene preferences.
+    public function updateSettings(Request $request)
+    {
+        $data = $request->validate([
+            'active_scene_id' => 'nullable|exists:scenes,id',
+            'scene_volume' => 'nullable|integer|min:0|max:100',
+            'background_play_seconds' => 'nullable|integer|min:0',
+            'video_enabled' => 'nullable|boolean',
+        ]);
+
+        $settings = UserSceneSetting::firstOrNew(['user_id' => auth()->id()]);
+
+        foreach (['active_scene_id', 'scene_volume', 'background_play_seconds', 'video_enabled'] as $field) {
+            if ($request->has($field)) {
+                $settings->$field = $data[$field] ?? ($field === 'video_enabled' ? false : null);
+            }
+        }
+
+        $settings->save();
+
+        return response()->json([
+            'message' => 'Settings saved successfully',
+            'settings' => $settings->load('activeScene'),
+        ]);
+    }
+
+    public function index(Request $request)
+    {
+        $query = Scene::query()->with('theme');
+
+        if (!$request->boolean('include_inactive')) {
+            $query->where('is_active', true);
+        }
+
+        return response()->json($query->orderBy('order')->get());
+    }
+
+    public function show($id)
+    {
+        return response()->json(Scene::with('theme')->findOrFail($id));
+    }
+
+    // CREATE a scene with its image / video / sound uploads.
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'name' => 'required|string|max:255',
+            'theme_id' => 'nullable|exists:themes,id',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+            'is_premium' => 'nullable|boolean',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+            'video' => 'nullable|file|extensions:mp4,mov,webm,mkv,avi,m4v,3gp|max:512000',
+            'sound' => 'nullable|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma|max:51200',
+        ]);
+
+        $scene = Scene::create([
+            'name' => $data['name'],
+            'theme_id' => $data['theme_id'] ?? null,
+            'order' => $data['order'] ?? 0,
+            'is_active' => $data['is_active'] ?? true,
+            'is_premium' => $data['is_premium'] ?? false,
+            'image_path' => $request->hasFile('image') ? $request->file('image')->store('scenes/images', 'public') : null,
+            'video_path' => $request->hasFile('video') ? $request->file('video')->store('scenes/videos', 'public') : null,
+            'sound_path' => $request->hasFile('sound') ? $request->file('sound')->store('scenes/sounds', 'public') : null,
+        ]);
+
+        return response()->json([
+            'message' => 'Scene created successfully',
+            'scene' => $scene->load('theme'),
+        ], 201);
+    }
+
+    // UPDATE a scene; any uploaded file replaces the old one (POST for multipart support).
+    public function update(Request $request, $id)
+    {
+        $scene = Scene::findOrFail($id);
+
+        $data = $request->validate([
+            'name' => 'sometimes|string|max:255',
+            'theme_id' => 'nullable|exists:themes,id',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+            'is_premium' => 'nullable|boolean',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
+            'video' => 'nullable|file|extensions:mp4,mov,webm,mkv,avi,m4v,3gp|max:512000',
+            'sound' => 'nullable|file|extensions:mp3,wav,ogg,flac,aac,m4a,opus,mpga,wma|max:51200',
+        ]);
+
+        if (array_key_exists('name', $data)) {
+            $scene->name = $data['name'];
+        }
+        if (array_key_exists('theme_id', $data)) {
+            $scene->theme_id = $data['theme_id'];
+        }
+        if (array_key_exists('order', $data)) {
+            $scene->order = $data['order'];
+        }
+        if (array_key_exists('is_active', $data)) {
+            $scene->is_active = $data['is_active'];
+        }
+        if (array_key_exists('is_premium', $data)) {
+            $scene->is_premium = $data['is_premium'];
+        }
+
+        foreach (['image' => 'scenes/images', 'video' => 'scenes/videos', 'sound' => 'scenes/sounds'] as $field => $folder) {
+            if ($request->hasFile($field)) {
+                $column = $field === 'image' ? 'image_path' : ($field === 'video' ? 'video_path' : 'sound_path');
+                if ($scene->$column) {
+                    Storage::disk('public')->delete($scene->$column);
+                }
+                $scene->$column = $request->file($field)->store($folder, 'public');
+            }
+        }
+
+        $scene->save();
+
+        return response()->json([
+            'message' => 'Scene updated successfully',
+            'scene' => $scene->load('theme'),
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        $scene = Scene::findOrFail($id);
+
+        foreach (['image_path', 'video_path', 'sound_path'] as $column) {
+            if ($scene->$column) {
+                Storage::disk('public')->delete($scene->$column);
+            }
+        }
+
+        $scene->delete();
+
+        return response()->json(['message' => 'Scene deleted successfully']);
+    }
+}

app/Http/Controllers/SliderController.php

@@ -4,16 +4,49 @@
 
 use Illuminate\Http\Request;
 use App\Models\Slider;
+use App\Traits\HandlesImageUpload;
 
 class SliderController extends Controller
 {
+    use HandlesImageUpload;
+
     public function index()
     {
         return response()->json([
-            'data' => Slider::all()
+            'data' => Slider::with('image')->get()->map(fn ($s) => $this->formatSlider($s))->values(),
         ]);
     }
 
+    // Shape a slider so the (old) app parses it safely: description is always a
+    // string, and action.type is normalized to 'navigation' or 'link' (the only
+    // types the client understands) — unknown/empty actions become null.
+    private function formatSlider(Slider $slider): array
+    {
+        return array_merge($slider->toArray(), [
+            'description' => $slider->description ?? '',
+            'action' => $this->normalizeAction($slider->action),
+        ]);
+    }
+
+    private function normalizeAction($action): ?array
+    {
+        if (!is_array($action) || empty($action['type'])) {
+            return null;
+        }
+
+        $type = $action['type'];
+
+        if (in_array($type, ['navigation', 'screen'], true)) {
+            return ['type' => 'navigation', 'path' => $action['path'] ?? ($action['url'] ?? '')];
+        }
+
+        if (in_array($type, ['link', 'url'], true)) {
+            return ['type' => 'link', 'url' => $action['url'] ?? ($action['path'] ?? '')];
+        }
+
+        return null; // unknown type → drop so the client doesn't throw
+    }
+
     public function store(Request $request)
     {
         $data = $request->validate([
@@ -21,20 +54,25 @@ public function store(Request $request)
             'description' => 'nullable|string',
             'url' => 'nullable|string|max:500',
             'action' => 'nullable|array',
+            'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         ]);
 
+        // An uploaded image file takes precedence over a provided image_id.
+        $data['image_id'] = $this->uploadedImageId($request) ?? ($data['image_id'] ?? null);
+
         $slider = Slider::create($data);
 
         return response()->json([
             'message' => 'Slider created successfully',
-            'data' => $slider
+            'data' => $this->formatSlider($slider->load('image')),
         ]);
     }
 
     public function show($id)
     {
-        $slider = Slider::findOrFail($id);
-        return response()->json($slider);
+        $slider = Slider::with('image')->findOrFail($id);
+        return response()->json($this->formatSlider($slider));
     }
 
     public function update(Request $request, $id)
@@ -46,13 +84,20 @@ public function update(Request $request, $id)
             'description' => 'sometimes|string',
             'url' => 'sometimes|string|max:500',
             'action' => 'nullable|array',
+            'image_id' => 'nullable|exists:images,id',
+            'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
         ]);
 
+        // An uploaded image file takes precedence over a provided image_id.
+        if (($uploadedImageId = $this->uploadedImageId($request)) !== null) {
+            $data['image_id'] = $uploadedImageId;
+        }
+
         $slider->update($data);
 
         return response()->json([
             'message' => 'Slider updated successfully',
-            'data' => $slider
+            'data' => $this->formatSlider($slider->load('image')),
         ]);
     }
 

app/Http/Controllers/SubCategoryController.php

@@ -27,6 +27,7 @@ public function store(Request $request)
         $data = $request->validate([
             'category_id' => 'required|exists:categories,id',
             'name' => 'required|string|max:255',
+            'description' => 'nullable|string',
         ]);
 
         $existing = SubCategory::where('category_id', $data['category_id'])
@@ -62,6 +63,7 @@ public function update(Request $request, $id)
         $data = $request->validate([
             'category_id' => 'sometimes|exists:categories,id',
             'name' => 'sometimes|string|max:255',
+            'description' => 'nullable|string',
         ]);
 
         $categoryId = $data['category_id'] ?? $subCategory->category_id;

app/Http/Controllers/SurveyQuestionController.php

@@ -6,8 +6,10 @@
 use App\Models\SurveyAnswer;
 use App\Models\SurveyQuestion;
 use App\Models\Tag;
+use App\Models\User;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
 use Illuminate\Validation\ValidationException;
 
 class SurveyQuestionController extends Controller
@@ -56,6 +58,104 @@ public function adminShow($id)
         return response()->json($question);
     }
 
+    // ADMIN: paginated list of users with their survey stats (age, gender, answers count).
+    public function adminUsers(Request $request)
+    {
+        $perPage = max(1, min((int) $request->input('per_page', 20), 100));
+        $answered = $request->input('answered');
+
+        $query = User::select('id', 'first_name', 'last_name', 'age', 'gender', 'email', 'mobile', 'created_at', 'identifier')
+            ->withCount(['surveyAnswers as answers_count'])
+            ->withCount(['surveyAnswers as questions_answered' => function ($q) {
+                $q->select(DB::raw('COUNT(DISTINCT survey_question_id)'));
+            }])
+            ->orderByDesc('created_at');
+
+        if ($answered === '1') {
+            $query->has('surveyAnswers');
+        } elseif ($answered === '0') {
+            $query->doesntHave('surveyAnswers');
+        }
+
+        $users = $query->paginate($perPage);
+
+        return response()->json($users);
+    }
+
+    // ADMIN: single user profile with all their survey answers grouped by question.
+    // Accepts either local user ID or approagency identifier (UUID).
+    public function adminUserShow($identifier)
+    {
+        $query = User::query()
+            ->select('id', 'first_name', 'last_name', 'age', 'gender', 'birthday', 'email', 'mobile', 'created_at')
+            ->withCount(['surveyAnswers as answers_count'])
+            ->withCount(['surveyAnswers as questions_answered' => function ($q) {
+                $q->select(DB::raw('COUNT(DISTINCT survey_question_id)'));
+            }]);
+
+        if (is_numeric($identifier)) {
+            $query->where('id', $identifier);
+        } else {
+            $query->where('identifier', $identifier);
+        }
+
+        $user = $query->first();
+
+        if (!$user) {
+            abort(404);
+        }
+
+        $answers = SurveyAnswer::where('user_id', $user->id)
+            ->with(['question.options', 'option'])
+            ->get()
+            ->groupBy('survey_question_id')
+            ->map(function ($group) {
+                $question = $group->first()->question;
+                return [
+                    'question_id' => $question->id,
+                    'question' => $question->question,
+                    'type' => $question->type,
+                    'answers' => $group->map(fn ($a) => [
+                        'option_id' => $a->survey_option_id,
+                        'label' => $a->option->label,
+                    ])->values(),
+                ];
+            })
+            ->values();
+
+        $user->survey_answers = $answers;
+
+        return response()->json($user);
+    }
+
+    // ADMIN: update a user's profile fields from approagency data.
+    public function adminUserUpdate(Request $request, $identifier)
+    {
+        if (is_numeric($identifier)) {
+            $user = User::where('id', $identifier)->first();
+        } else {
+            $user = User::where('identifier', $identifier)->first();
+        }
+
+        if (!$user) {
+            abort(404);
+        }
+
+        $data = $request->validate([
+            'first_name' => 'nullable|string',
+            'last_name' => 'nullable|string',
+            'age' => 'nullable|integer',
+            'gender' => 'nullable|integer',
+            'birthday' => 'nullable|string',
+            'identifier' => 'nullable|string',
+            'email' => 'nullable|email',
+        ]);
+
+        $user->update(array_filter($data, fn ($v) => !is_null($v)));
+
+        return response()->json($user);
+    }
+
     // ADMIN: clean aggregated results — per option vote counts & percentages, no raw rows.
     // Pass an $id for one question, omit it for all questions.
     public function adminAnalytics($id = null)
@@ -193,48 +293,21 @@ public function destroy($id)
         return response()->json(['message' => 'Question deleted successfully']);
     }
 
-    // USER submits their answer(s) for a question.
+    // USER submits their answer(s) for a single question.
+    // An empty option_ids array (or omitting it) means "no answer" / skip.
     public function answer(Request $request, $id)
     {
         $question = SurveyQuestion::findOrFail($id);
 
         $data = $request->validate([
-            'option_ids' => 'required|array|min:1',
+            'option_ids' => 'nullable|array',
             'option_ids.*' => 'integer',
         ]);
 
-        $optionIds = array_values(array_unique($data['option_ids']));
-
-        // Every selected option must belong to this question.
-        $validOptionIds = $question->options()->pluck('id')->all();
-        if (array_diff($optionIds, $validOptionIds)) {
-            throw ValidationException::withMessages([
-                'option_ids' => ['One or more options do not belong to this question.'],
-            ]);
-        }
-
-        // Enforce single vs multiple selection.
-        if ($question->type === 'single' && count($optionIds) > 1) {
-            throw ValidationException::withMessages([
-                'option_ids' => ['This question allows only a single option.'],
-            ]);
-        }
-
         $userId = auth()->id();
 
-        DB::transaction(function () use ($question, $optionIds, $userId) {
-            // Replace any previous answer for this user + question.
-            $question->answers()->where('user_id', $userId)->delete();
-
-            $rows = array_map(fn ($optionId) => [
-                'user_id' => $userId,
-                'survey_question_id' => $question->id,
-                'survey_option_id' => $optionId,
-                'created_at' => now(),
-                'updated_at' => now(),
-            ], $optionIds);
-
-            $question->answers()->getRelated()->insert($rows);
+        DB::transaction(function () use ($question, $data, $userId) {
+            $this->syncAnswerFor($question, $data['option_ids'] ?? [], $userId);
         });
 
         return response()->json([
@@ -243,45 +316,166 @@ public function answer(Request $request, $id)
         ]);
     }
 
+    // USER submits answers for many questions at once. Each item may carry an
+    // empty option_ids (skip), and the whole answers array may be empty too.
+    public function bulkAnswer(Request $request)
+    {
+        $data = $request->validate([
+            'answers' => 'present|array',
+            'answers.*.question_id' => 'required|integer|exists:survey_questions,id',
+            'answers.*.option_ids' => 'nullable|array',
+            'answers.*.option_ids.*' => 'integer',
+        ]);
+
+        $userId = auth()->id();
+        $items = $data['answers'] ?? [];
+
+        $questions = SurveyQuestion::with('options')
+            ->whereIn('id', collect($items)->pluck('question_id')->unique()->all())
+            ->get()
+            ->keyBy('id');
+
+        DB::transaction(function () use ($items, $questions, $userId) {
+            foreach ($items as $item) {
+                $question = $questions->get($item['question_id']);
+                if (!$question) {
+                    continue;
+                }
+                $this->syncAnswerFor($question, $item['option_ids'] ?? [], $userId);
+            }
+        });
+
+        return response()->json([
+            'message' => 'Answers submitted successfully',
+            'questions' => SurveyQuestion::with(['options', 'userAnswers'])
+                ->where('is_active', true)
+                ->orderBy('order')
+                ->get(),
+        ]);
+    }
+
+    // Validate and replace a single user's answer set for one question.
+    // Empty $optionIds clears the answer (the user chose not to answer it).
+    private function syncAnswerFor(SurveyQuestion $question, array $optionIds, int $userId): void
+    {
+        $optionIds = array_values(array_unique(array_map('intval', $optionIds)));
+
+        // Every selected option must belong to this question.
+        $validOptionIds = $question->options()->pluck('id')->all();
+        if (array_diff($optionIds, $validOptionIds)) {
+            throw ValidationException::withMessages([
+                'option_ids' => ["One or more options do not belong to question #{$question->id}."],
+            ]);
+        }
+
+        // Enforce single vs multiple selection.
+        if ($question->type === 'single' && count($optionIds) > 1) {
+            throw ValidationException::withMessages([
+                'option_ids' => ["Question #{$question->id} allows only a single option."],
+            ]);
+        }
+
+        // Replace any previous answer for this user + question.
+        $question->answers()->where('user_id', $userId)->delete();
+
+        if ($optionIds) {
+            $now = now();
+            $rows = array_map(fn ($optionId) => [
+                'user_id' => $userId,
+                'survey_question_id' => $question->id,
+                'survey_option_id' => $optionId,
+                'created_at' => $now,
+                'updated_at' => $now,
+            ], $optionIds);
+
+            $question->answers()->getRelated()->insert($rows);
+        }
+    }
+
     // USER: suggest media based on the tags attached to the options this user has chosen.
     public function suggestedMedia(Request $request)
     {
         $userId = auth()->id();
 
+        $limit = (int) $request->input('limit', 20);
+        $limit = max(1, min($limit, 100));
+
         $answersQuery = SurveyAnswer::where('user_id', $userId);
         if ($request->filled('question_id')) {
             $answersQuery->where('survey_question_id', $request->question_id);
         }
         $optionIds = $answersQuery->pluck('survey_option_id');
 
-        if ($optionIds->isEmpty()) {
-            return response()->json([]);
-        }
-
-        // Collect the tags behind the chosen options.
-        $tagIds = DB::table('survey_option_tag')
+        // Tags behind the user's chosen options.
+        $tagIds = $optionIds->isEmpty()
+            ? collect()
+            : DB::table('survey_option_tag')
                 ->whereIn('survey_option_id', $optionIds)
                 ->pluck('tag_id')
                 ->unique()
                 ->values();
 
-        if ($tagIds->isEmpty()) {
-            return response()->json([]);
-        }
+        // Visible to this user: public or their own.
+        $visible = function ($q) use ($userId) {
+            $q->where('visibility', 'public')->orWhere('user_id', $userId);
+        };
 
-        // Media sharing those tags, ranked by how many of them match.
-        $media = Media::query()
+        $eager = ['image', 'detailImage', 'categories', 'subCategories', 'tags'];
+
+        $media = collect();
+
+        if ($tagIds->isNotEmpty()) {
+            // 1) Media directly sharing the chosen tags, ranked by overlap.
+            $tagMatched = Media::query()
                 ->whereHas('tags', fn ($q) => $q->whereIn('tags.id', $tagIds))
                 ->withCount(['tags as match_count' => fn ($q) => $q->whereIn('tags.id', $tagIds)])
-            ->where(function ($q) use ($userId) {
-                $q->where('visibility', 'public')->orWhere('user_id', $userId);
-            })
-            ->with(['image', 'categories', 'subCategories', 'tags'])
+                ->where($visible)
+                ->with($eager)
                 ->orderByDesc('match_count')
                 ->orderByDesc('created_at')
                 ->get();
 
-        return response()->json($media);
+            // 2) Broaden to "similar" media: same categories / sub-categories as
+            //    the tag-matched media (so a thinly-tagged catalog still surfaces
+            //    the rest of the topic, not just the one over-tagged item).
+            $categoryIds = $tagMatched->pluck('categories')->flatten(1)->pluck('id')->unique()->values();
+            $subCategoryIds = $tagMatched->pluck('subCategories')->flatten(1)->pluck('id')->unique()->values();
+
+            $similar = collect();
+            if ($categoryIds->isNotEmpty() || $subCategoryIds->isNotEmpty()) {
+                $similar = Media::query()
+                    ->where($visible)
+                    ->whereNotIn('id', $tagMatched->pluck('id'))
+                    ->where(function ($q) use ($categoryIds, $subCategoryIds) {
+                        if ($categoryIds->isNotEmpty()) {
+                            $q->orWhereHas('categories', fn ($c) => $c->whereIn('categories.id', $categoryIds));
+                        }
+                        if ($subCategoryIds->isNotEmpty()) {
+                            $q->orWhereHas('subCategories', fn ($s) => $s->whereIn('sub_categories.id', $subCategoryIds));
+                        }
+                    })
+                    ->with($eager)
+                    ->orderByDesc('created_at')
+                    ->get()
+                    ->each(fn ($m) => $m->match_count = 0);
+            }
+
+            $media = $tagMatched->concat($similar);
+        }
+
+        // Fallback (no answers / no tags / nothing matched): popular public media,
+        // so the suggestions row is never empty.
+        if ($media->isEmpty()) {
+            $media = Media::query()
+                ->where($visible)
+                ->withCount('plays as plays_count')
+                ->with($eager)
+                ->orderByDesc('plays_count')
+                ->orderByDesc('created_at')
+                ->get();
+        }
+
+        return response()->json($media->take($limit)->values());
     }
 
     private function syncOptions(SurveyQuestion $question, array $options): void

app/Http/Controllers/ThemeController.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\Theme;
+use Illuminate\Http\Request;
+
+class ThemeController extends Controller
+{
+    // List themes (for the scene theme picker and the app).
+    public function index(Request $request)
+    {
+        $query = Theme::query();
+
+        if (!$request->boolean('include_inactive')) {
+            $query->where('is_active', true);
+        }
+
+        return response()->json($query->orderBy('order')->get());
+    }
+
+    public function show($id)
+    {
+        return response()->json(Theme::findOrFail($id));
+    }
+
+    // Edit an existing theme — typically its color map. The `key` is the stable
+    // identifier the app maps against, so it is intentionally not editable here.
+    public function update(Request $request, $id)
+    {
+        $theme = Theme::findOrFail($id);
+
+        $data = $request->validate([
+            'name' => 'sometimes|string|max:255',
+            'colors' => 'sometimes|array',
+            'colors.*' => 'nullable|string|max:32',
+            'order' => 'sometimes|integer',
+            'is_active' => 'sometimes|boolean',
+        ]);
+
+        $theme->update($data);
+
+        return response()->json([
+            'message' => 'Theme updated successfully',
+            'data' => $theme,
+        ]);
+    }
+}

app/Http/Controllers/TimerPresetController.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\BackgroundSound;
+use App\Models\BellSound;
+use App\Models\Image;
+use App\Models\TimerPreset;
+use Illuminate\Http\Request;
+
+class TimerPresetController extends Controller
+{
+    // All catalogs needed to build a timer (pickers), in one call.
+    public function options()
+    {
+        return response()->json([
+            'bell_sounds' => BellSound::where('is_active', true)->orderBy('order')->get(),
+            'background_sounds' => BackgroundSound::where('is_active', true)->orderBy('order')->get(),
+            'background_images' => Image::where('type', 'public')->get(),
+        ]);
+    }
+
+    // USER: their saved timers (ذخیره‌شده‌های من).
+    public function index()
+    {
+        $presets = TimerPreset::with(TimerPreset::RELATIONS)
+            ->where('user_id', auth()->id())
+            ->latest()
+            ->get();
+
+        return response()->json($presets);
+    }
+
+    public function show($id)
+    {
+        $preset = TimerPreset::with(TimerPreset::RELATIONS)
+            ->where('user_id', auth()->id())
+            ->findOrFail($id);
+
+        return response()->json($preset);
+    }
+
+    public function store(Request $request)
+    {
+        $data = $this->validatePreset($request);
+
+        $preset = TimerPreset::create($data + ['user_id' => auth()->id()]);
+
+        return response()->json([
+            'message' => 'Timer saved successfully',
+            'preset' => $preset->load(TimerPreset::RELATIONS),
+        ], 201);
+    }
+
+    public function update(Request $request, $id)
+    {
+        $preset = TimerPreset::where('user_id', auth()->id())->findOrFail($id);
+
+        $data = $this->validatePreset($request, false);
+
+        $preset->fill($data)->save();
+
+        return response()->json([
+            'message' => 'Timer updated successfully',
+            'preset' => $preset->load(TimerPreset::RELATIONS),
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        $preset = TimerPreset::where('user_id', auth()->id())->findOrFail($id);
+        $preset->delete();
+
+        return response()->json(['message' => 'Timer deleted successfully']);
+    }
+
+    private function validatePreset(Request $request, bool $creating = true): array
+    {
+        $required = $creating ? 'required' : 'sometimes';
+
+        return $request->validate([
+            'name' => "$required|string|max:255",
+            'duration_seconds' => "$required|integer|min:1",
+            'start_bell_id' => 'nullable|exists:bell_sounds,id',
+            'end_bell_id' => 'nullable|exists:bell_sounds,id',
+            'interval_bell_id' => 'nullable|exists:bell_sounds,id',
+            'interval_seconds' => 'nullable|integer|min:1',
+            'interval_repeat' => 'nullable|integer|min:1',
+            'background_sound_id' => 'nullable|exists:background_sounds,id',
+            'background_image_id' => 'nullable|exists:images,id',
+            'volume' => 'nullable|integer|min:0|max:100',
+        ]);
+    }
+}

app/Http/Controllers/UserController.php

@@ -44,10 +44,16 @@ public function loginV2(Request $request)
             $user = User::where('identifier', $response['uuid'])->first();
         }
 
-        // If not found, try by email
-        if (!$user) {
+        // Then by email — only when an email exists. (where('email', null) would
+        // match an arbitrary mobile-only user and cross-link the wrong account.)
+        if (!$user && !empty($response['email'])) {
             $user = User::where('email', $response['email'])->first();
         }
+
+        // Finally by mobile, so mobile-only users reconnect to their account
+        if (!$user && !empty($response['mobile'])) {
+            $user = User::where('mobile', $response['mobile'])->first();
+        }
         $mobile = $response['mobile'] ?? null;
 
     // If mobile already exists, set it null to avoid duplicate error
@@ -60,28 +66,52 @@ public function loginV2(Request $request)
             'email' => $response['email'],
             'identifier' => $response['uuid'] ?? null,
             'password' => config('app.default_password'),
-            // 'name' => trim(($response['first_name'] ?? '') . ' ' . ($response['last_name'] ?? '')),
             'mobile' => $mobile,
             'first_name' => $response['first_name'] ?? null,
-            'last_name' => $response['last_name'] ?? null
+            'last_name' => $response['last_name'] ?? null,
+            'age' => $response['age'] ?? null,
+            'gender' => $response['gender'] ?? null,
+            'birthday' => $response['birthday'] ?? null,
+            'referral_code' => $response['referral_code'] ?? null,
         ]);
     } else {
-        // Only update name and mobile for existing user
-        $user->first_name = $response['first_name'] ?? $user->first_name;
-        $user->last_name = $response['last_name'] ?? $user->last_name;
-        // $user->name = trim(($response['first_name'] ?? '') . ' ' . ($response['last_name'] ?? ''));
+        // Keep the local identifier aligned with the current approagency uuid
+        // (e.g. when the user was matched by mobile, not identifier).
+        $user->identifier = $response['uuid'] ?? $user->identifier;
+
+        // Sync names — update if the response has a non-null, non-empty value
+        if (!empty($response['first_name'])) {
+            $user->first_name = $response['first_name'];
+        }
+        if (!empty($response['last_name'])) {
+            $user->last_name = $response['last_name'];
+        }
+
         $user->mobile = $mobile ?? $user->mobile;
+        $user->age = $response['age'] ?? $user->age;
+        $user->gender = $response['gender'] ?? $user->gender;
+        $user->birthday = $response['birthday'] ?? $user->birthday;
+        $user->referral_code = $response['referral_code'] ?? $user->referral_code;
         $user->save();
     }
 
+        // Link the referral relationship and reward the referrer (کد معرف)
+        $this->linkReferral($user, $response);
 
         $access_token = $user->createToken('user')->plainTextToken;
 
+        // Whether this user has answered any survey question.
+        $user->setAttribute(
+            'has_answered_survey',
+            \App\Models\SurveyAnswer::where('user_id', $user->id)->exists()
+        );
+
         return [
             'email' => $user->email,
             'identifier' => $user->identifier,
             'token' => $access_token,
             'user' => $user,
+            'status' => $response,
         ];
     }
     
@@ -95,6 +125,9 @@ private function syncUserFromStatus(array $response, ?User $user = null): User
         if (!$user && !empty($response['email'])) {
             $user = User::where('email', $response['email'])->first();
         }
+        if (!$user && !empty($response['mobile'])) {
+            $user = User::where('mobile', $response['mobile'])->first();
+        }
     }
 
     $mobile = $response['mobile'] ?? null;
@@ -111,20 +144,89 @@ private function syncUserFromStatus(array $response, ?User $user = null): User
             'mobile' => $mobile,
             'first_name' => $response['first_name'] ?? null,
             'last_name' => $response['last_name'] ?? null,
+            'age' => $response['age'] ?? null,
+            'gender' => $response['gender'] ?? null,
+            'birthday' => $response['birthday'] ?? null,
+            'referral_code' => $response['referral_code'] ?? null,
             'email_verified_at' => $response['email_verified_at'] ?? null
         ]);
     } else {
         // update existing
-        $user->first_name = $response['first_name'] ?? $user->first_name;
-        $user->last_name  = $response['last_name'] ?? $user->last_name;
+        $user->identifier = $response['uuid'] ?? $user->identifier;
+
+        if (!empty($response['first_name'])) {
+            $user->first_name = $response['first_name'];
+        }
+        if (!empty($response['last_name'])) {
+            $user->last_name = $response['last_name'];
+        }
+
         $user->mobile     = $mobile ?? $user->mobile;
+        $user->age = $response['age'] ?? $user->age;
+        $user->gender = $response['gender'] ?? $user->gender;
+        $user->birthday = $response['birthday'] ?? $user->birthday;
+        $user->referral_code = $response['referral_code'] ?? $user->referral_code;
         $user->email_verified_at = $response['email_verified_at'] ?? $user->email_verified_at;
         $user->save();
     }
 
+    // Link the referral relationship and reward the referrer (کد معرف)
+    $this->linkReferral($user, $response);
+
     return $user;
 }
 
+    /**
+     * Resolve the approagency referrer (by uuid/identifier) to a local
+     * meditation user, record the relationship once, and grant the referrer
+     * their per-invite points. The free-month subscription milestone is
+     * handled in approagency, where products/plans/transactions are managed.
+     */
+    private function linkReferral(User $user, array $response): void
+    {
+        if ($user->referred_by) {
+            return; // already linked — never reward twice
+        }
+
+        $referrerUuid = $response['referrer_uuid'] ?? null;
+        if (!$referrerUuid) {
+            return;
+        }
+
+        $referrer = User::where('identifier', $referrerUuid)->first();
+        if (!$referrer || $referrer->id === $user->id) {
+            return;
+        }
+
+        $user->referred_by = $referrer->id;
+        $user->save();
+
+        // 100 points per successful invite
+        $referrer->increment('referral_points', User::REFERRAL_POINTS_PER_INVITE);
+    }
+
+    /**
+     * Referral dashboard data (دعوت دوستان page).
+     */
+    public function referral(Request $request)
+    {
+        $user = auth()->user();
+        $invites = $user->referrals()->count();
+        $target = User::REFERRAL_SUBSCRIPTION_TARGET;
+
+        return response()->json([
+            'referral_code' => $user->referral_code,
+            'referral_points' => (int) $user->referral_points,
+            'successful_invites' => $invites,
+            'subscription_target' => $target,
+            'remaining_to_subscription' => max(0, $target - $invites),
+            'rewards' => [
+                'points_per_invite' => User::REFERRAL_POINTS_PER_INVITE,
+                'friend_points_share_percent' => (int) (User::REFERRAL_SHARE * 100),
+                'subscription_invite_target' => $target,
+            ],
+        ]);
+    }
 
     public function loginForeginer(Request $request)
     {
@@ -434,6 +536,7 @@ public function updateProfile(Request $request)
             'first_name' => 'string|nullable',
             'last_name' => 'string|nullable',
             'birthday' => 'date|nullable',
+            'age' => 'integer|nullable|min:0|max:120',
             'gender' => ['integer', 'nullable', Rule::in(User::GENDERS)],
             'email' => 'email|nullable',
             'mobile' => [new MobileNumber, 'string'],
@@ -499,6 +602,13 @@ public function profile(Request $request)
         : [];
 
         $user->load(['breathingSessions.template']);
+
+        // Whether this user has answered any survey question.
+        $user->setAttribute(
+            'has_answered_survey',
+            \App\Models\SurveyAnswer::where('user_id', $user->id)->exists()
+        );
+
         return response()->json([
             'user' => $user,
             'reminders' => $reminders,

app/Models/Announcement.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class Announcement extends Model
+{
+    protected $fillable = [
+        'image_id', 'title', 'description', 'link', 'button_text', 'start_date', 'end_date',
+    ];
+
+    protected $casts = [
+        'start_date' => 'datetime',
+        'end_date' => 'datetime',
+    ];
+
+    public function image(): BelongsTo
+    {
+        return $this->belongsTo(Image::class);
+    }
+
+    // Currently within its [start_date, end_date] window (null bounds = open-ended).
+    public function scopeActive($query)
+    {
+        $now = now();
+
+        return $query
+            ->where(fn ($q) => $q->whereNull('start_date')->orWhere('start_date', '<=', $now))
+            ->where(fn ($q) => $q->whereNull('end_date')->orWhere('end_date', '>=', $now));
+    }
+}

app/Models/AppFeedback.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class AppFeedback extends Model
+{
+    protected $table = 'app_feedback';
+
+    protected $fillable = ['user_id', 'stars', 'content'];
+
+    protected $casts = [
+        'stars' => 'integer',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+}

app/Models/AppVersion.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class AppVersion extends Model
+{
+    protected $fillable = [
+        'image_id', 'title', 'description', 'version_name', 'version_code', 'link', 'button_text',
+    ];
+
+    protected $casts = [
+        'version_code' => 'integer',
+    ];
+
+    public function image(): BelongsTo
+    {
+        return $this->belongsTo(Image::class);
+    }
+}

app/Models/BackgroundSound.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class BackgroundSound extends Model
+{
+    protected $fillable = ['name', 'sound_path', 'image_path', 'order', 'is_active'];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+
+    protected $appends = ['sound_url', 'image_url'];
+
+    public function getSoundUrlAttribute(): ?string
+    {
+        return $this->sound_path ? asset('storage/' . $this->sound_path) : null;
+    }
+
+    public function getImageUrlAttribute(): ?string
+    {
+        return $this->image_path ? asset('storage/' . $this->image_path) : null;
+    }
+}

app/Models/BellSound.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class BellSound extends Model
+{
+    protected $fillable = ['name', 'sound_path', 'image_path', 'order', 'is_active'];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+
+    protected $appends = ['sound_url', 'image_url'];
+
+    public function getSoundUrlAttribute(): ?string
+    {
+        return $this->sound_path ? asset('storage/' . $this->sound_path) : null;
+    }
+
+    public function getImageUrlAttribute(): ?string
+    {
+        return $this->image_path ? asset('storage/' . $this->image_path) : null;
+    }
+}

app/Models/BreathingColor.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class BreathingColor extends Model
+{
+    protected $fillable = ['name', 'colors', 'order', 'is_active'];
+
+    protected $casts = [
+        'colors' => 'array',
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+}

app/Models/BreathingTemplate.php

@@ -8,12 +8,17 @@
 class BreathingTemplate extends Model
 {
      use HasSaves;
-    protected $fillable = ['user_id', 'name', 'inhale', 'exhale', 'breath_hold' , 'duration' , 'description','image_id' , 'source'];
+    protected $fillable = ['user_id', 'name', 'inhale', 'exhale', 'breath_hold' , 'duration' , 'description','image_id' , 'source', 'breathing_color_id'];
 
     public function user()
     {
         return $this->belongsTo(User::class);
     }
+
+    public function breathingColor()
+    {
+        return $this->belongsTo(BreathingColor::class);
+    }
     protected $appends = ['image_url', 'is_saved','saved_count'];
 
     public function getImageUrlAttribute()

app/Models/Category.php

@@ -6,7 +6,28 @@
 
 class Category extends Model
 {
-    protected $fillable = ['name'];
+    public const TYPE_MEDIA = 'media';
+    public const TYPE_PLAYLIST = 'playlist';
+    public const TYPE_BREATHING_TEMPLATE = 'breathing_template';
+
+    public const TYPES = [
+        self::TYPE_MEDIA,
+        self::TYPE_PLAYLIST,
+        self::TYPE_BREATHING_TEMPLATE,
+    ];
+
+    protected $fillable = ['name', 'type', 'order', 'description', 'icon'];
+
+    protected $casts = [
+        'order' => 'integer',
+    ];
+
+    protected $appends = ['icon_url'];
+
+    public function getIconUrlAttribute(): ?string
+    {
+        return $this->icon ? asset('storage/' . $this->icon) : null;
+    }
 
     public function questions()
     {

app/Models/ChatTopic.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class ChatTopic extends Model
+{
+    protected $fillable = ['title', 'description', 'order', 'is_active'];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+}

app/Models/Faq.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class Faq extends Model
+{
+    protected $fillable = ['faq_category_id', 'question', 'answer', 'order', 'is_active'];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+
+    public function category(): BelongsTo
+    {
+        return $this->belongsTo(FaqCategory::class, 'faq_category_id');
+    }
+}

app/Models/FaqCategory.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class FaqCategory extends Model
+{
+    protected $fillable = ['name', 'order', 'is_active'];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+
+    public function faqs(): HasMany
+    {
+        return $this->hasMany(Faq::class)->orderBy('order');
+    }
+}

app/Models/Media.php

@@ -13,6 +13,7 @@ class Media extends Model
   protected $fillable = [
         'user_id',
         'image_id',
+        'detail_image_id',
         'title',
         'caption',
         'type',
@@ -35,14 +36,19 @@ class Media extends Model
         'saved_count',
         'is_liked',
         'likes_count',
-'is_liked',
-        'likes_count', 
+        'url',
     ];
     public function image()
     {
         return $this->belongsTo(Image::class);
     }
 
+    // Image shown on the detail (show-by-id) screen; image() is the list thumbnail.
+    public function detailImage()
+    {
+        return $this->belongsTo(Image::class, 'detail_image_id');
+    }
+
     public function categories()
     {
         return $this->belongsToMany(Category::class, 'category_media');
@@ -83,14 +89,6 @@ public function getUrlAttribute()
 
         return $this->external_url;
     }
-
-
-    public function getIsSavedAttribute()
-    {
-        if (!auth()->check()) return false;
-
-        return $this->savedBy()
-            ->where('user_id', auth()->id())
-            ->exists();
-    }
+    // is_saved / saved_count come from the HasSaves trait (saved_items table),
+    // so the /saves/* endpoints and the media list/show all agree.
 }

app/Models/MusicCategory.php

@@ -8,6 +8,9 @@
 use Illuminate\Database\Eloquent\Relations\HasMany;    // ← Add this
 class MusicCategory extends Model
 {
+    // Static type so playlist categories are tagged like media categories.
+    public const TYPE = 'playlist';
+
     protected $table = 'music_categories';
 
     protected $fillable = [
@@ -19,6 +22,13 @@ class MusicCategory extends Model
         'order' => 'integer',
     ];
 
+    protected $appends = ['type'];
+
+    public function getTypeAttribute(): string
+    {
+        return self::TYPE;
+    }
+
     public function playlists(): BelongsToMany
     {
         return $this->belongsToMany(MusicPlaylist::class, 'music_category_playlist', 'category_id', 'playlist_id');

app/Models/MusicPlaylist.php

@@ -9,17 +9,19 @@
 use App\Traits\HasComments; // Add this
 use App\Traits\HasLikes;
 use App\Traits\HasSaves;
+use App\Traits\HasRatings;
 class MusicPlaylist extends Model
 {
-    use HasComments, HasLikes, HasSaves;
+    use HasComments, HasLikes, HasSaves, HasRatings;
     protected $table = 'music_playlists';
     
     protected $fillable = [
-        'name', 'slug', 'description', 'image_id', 'order', 'is_active'
+        'name', 'slug', 'description', 'image_id', 'detail_image_id', 'order', 'is_active', 'is_premium'
     ];
 
     protected $casts = [
         'is_active' => 'boolean',
+        'is_premium' => 'boolean',
         'order' => 'integer',
     ];
     protected $appends = [
@@ -30,7 +32,8 @@ class MusicPlaylist extends Model
         'is_liked',
         'likes_count',
         'is_saved',
-        'saved_count'
+        'saved_count',
+        'duration',
     ];
     public function categories(): BelongsToMany
     {
@@ -55,6 +58,12 @@ public function image(): BelongsTo
         return $this->belongsTo(Image::class);
     }
 
+    // Image shown on the detail (show-by-id) screen; image() is the list thumbnail.
+    public function detailImage(): BelongsTo
+    {
+        return $this->belongsTo(Image::class, 'detail_image_id');
+    }
+    
     public function getActiveMusicsAttribute()
     {
         return $this->musics()->where('music.is_active', true)->orderBy('music_playlist.order')->get();
@@ -64,4 +73,10 @@ public function getTotalDurationAttribute()
     {
         return $this->musics()->where('music.is_active', true)->sum('music.duration');
     }
+
+    // Total play time of the playlist = sum of its active musics' durations.
+    public function getDurationAttribute()
+    {
+        return $this->total_duration;
+    }
 }

app/Models/Scene.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class Scene extends Model
+{
+    protected $fillable = ['theme_id', 'name', 'image_path', 'video_path', 'sound_path', 'order', 'is_active', 'is_premium'];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'is_premium' => 'boolean',
+        'order' => 'integer',
+    ];
+
+    public function theme(): BelongsTo
+    {
+        return $this->belongsTo(Theme::class);
+    }
+
+    protected $appends = ['image_url', 'video_url', 'sound_url', 'has_video'];
+
+    public function getImageUrlAttribute(): ?string
+    {
+        return $this->image_path ? asset('storage/' . $this->image_path) : null;
+    }
+
+    public function getVideoUrlAttribute(): ?string
+    {
+        return $this->video_path ? asset('storage/' . $this->video_path) : null;
+    }
+
+    public function getSoundUrlAttribute(): ?string
+    {
+        return $this->sound_path ? asset('storage/' . $this->sound_path) : null;
+    }
+
+    // Whether this scene can be shown as a video (the "تبدیل صحنه به ویدیو" toggle).
+    public function getHasVideoAttribute(): bool
+    {
+        return !empty($this->video_path);
+    }
+}

app/Models/Slider.php

@@ -3,12 +3,18 @@
 namespace App\Models;
 
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
 class Slider extends Model
 {
-    protected $fillable = ['title', 'description', 'url','action'];
+    protected $fillable = ['title', 'description', 'url', 'action', 'image_id'];
 
     protected $casts = [
         'action' => 'array', //  auto convert JSON to array
     ];
+
+    public function image(): BelongsTo
+    {
+        return $this->belongsTo(Image::class);
+    }
 }

app/Models/SubCategory.php

@@ -10,7 +10,7 @@ class SubCategory extends Model
 {
     protected $table = 'sub_categories';
 
-    protected $fillable = ['category_id', 'name'];
+    protected $fillable = ['category_id', 'name', 'description'];
 
     public function category(): BelongsTo
     {

app/Models/Theme.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class Theme extends Model
+{
+    protected $fillable = ['key', 'name', 'colors', 'order', 'is_active'];
+
+    protected $casts = [
+        'colors' => 'array',
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+
+    public function scenes(): HasMany
+    {
+        return $this->hasMany(Scene::class);
+    }
+}

app/Models/TimerPreset.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class TimerPreset extends Model
+{
+    protected $fillable = [
+        'user_id',
+        'name',
+        'duration_seconds',
+        'start_bell_id',
+        'end_bell_id',
+        'interval_bell_id',
+        'interval_seconds',
+        'interval_repeat',
+        'background_sound_id',
+        'background_image_id',
+        'volume',
+    ];
+
+    protected $casts = [
+        'duration_seconds' => 'integer',
+        'interval_seconds' => 'integer',
+        'interval_repeat' => 'integer',
+        'volume' => 'integer',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function startBell(): BelongsTo
+    {
+        return $this->belongsTo(BellSound::class, 'start_bell_id');
+    }
+
+    public function endBell(): BelongsTo
+    {
+        return $this->belongsTo(BellSound::class, 'end_bell_id');
+    }
+
+    public function intervalBell(): BelongsTo
+    {
+        return $this->belongsTo(BellSound::class, 'interval_bell_id');
+    }
+
+    public function backgroundSound(): BelongsTo
+    {
+        return $this->belongsTo(BackgroundSound::class, 'background_sound_id');
+    }
+
+    public function backgroundImage(): BelongsTo
+    {
+        return $this->belongsTo(Image::class, 'background_image_id');
+    }
+
+    // Eager-load set for returning a fully-resolved preset to the front.
+    public const RELATIONS = [
+        'startBell',
+        'endBell',
+        'intervalBell',
+        'backgroundSound',
+        'backgroundImage',
+    ];
+}

app/Models/User.php

@@ -18,6 +18,12 @@ class User extends Authenticatable
         'male' => 1,
         'female' => 2,
     ];
+
+    // Referral program (کد معرف)
+    const REFERRAL_POINTS_PER_INVITE = 100;   // points granted to the referrer per successful invite
+    const REFERRAL_SHARE = 0.10;              // referrer keeps 10% of each friend's earned xp, forever
+    const REFERRAL_SUBSCRIPTION_TARGET = 10;  // successful invites needed for the free-month milestone
+
     /**
      * The attributes that are mass assignable.
      *
@@ -69,6 +75,32 @@ public function otpTokens()
         return $this->hasMany(OtpTokens::class);
     }
 
+    public function referrer()
+    {
+        return $this->belongsTo(User::class, 'referred_by');
+    }
+
+    public function referrals()
+    {
+        return $this->hasMany(User::class, 'referred_by');
+    }
+
+    /**
+     * Award xp to this user and, if they were referred, credit the
+     * referrer their permanent 10% share of the earned points.
+     */
+    public function awardXp(int $amount): void
+    {
+        $this->increment('xp', $amount);
+
+        if ($this->referred_by) {
+            $share = (int) floor($amount * self::REFERRAL_SHARE);
+            if ($share > 0) {
+                self::where('id', $this->referred_by)->increment('referral_points', $share);
+            }
+        }
+    }
+
     public function transactions()
     {
         return $this->hasMany(Transaction::class);
@@ -111,4 +143,9 @@ public function savedMedia()
     return $this->belongsToMany(Media::class, 'saved_media')->withTimestamps();
 }
 
+public function surveyAnswers()
+{
+    return $this->hasMany(SurveyAnswer::class);
+}
+
 }

app/Models/UserSceneSetting.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class UserSceneSetting extends Model
+{
+    protected $fillable = [
+        'user_id',
+        'active_scene_id',
+        'scene_volume',
+        'background_play_seconds',
+        'video_enabled',
+    ];
+
+    protected $casts = [
+        'scene_volume' => 'integer',
+        'background_play_seconds' => 'integer',
+        'video_enabled' => 'boolean',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function activeScene(): BelongsTo
+    {
+        return $this->belongsTo(Scene::class, 'active_scene_id');
+    }
+}

app/Traits/HandlesImageUpload.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Traits;
+
+use App\Models\Image;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+
+trait HandlesImageUpload
+{
+    /**
+     * If the request carries an uploaded image file, store it, create an Image
+     * record for it, and return that record's id. Returns null when no file is
+     * present so callers can fall back to a provided image_id.
+     */
+    protected function uploadedImageId(Request $request, string $field = 'image'): ?int
+    {
+        if (!$request->hasFile($field)) {
+            return null;
+        }
+
+        $file = $request->file($field);
+        $ext = $file->getClientOriginalExtension() ?: ($file->guessExtension() ?: 'jpg');
+        $path = $file->storeAs('images', Str::random(40) . '.' . $ext, 'public');
+
+        return Image::create([
+            'user_id' => auth()->id(),
+            'path' => $path,
+            'type' => 'public',
+        ])->id;
+    }
+}

app/Traits/HasSaves.php

@@ -3,7 +3,6 @@
 namespace App\Traits;
 
 use App\Models\SavedItem;
-use Illuminate\Database\Eloquent\Relations\MorphMany;
 
 trait HasSaves
 {
@@ -14,11 +13,7 @@ public function saves()
 
     public function getIsSavedAttribute()
     {
-        if (!auth()->check()) return false;
-        
-        return $this->saves()
-            ->where('user_id', auth()->id())
-            ->exists();
+        return $this->isSavedByAuthUser();
     }
 
     public function getSavedCountAttribute()
@@ -26,20 +21,31 @@ public function getSavedCountAttribute()
         return $this->saves()->count();
     }
 
+    // Check the saves() relation directly (not the is_saved attribute, which a
+    // model may override to point at a different table — e.g. Media), so toggle
+    // always decides against the same table it writes to.
+    protected function isSavedByAuthUser(): bool
+    {
+        if (!auth()->check()) {
+            return false;
+        }
+
+        return $this->saves()->where('user_id', auth()->id())->exists();
+    }
+
     public function toggleSaveStatus()
     {
-        if ($this->getIsSavedAttribute()) {
-            return $this->removeSave();
-        } else {
-            return $this->addSave();
-        }
+        return $this->isSavedByAuthUser() ? $this->removeSave() : $this->addSave();
     }
 
     public function addSave()
     {
-        if ($this->getIsSavedAttribute()) return false;
+        if (!auth()->check()) {
+            return false;
+        }
 
-        return SavedItem::create([
+        // Idempotent: never inserts a duplicate even on repeated/racing calls.
+        return SavedItem::firstOrCreate([
             'user_id' => auth()->id(),
             'saveable_id' => $this->id,
             'saveable_type' => get_class($this),
@@ -48,7 +54,9 @@ public function addSave()
 
     public function removeSave()
     {
-        if (!$this->getIsSavedAttribute()) return false;
+        if (!auth()->check()) {
+            return false;
+        }
 
         return SavedItem::where([
             'user_id' => auth()->id(),

app/Traits/StoresUploads.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Traits;
+
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Str;
+
+trait StoresUploads
+{
+    /**
+     * Store an uploaded file under a random name while preserving its real
+     * extension (from the original filename). Laravel's default store() derives
+     * the extension from the sniffed MIME type, which yields ".bin" for files
+     * that sniff as application/octet-stream (e.g. some valid .mp3 files).
+     */
+    protected function storeUpload(UploadedFile $file, string $folder, string $disk = 'public'): string
+    {
+        $ext = $file->getClientOriginalExtension()
+            ?: ($file->guessExtension() ?: 'bin');
+
+        return $file->storeAs($folder, Str::random(40) . '.' . $ext, $disk);
+    }
+}

database/migrations/2026_06_01_130000_create_scenes_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('scenes', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('image_path')->nullable(); // scene background image
+            $table->string('video_path')->nullable(); // animated/video version of the scene
+            $table->string('sound_path')->nullable(); // scene ambient sound
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('scenes');
+    }
+};

database/migrations/2026_06_01_140000_create_user_scene_settings_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('user_scene_settings', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();
+            $table->foreignId('active_scene_id')->nullable()->constrained('scenes')->nullOnDelete();
+            $table->unsignedInteger('scene_volume')->default(100);            // صدای صحنه (0-100)
+            $table->unsignedInteger('background_play_seconds')->default(0);   // پخش صدا خارج از برنامه
+            $table->boolean('video_enabled')->default(false);                 // تبدیل صحنه به ویدیو
+            $table->timestamps();
+
+            $table->unique('user_id'); // one settings row per user
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('user_scene_settings');
+    }
+};

database/migrations/2026_06_02_100000_create_bell_sounds_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        // Bell sounds used for start / end / interval bells (زنگ شروع/پایان/بین‌راهی).
+        Schema::create('bell_sounds', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('sound_path')->nullable();
+            $table->string('image_path')->nullable();
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('bell_sounds');
+    }
+};

database/migrations/2026_06_02_100100_create_background_sounds_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        // Ambient background sounds (صدای پس‌زمینه).
+        Schema::create('background_sounds', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('sound_path')->nullable();
+            $table->string('image_path')->nullable();
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('background_sounds');
+    }
+};

database/migrations/2026_06_02_100200_create_background_images_table.php

@@ -0,0 +1,32 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        // Background images (تصویر پس‌زمینه).
+        Schema::create('background_images', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('image_path')->nullable();
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('background_images');
+    }
+};

database/migrations/2026_06_02_100300_create_timer_presets_table.php

@@ -0,0 +1,46 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        // A saved meditation timer (ذخیره‌شده‌های من) configured by a user.
+        Schema::create('timer_presets', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();
+            $table->string('name');
+            $table->unsignedInteger('duration_seconds')->default(0); // مدت زمان
+
+            // Bells
+            $table->foreignId('start_bell_id')->nullable()->constrained('bell_sounds')->nullOnDelete();
+            $table->foreignId('end_bell_id')->nullable()->constrained('bell_sounds')->nullOnDelete();
+            $table->foreignId('interval_bell_id')->nullable()->constrained('bell_sounds')->nullOnDelete();
+            $table->unsignedInteger('interval_seconds')->nullable();  // هر چند ثانیه یک‌بار
+            $table->unsignedInteger('interval_repeat')->nullable();   // تکرار چند بار
+
+            // Ambience
+            $table->foreignId('background_sound_id')->nullable()->constrained('background_sounds')->nullOnDelete();
+            $table->foreignId('background_image_id')->nullable()->constrained('background_images')->nullOnDelete();
+
+            $table->unsignedInteger('volume')->default(100); // صدای دستگاه (0-100)
+            $table->timestamps();
+
+            $table->index('user_id');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('timer_presets');
+    }
+};

database/migrations/2026_06_03_100000_use_images_for_timer_background_image.php

@@ -0,0 +1,48 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Repoint timer background image to the shared `images` table and drop the
+     * dedicated background_images catalog.
+     */
+    public function up(): void
+    {
+        Schema::table('timer_presets', function (Blueprint $table) {
+            $table->dropForeign(['background_image_id']);
+        });
+
+        Schema::dropIfExists('background_images');
+
+        Schema::table('timer_presets', function (Blueprint $table) {
+            $table->foreign('background_image_id')->references('id')->on('images')->nullOnDelete();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('timer_presets', function (Blueprint $table) {
+            $table->dropForeign(['background_image_id']);
+        });
+
+        Schema::create('background_images', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('image_path')->nullable();
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+
+        Schema::table('timer_presets', function (Blueprint $table) {
+            $table->foreign('background_image_id')->references('id')->on('background_images')->nullOnDelete();
+        });
+    }
+};

database/migrations/2026_06_03_110000_add_description_and_icon_to_categories_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('categories', function (Blueprint $table) {
+            $table->text('description')->nullable()->after('name');
+            $table->string('icon')->nullable()->after('description'); // stored icon image path
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('categories', function (Blueprint $table) {
+            $table->dropColumn(['description', 'icon']);
+        });
+    }
+};

database/migrations/2026_06_03_110100_add_description_to_sub_categories_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('sub_categories', function (Blueprint $table) {
+            $table->text('description')->nullable()->after('name');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('sub_categories', function (Blueprint $table) {
+            $table->dropColumn('description');
+        });
+    }
+};

database/migrations/2026_06_03_120000_create_chat_topics_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('chat_topics', function (Blueprint $table) {
+            $table->id();
+            $table->string('title');                 // chip text shown in the advisor chat
+            $table->text('description')->nullable();
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('chat_topics');
+    }
+};

database/migrations/2026_06_03_130000_add_detail_image_to_media_and_playlists.php

@@ -0,0 +1,41 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Add a second image reference: image_id = list/thumbnail image,
+     * detail_image_id = image shown on the detail (show-by-id) screen.
+     */
+    public function up(): void
+    {
+        Schema::table('media', function (Blueprint $table) {
+            $table->unsignedBigInteger('detail_image_id')->nullable()->after('image_id');
+            $table->foreign('detail_image_id')->references('id')->on('images')->nullOnDelete();
+        });
+
+        Schema::table('music_playlists', function (Blueprint $table) {
+            $table->unsignedBigInteger('detail_image_id')->nullable()->after('image_id');
+            $table->foreign('detail_image_id')->references('id')->on('images')->nullOnDelete();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('media', function (Blueprint $table) {
+            $table->dropForeign(['detail_image_id']);
+            $table->dropColumn('detail_image_id');
+        });
+
+        Schema::table('music_playlists', function (Blueprint $table) {
+            $table->dropForeign(['detail_image_id']);
+            $table->dropColumn('detail_image_id');
+        });
+    }
+};

database/migrations/2026_06_06_000000_add_referral_code_to_users_table.php

@@ -0,0 +1,42 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            // Own shareable code, mirrored from approagency (source of truth).
+            if (!Schema::hasColumn('users', 'referral_code')) {
+                $table->string('referral_code', 12)->nullable()->after('identifier');
+            }
+            // Local meditation user who referred this user (resolved from approagency's referrer_uuid).
+            if (!Schema::hasColumn('users', 'referred_by')) {
+                $table->foreignId('referred_by')->nullable()->after('referral_code')
+                    ->constrained('users')->nullOnDelete();
+            }
+            // Points earned through referrals (100 per invite + 10% of friends' xp).
+            if (!Schema::hasColumn('users', 'referral_points')) {
+                $table->unsignedInteger('referral_points')->default(0)->after('referred_by');
+            }
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            if (Schema::hasColumn('users', 'referred_by')) {
+                $table->dropForeign(['referred_by']);
+                $table->dropColumn('referred_by');
+            }
+            foreach (['referral_code', 'referral_points'] as $column) {
+                if (Schema::hasColumn('users', $column)) {
+                    $table->dropColumn($column);
+                }
+            }
+        });
+    }
+};

database/migrations/2026_06_06_100000_create_app_feedback_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * App-level feedback (نظرات و ایده‌ها): one editable entry per user holding an
+     * overall star rating and/or an idea/comment about the application.
+     */
+    public function up(): void
+    {
+        Schema::create('app_feedback', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();
+            $table->unsignedTinyInteger('stars')->nullable(); // 1-5 overall rating
+            $table->text('content')->nullable();              // idea / comment
+            $table->timestamps();
+
+            $table->unique('user_id'); // one feedback row per user (edited in place)
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('app_feedback');
+    }
+};

database/migrations/2026_06_10_000000_add_age_to_users_table.php

@@ -0,0 +1,26 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            if (!Schema::hasColumn('users', 'age')) {
+                $table->unsignedTinyInteger('age')->nullable()->after('birthday');
+            }
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            if (Schema::hasColumn('users', 'age')) {
+                $table->dropColumn('age');
+            }
+        });
+    }
+};

database/migrations/2026_06_11_100000_add_type_to_categories_table.php

@@ -0,0 +1,41 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('categories', function (Blueprint $table) {
+            // General category type: media | playlist | breathing_template
+            $table->string('type')->default('media')->after('name')->index();
+        });
+
+        // Existing categories were used for media content.
+        DB::table('categories')->update(['type' => 'media']);
+
+        // Name is unique per type (same name may exist for media and playlist).
+        Schema::table('categories', function (Blueprint $table) {
+            $table->dropUnique('categories_name_unique');
+            $table->unique(['name', 'type']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('categories', function (Blueprint $table) {
+            $table->dropUnique(['name', 'type']);
+            $table->unique('name');
+            $table->dropColumn('type');
+        });
+    }
+};

database/migrations/2026_06_15_100000_create_themes_table.php

@@ -0,0 +1,26 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('themes', function (Blueprint $table) {
+            $table->id();
+            $table->string('key')->unique();   // blue, pink, green, orange, purple
+            $table->string('name');            // display label
+            $table->json('colors');            // full color map (json works on MySQL & Postgres)
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('themes');
+    }
+};

database/migrations/2026_06_15_100100_add_theme_id_to_scenes_table.php

@@ -0,0 +1,24 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('scenes', function (Blueprint $table) {
+            $table->foreignId('theme_id')->nullable()->after('id')
+                ->constrained('themes')->nullOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('scenes', function (Blueprint $table) {
+            $table->dropForeign(['theme_id']);
+            $table->dropColumn('theme_id');
+        });
+    }
+};

database/migrations/2026_06_15_120000_add_is_premium_to_scenes_table.php

@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('scenes', function (Blueprint $table) {
+            $table->boolean('is_premium')->default(false)->after('is_active');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('scenes', function (Blueprint $table) {
+            $table->dropColumn('is_premium');
+        });
+    }
+};

database/migrations/2026_06_15_130000_add_colors_to_breathing_templates_table.php

@@ -0,0 +1,23 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('breathing_templates', function (Blueprint $table) {
+            // One or more hex colors: a single solid color or a gradient.
+            $table->json('colors')->nullable()->after('image_id');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('breathing_templates', function (Blueprint $table) {
+            $table->dropColumn('colors');
+        });
+    }
+};

database/migrations/2026_06_15_140000_create_breathing_colors_table.php

@@ -0,0 +1,25 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('breathing_colors', function (Blueprint $table) {
+            $table->id();
+            $table->string('name')->nullable();
+            $table->json('colors');          // one hex (solid) or several (gradient)
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('breathing_colors');
+    }
+};

database/migrations/2026_06_15_150000_use_breathing_color_id_on_templates.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('breathing_templates', function (Blueprint $table) {
+            if (Schema::hasColumn('breathing_templates', 'colors')) {
+                $table->dropColumn('colors');
+            }
+            $table->foreignId('breathing_color_id')->nullable()->after('image_id')
+                ->constrained('breathing_colors')->nullOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('breathing_templates', function (Blueprint $table) {
+            $table->dropForeign(['breathing_color_id']);
+            $table->dropColumn('breathing_color_id');
+            $table->json('colors')->nullable();
+        });
+    }
+};

database/migrations/2026_06_15_160000_create_faq_categories_table.php

@@ -0,0 +1,24 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('faq_categories', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('faq_categories');
+    }
+};

database/migrations/2026_06_15_160100_create_faqs_table.php

@@ -0,0 +1,26 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('faqs', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('faq_category_id')->constrained('faq_categories')->cascadeOnDelete();
+            $table->string('question');
+            $table->text('answer');
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('faqs');
+    }
+};

database/migrations/2026_06_15_170000_add_image_id_to_sliders_table.php

@@ -0,0 +1,24 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('sliders', function (Blueprint $table) {
+            $table->foreignId('image_id')->nullable()->after('id')
+                ->constrained('images')->nullOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('sliders', function (Blueprint $table) {
+            $table->dropForeign(['image_id']);
+            $table->dropColumn('image_id');
+        });
+    }
+};

database/migrations/2026_06_15_180000_add_is_premium_to_music_playlists_table.php

@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('music_playlists', function (Blueprint $table) {
+            $table->boolean('is_premium')->default(false)->after('is_active');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('music_playlists', function (Blueprint $table) {
+            $table->dropColumn('is_premium');
+        });
+    }
+};

database/migrations/2026_06_24_100000_create_announcements_table.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('announcements', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('image_id')->nullable()->constrained('images')->nullOnDelete();
+            $table->string('title');
+            $table->text('description')->nullable();
+            $table->string('link')->nullable();
+            $table->dateTime('start_date')->nullable();
+            $table->dateTime('end_date')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('announcements');
+    }
+};

database/migrations/2026_06_24_110000_create_app_versions_table.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('app_versions', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('image_id')->nullable()->constrained('images')->nullOnDelete();
+            $table->string('title');
+            $table->text('description')->nullable();
+            $table->string('version_name');           // e.g. "1.2.0"
+            $table->unsignedInteger('version_code');   // monotonic build number, e.g. 42
+            $table->string('link')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('app_versions');
+    }
+};

database/migrations/2026_06_24_120000_add_button_text_to_announcements_and_app_versions.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('announcements', function (Blueprint $table) {
+            $table->string('button_text')->nullable()->after('link');
+        });
+
+        Schema::table('app_versions', function (Blueprint $table) {
+            $table->string('button_text')->nullable()->after('link');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('announcements', function (Blueprint $table) {
+            $table->dropColumn('button_text');
+        });
+
+        Schema::table('app_versions', function (Blueprint $table) {
+            $table->dropColumn('button_text');
+        });
+    }
+};

database/migrations/2026_06_27_100000_add_order_to_categories_table.php

@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('categories', function (Blueprint $table) {
+            $table->integer('order')->default(0)->after('type')->index();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('categories', function (Blueprint $table) {
+            $table->dropColumn('order');
+        });
+    }
+};

database/seeders/BreathingColorSeeder.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Database\Seeders;
+
+use App\Models\BreathingColor;
+use Illuminate\Database\Seeder;
+
+class BreathingColorSeeder extends Seeder
+{
+    public function run(): void
+    {
+        $colors = [
+            ['name' => 'آبی',    'order' => 1, 'colors' => ['#3ABDEB', '#553AEB']],
+            ['name' => 'صورتی',  'order' => 2, 'colors' => ['#CE4299', '#8628FF']],
+            ['name' => 'سبز',    'order' => 3, 'colors' => ['#5CC65C', '#00A489']],
+            ['name' => 'نارنجی', 'order' => 4, 'colors' => ['#E2990A', '#CC4B1C']],
+            ['name' => 'بنفش',   'order' => 5, 'colors' => ['#6829DD', '#1A50CC']],
+            ['name' => 'تک‌رنگ', 'order' => 6, 'colors' => ['#5360FC']],
+        ];
+
+        foreach ($colors as $c) {
+            BreathingColor::firstOrCreate(['name' => $c['name']], $c);
+        }
+    }
+}

database/seeders/ThemeSeeder.php

@@ -0,0 +1,136 @@
+<?php
+
+namespace Database\Seeders;
+
+use App\Models\Theme;
+use Illuminate\Database\Seeder;
+
+class ThemeSeeder extends Seeder
+{
+    public function run(): void
+    {
+        $common = [
+            'bgPrimary' => '#26000000',
+            'bgSecondary' => '#33000000',
+            'bgTertiary' => '#40000000',
+            'bgFourth' => '#80000000',
+            'bgBlack' => '#99000000',
+            'bgWhite' => '#FFF7F7F7',
+            'bgError' => '#FFF04438',
+            'fgPrimary' => '#FFFFFFFF',
+            'fgSecondary' => '#FFD9D9D9',
+            'fgDisable' => '#FFC0C0C0',
+            'fgBlack' => '#FF000000',
+            'fgBlack2' => '#FF2F2F2F',
+            'fgError' => '#FFF04438',
+            'textPrimary' => '#FFFFFFFF',
+            'textSecondary' => '#FFD9D9D9',
+            'textDisable' => '#FFC0C0C0',
+            'textPrimaryReverse' => '#FF000000',
+            'textPrimaryReverse2' => '#FF2F2F2F',
+            'textError' => '#FFF04438',
+            'borderPrimary' => '#26FFFFFF',
+            'borderSecondary' => '#40FFFFFF',
+            'borderWhite' => '#FFFFFFFF',
+            'borderBlack' => '#FF000000',
+            'borderError' => '#FFF04438',
+        ];
+
+        $themes = [
+            [
+                'key' => 'blue',
+                'name' => 'آبی',
+                'order' => 1,
+                'colors' => array_merge($common, [
+                    'themeUp' => '#156395',
+                    'themeDown' => '#2E3381',
+                    'bottomNavigation' => '#292E74',
+                    'lightColorGradient' => '#3ABDEB',
+                    'darkColorGradient' => '#553AEB',
+                    'chatContainer' => '#252967',
+                    'bottomPlayerContainer' => '#252967',
+                    'bgBrand' => '#5360FC',
+                    'fgBrand' => '#5360FC',
+                    'textBrand' => '#5360FC',
+                    'borderBrand' => '#5360FC',
+                ]),
+            ],
+            [
+                'key' => 'pink',
+                'name' => 'صورتی',
+                'order' => 2,
+                'colors' => array_merge($common, [
+                    'themeUp' => '#843F6A',
+                    'themeDown' => '#4F366F',
+                    'bottomNavigation' => '#3F2B59',
+                    'lightColorGradient' => '#CE4299',
+                    'darkColorGradient' => '#8628FF',
+                    'chatContainer' => '#3F2B59',
+                    'bottomPlayerContainer' => '#3F2B59',
+                    'bgBrand' => '#843F6A',
+                    'fgBrand' => '#843F6A',
+                    'textBrand' => '#FFFF80AB',
+                    'borderBrand' => '#843F6A',
+                ]),
+            ],
+            [
+                'key' => 'green',
+                'name' => 'سبز',
+                'order' => 3,
+                'colors' => array_merge($common, [
+                    'themeUp' => '#3B6D3B',
+                    'themeDown' => '#064A3F',
+                    'bottomNavigation' => '#054339',
+                    'lightColorGradient' => '#5CC65C',
+                    'darkColorGradient' => '#00A489',
+                    'chatContainer' => '#053B32',
+                    'bottomPlayerContainer' => '#053B32',
+                    'bgBrand' => '#3B6D3B',
+                    'fgBrand' => '#3B6D3B',
+                    'textBrand' => '#4CAF50',
+                    'borderBrand' => '#3B6D3B',
+                ]),
+            ],
+            [
+                'key' => 'orange',
+                'name' => 'نارنجی',
+                'order' => 4,
+                'colors' => array_merge($common, [
+                    'themeUp' => '#7E5607',
+                    'themeDown' => '#81381D',
+                    'bottomNavigation' => '#74321A',
+                    'lightColorGradient' => '#E2990A',
+                    'darkColorGradient' => '#CC4B1C',
+                    'chatContainer' => '#672D17',
+                    'bottomPlayerContainer' => '#672D17',
+                    'bgBrand' => '#7E5607',
+                    'fgBrand' => '#7E5607',
+                    'textBrand' => '#FFE2990A',
+                    'borderBrand' => '#7E5607',
+                ]),
+            ],
+            [
+                'key' => 'purple',
+                'name' => 'بنفش',
+                'order' => 5,
+                'colors' => array_merge($common, [
+                    'themeUp' => '#371F63',
+                    'themeDown' => '#132F6F',
+                    'bottomNavigation' => '#112A64',
+                    'lightColorGradient' => '#6829DD',
+                    'darkColorGradient' => '#1A50CC',
+                    'chatContainer' => '#0F2659',
+                    'bottomPlayerContainer' => '#0F2659',
+                    'bgBrand' => '#371F63',
+                    'fgBrand' => '#371F63',
+                    'textBrand' => '#1A50CC',
+                    'borderBrand' => '#371F63',
+                ]),
+            ],
+        ];
+
+        foreach ($themes as $theme) {
+            Theme::updateOrCreate(['key' => $theme['key']], $theme);
+        }
+    }
+}

routes/api.php

@@ -4,6 +4,7 @@
 use Illuminate\Support\Facades\Route;
 use Laravel\Socialite\Facades\Socialite;
 use App\Http\Controllers\BreathingExerciseController;
+use App\Http\Controllers\BreathingColorController;
 use App\Http\Controllers\PackageNameController;
 use App\Http\Controllers\ProductController;
 use App\Http\Controllers\BreathingTemplate;
@@ -12,7 +13,18 @@
 use Illuminate\Support\Facades\Hash;
 use App\Http\Controllers\QuestionController;
 use App\Http\Controllers\SurveyQuestionController;
+use App\Http\Controllers\ChatTopicController;
+use App\Http\Controllers\AppFeedbackController;
+use App\Http\Controllers\FaqController;
+use App\Http\Controllers\FaqCategoryController;
 use App\Http\Controllers\SliderController;
+use App\Http\Controllers\AnnouncementController;
+use App\Http\Controllers\AppVersionController;
+use App\Http\Controllers\SceneController;
+use App\Http\Controllers\ThemeController;
+use App\Http\Controllers\BellSoundController;
+use App\Http\Controllers\BackgroundSoundController;
+use App\Http\Controllers\TimerPresetController;
 use App\Http\Controllers\ImageController;
 use App\Http\Controllers\MusicController;
 use App\Http\Controllers\MediaController;
@@ -25,6 +37,7 @@
 use App\Http\Controllers\MusicSubcategoryController;
 use App\Http\Controllers\SaveController;
 use App\Http\Controllers\LikeController;
+use App\Http\Controllers\InteractionController;
 
 Route::get('/test-hash', function() {
     $plain = 'amnk1380';
@@ -76,6 +89,9 @@
    ////-- leader board
    Route::get('/leader-board', [UserController::class, 'leaderBoard']);
 
+   ////-- referral (دعوت دوستان)
+   Route::get('/referral', [UserController::class, 'referral']);
+
     ///--  mood routes
 
      Route::post('/moods/today', [MoodController::class, 'storeUserMood']);
@@ -98,6 +114,9 @@
     Route::get('user-templates', [BreathingExerciseController::class, 'getUserTemplates']);
     Route::get('breathing-sessions', [BreathingExerciseController::class, 'getSessions']);
 
+    // Breathing color palette (app reads it to pick a template color; admin manages it).
+    Route::apiResource('breathing-colors', BreathingColorController::class);
+
     /// worry box feature
     Route::prefix('worries')->controller(WorryController::class)->group(function () {
         Route::post('/', 'store');            // Create worry + note
@@ -117,6 +136,28 @@
     Route::delete('/questions/{question}', [QuestionController::class, 'destroy']);
 
 
+    /// advisor chat — suggested topics (موضوعات پیشنهادی)
+    Route::apiResource('chat-topics', ChatTopicController::class);
+
+
+    /// FAQ (سوالات متداول) — app reads grouped /faqs; admin manages categories & items
+    Route::get('/faqs', [FaqController::class, 'index']); // app: categories + their questions
+    Route::apiResource('faq-categories', FaqCategoryController::class);
+    Route::post('/faqs', [FaqController::class, 'store']);
+    Route::get('/faqs/{id}', [FaqController::class, 'show']);
+    Route::put('/faqs/{id}', [FaqController::class, 'update']);
+    Route::delete('/faqs/{id}', [FaqController::class, 'destroy']);
+
+
+    /// app feedback — ideas & reviews (نظرات و ایده‌ها)
+    Route::get('/app-feedback', [AppFeedbackController::class, 'mine']);
+    Route::post('/app-feedback', [AppFeedbackController::class, 'store']);
+    Route::middleware('abilities:admin')->group(function () {
+        Route::get('/admin/app-feedback', [AppFeedbackController::class, 'adminIndex']);
+        Route::delete('/admin/app-feedback/{id}', [AppFeedbackController::class, 'adminDestroy']);
+    });
+
+
     /// survey questions feature (question + description + single/multi options, answered by users)
     // Admin: see all users' answers (must be registered before the resource so it isn't caught by {survey_question}).
     Route::middleware('abilities:admin')->group(function () {
@@ -125,9 +166,14 @@
         Route::get('/admin/survey-questions/{id}/analytics', [SurveyQuestionController::class, 'adminAnalytics']);
         Route::get('/admin/survey-questions', [SurveyQuestionController::class, 'adminIndex']);
         Route::get('/admin/survey-questions/{id}', [SurveyQuestionController::class, 'adminShow']);
+        // User list + detail for survey admin
+        Route::get('/admin/survey-users', [SurveyQuestionController::class, 'adminUsers']);
+        Route::get('/admin/survey-users/{id}', [SurveyQuestionController::class, 'adminUserShow']);
+        Route::patch('/admin/survey-users/{id}', [SurveyQuestionController::class, 'adminUserUpdate']);
     });
     // User: answer + read questions with their own answers only.
     Route::get('/survey-questions/suggested-media', [SurveyQuestionController::class, 'suggestedMedia']);
+    Route::post('/survey-questions/answers', [SurveyQuestionController::class, 'bulkAnswer']);
     Route::post('/survey-questions/{id}/answer', [SurveyQuestionController::class, 'answer']);
     Route::apiResource('survey-questions', SurveyQuestionController::class);
 
@@ -154,14 +200,79 @@
     Route::get('/slider', [SliderController::class, 'index']);     // list all sliders
     Route::post('/slider', [SliderController::class, 'store']);    // create slider
     Route::get('/slider/{id}', [SliderController::class, 'show']); // get single slider
-    Route::put('/slider/{id}', [SliderController::class, 'update']); // update slider
+    Route::put('/slider/{id}', [SliderController::class, 'update']); // update slider (json)
+    Route::post('/slider/{id}', [SliderController::class, 'update']); // update slider (multipart: image upload)
     Route::delete('/slider/{id}', [SliderController::class, 'destroy']); // delete slider
 
+    /// announcements
+    Route::get('/announcements/latest', [AnnouncementController::class, 'latest']); // single latest active (app)
+    Route::get('/announcements', [AnnouncementController::class, 'index']);          // list all (admin)
+    Route::post('/announcements', [AnnouncementController::class, 'store']);         // create
+    Route::get('/announcements/{id}', [AnnouncementController::class, 'show']);      // single
+    Route::put('/announcements/{id}', [AnnouncementController::class, 'update']);    // update (json)
+    Route::post('/announcements/{id}', [AnnouncementController::class, 'update']);   // update (multipart: image)
+    Route::delete('/announcements/{id}', [AnnouncementController::class, 'destroy']); // delete
+
+    /// app versions
+    Route::get('/versions/latest', [AppVersionController::class, 'latest']);  // newest version (app update check)
+    Route::get('/versions', [AppVersionController::class, 'index']);          // list all (admin)
+    Route::post('/versions', [AppVersionController::class, 'store']);         // create
+    Route::get('/versions/{id}', [AppVersionController::class, 'show']);      // single
+    Route::put('/versions/{id}', [AppVersionController::class, 'update']);    // update (json)
+    Route::post('/versions/{id}', [AppVersionController::class, 'update']);   // update (multipart: image)
+    Route::delete('/versions/{id}', [AppVersionController::class, 'destroy']); // delete
+
+
+    /// themes (color themes a scene can use)
+    Route::get('/themes', [ThemeController::class, 'index']);
+    Route::get('/themes/{id}', [ThemeController::class, 'show']);
+    Route::put('/themes/{id}', [ThemeController::class, 'update']);   // edit name / colors / order / active
+    Route::post('/themes/{id}', [ThemeController::class, 'update']);  // same, for method-spoofed clients
+
+    /// scenes (تنظیمات صحنه) — each scene has an image, optional video, and sound
+    // Consolidated settings screen (all scenes + current user's preferences) in one call.
+    Route::get('/scene-settings', [SceneController::class, 'settings']);
+    Route::put('/scene-settings', [SceneController::class, 'updateSettings']);
+    Route::get('/scenes', [SceneController::class, 'index']);
+    Route::post('/scenes', [SceneController::class, 'store']);          // multipart: image, video, sound
+    Route::get('/scenes/{id}', [SceneController::class, 'show']);
+    Route::post('/scenes/{id}', [SceneController::class, 'update']);    // multipart update
+    Route::delete('/scenes/{id}', [SceneController::class, 'destroy']);
+
+
+    /// insight timer (زمان‌سنج)
+    // Builder catalogs (bells / background sounds / background images) in one call.
+    Route::get('/timer/options', [TimerPresetController::class, 'options']);
+
+    // Saved timers per user (ذخیره‌شده‌های من).
+    Route::get('/timer-presets', [TimerPresetController::class, 'index']);
+    Route::post('/timer-presets', [TimerPresetController::class, 'store']);
+    Route::get('/timer-presets/{id}', [TimerPresetController::class, 'show']);
+    Route::put('/timer-presets/{id}', [TimerPresetController::class, 'update']);
+    Route::delete('/timer-presets/{id}', [TimerPresetController::class, 'destroy']);
+
+    // Timer sound/image catalogs (POST update for multipart uploads).
+    Route::get('/bell-sounds', [BellSoundController::class, 'index']);
+    Route::post('/bell-sounds', [BellSoundController::class, 'store']);
+    Route::get('/bell-sounds/{id}', [BellSoundController::class, 'show']);
+    Route::post('/bell-sounds/{id}', [BellSoundController::class, 'update']);
+    Route::delete('/bell-sounds/{id}', [BellSoundController::class, 'destroy']);
+
+    Route::get('/background-sounds', [BackgroundSoundController::class, 'index']);
+    Route::post('/background-sounds', [BackgroundSoundController::class, 'store']);
+    Route::get('/background-sounds/{id}', [BackgroundSoundController::class, 'show']);
+    Route::post('/background-sounds/{id}', [BackgroundSoundController::class, 'update']);
+    Route::delete('/background-sounds/{id}', [BackgroundSoundController::class, 'destroy']);
+
+    // Background images for timers reuse the shared images catalog (see /images routes).
+
 
 
     ///media
     Route::get('/media/filters', [MediaController::class, 'filters']);
+    Route::get('/media/search', [MediaController::class, 'search']);
     Route::get('/media/popular', [MediaController::class, 'popular']);
+    Route::get('/media/newest', [MediaController::class, 'newest']);
     Route::get('/media/recently-played', [MediaController::class, 'recentlyPlayed']);
     Route::post('/media', [MediaController::class, 'store']);
     Route::get('/media', [MediaController::class, 'index']);
@@ -180,6 +291,10 @@
     Route::post('/media/{id}/note', [MediaController::class, 'storeNote']);
 
     // Media categories
+    // Category with its sub-categories, each carrying its medias.
+    Route::get('categories/{id}/grouped', [CategoryController::class, 'grouped']);
+    // Explicit POST update so an icon image can be uploaded (multipart can't ride a PUT).
+    Route::post('categories/{id}', [CategoryController::class, 'update']);
     Route::apiResource('categories', CategoryController::class);
 
     // Media sub categories
@@ -189,10 +304,16 @@
 
 
     // Music Categories
+    // Category with its sub-categories, each carrying its playlists.
+    Route::get('music-categories/{id}/grouped', [MusicCategoryController::class, 'grouped']);
+    // Explicit POST update so an image can be uploaded (multipart can't ride a PUT).
+    Route::post('music-categories/{id}', [MusicCategoryController::class, 'update']);
     Route::apiResource('music-categories', MusicCategoryController::class);
     Route::get('public/music-categories', [MusicCategoryController::class, 'index']);
 
     // Music Playlists
+    // Explicit POST update so a playlist image can be uploaded (multipart can't ride a PUT).
+    Route::post('music-playlists/{music_playlist}', [MusicPlaylistController::class, 'update']);
     Route::apiResource('music-playlists', MusicPlaylistController::class);
     Route::get('playlists/by-category/{categoryId}', [MusicPlaylistController::class, 'index']);
 
@@ -242,6 +363,9 @@
     });
 
 
+    // Combined comment + like in one request (music / media / playlist)
+    Route::post('interactions/{type}/{id}', [InteractionController::class, 'store']);
+
     // Like routes (only for music and media)
     Route::prefix('likes')->group(function () {
         Route::post('/like', [LikeController::class, 'like']);