fix

Reviewed-on: http://95.38.179.159:3000/Amirmahdi/back-meditation/pulls/3

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

@@ -0,0 +1,207 @@
+<?php
+
+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');
+        }
+
+        $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',
+                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([
+            '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',
+            'category' => $category,
+        ], 201);
+    }
+
+    public function show($id)
+    {
+        $category = Category::with('subcategories')->withCount('subcategories')->findOrFail($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' => [
+                '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',
+        ]);
+
+        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',
+            'category' => $category,
+        ]);
+    }
+
+    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/CommentController.php

@@ -127,10 +127,11 @@ private function getModelClass($type)
         $models = [
             'music' => \App\Models\Music::class,
             'media' => \App\Models\Media::class,
+            'playlist' => \App\Models\MusicPlaylist::class, 
         ];
         
         if (!isset($models[$type])) {
-            abort(404, 'Invalid model type');
+            abort(404, 'Invalid model type. Supported types: music, media, playlist');
         }
         
         return $models[$type];

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

@@ -0,0 +1,241 @@
+<?php
+
+namespace App\Http\Controllers;
+use App\Models\Like;
+use Illuminate\Http\Request;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+
+class LikeController extends Controller
+{
+     /**
+     * Like an item (music or media)
+     */
+    public function like(Request $request)
+    {
+        $request->validate([
+            'type' => 'required|string|in:music,media,playlist',
+            'id' => 'required|integer',
+        ]);
+        
+        $model = $this->getModel($request->type, $request->id);
+        
+        if (!$model) {
+            return response()->json([
+                'message' => 'Item not found'
+            ], 404);
+        }
+        
+        $result = $model->addLike();
+        
+        return response()->json([
+            'message' => 'Item liked successfully',
+            'is_liked' => true,
+            'likes_count' => $model->likes_count
+        ]);
+    }
+    
+    /**
+     * Unlike an item
+     */
+    public function unlike(Request $request)
+    {
+        $request->validate([
+            'type' => 'required|string|in:music,media,playlist',
+            'id' => 'required|integer',
+        ]);
+        
+        $model = $this->getModel($request->type, $request->id);
+        
+        if (!$model) {
+            return response()->json([
+                'message' => 'Item not found'
+            ], 404);
+        }
+        
+        $result = $model->removeLike();
+        
+        return response()->json([
+            'message' => 'Item unliked successfully',
+            'is_liked' => false,
+            'likes_count' => $model->likes_count
+        ]);
+    }
+    
+    /**
+     * Toggle like status
+     */
+    public function toggleLike(Request $request)
+    {
+        $request->validate([
+            'type' => 'required|string|in:music,media,playlist',
+            'id' => 'required|integer',
+        ]);
+        
+        $model = $this->getModel($request->type, $request->id);
+        
+        if (!$model) {
+            return response()->json([
+                'message' => 'Item not found'
+            ], 404);
+        }
+        
+        $result = $model->toggleLike();
+        
+        return response()->json([
+            'message' => $result ? 'Item liked successfully' : 'Item unliked successfully',
+            'is_liked' => $model->is_liked,
+            'likes_count' => $model->likes_count
+        ]);
+    }
+    
+    /**
+     * Get all liked items for the authenticated user
+     */
+    public function myLikedItems(Request $request)
+    {
+        $type = $request->get('type'); // Optional filter by type (music or media)
+        
+        $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) {
+            $modelClass = $this->getModelClass($type);
+            $query->where('likeable_type', $modelClass);
+        }
+        
+        $likedItems = $query->latest()->paginate(20);
+
+          return response()->json([
+            'data' => $likedItems,
+            'total' => $likedItems->total(),
+            'types' => [
+                'music' => 'App\\Models\\Music',
+                'media' => 'App\\Models\\Media',
+                'playlist' => 'App\\Models\\MusicPlaylist',
+            ]
+        ]);
+        // Transform the response
+        // $transformedItems = $likedItems->map(function ($likeItem) {
+        //     $item = $likeItem->likeable;
+            
+        //     if (!$item) return null;
+            
+        //     $baseData = [
+        //         'like_id' => $likeItem->id,
+        //         'liked_at' => $likeItem->created_at,
+        //         'type' => class_basename($likeItem->likeable_type),
+        //         'is_liked' => true,
+        //     ];
+            
+        //     // Add type-specific data
+        //     if ($item instanceof \App\Models\Music) {
+        //         return array_merge($baseData, [
+        //             'id' => $item->id,
+        //             'title' => $item->title,
+        //             'artist' => $item->artist,
+        //             'duration' => $item->duration_formatted ?? $item->duration,
+        //             'image_url' => $item->image_url,
+        //             'likes_count' => $item->likes_count,
+        //             'type_display' => 'music'
+        //         ]);
+        //     } elseif ($item instanceof \App\Models\Media) {
+        //         return array_merge($baseData, [
+        //             'id' => $item->id,
+        //             'title' => $item->title,
+        //             'caption' => $item->caption,
+        //             'media_type' => $item->type,
+        //             'duration' => $item->duration,
+        //             'image_url' => $item->image->url ?? null,
+        //             'likes_count' => $item->likes_count,
+        //             'type_display' => 'media'
+        //         ]);
+        //     }
+            
+        //     return $baseData;
+        // })->filter();
+        
+        // return response()->json([
+        //     'data' => $transformedItems,
+        //     'total' => $likedItems->total(),
+        //     'current_page' => $likedItems->currentPage(),
+        //     'last_page' => $likedItems->lastPage(),
+        //     'per_page' => $likedItems->perPage(),
+        // ]);
+    }
+    
+    /**
+     * Check if specific item is liked by user
+     */
+    public function checkLiked(Request $request)
+    {
+        $request->validate([
+            'type' => 'required|string|in:music,media,playlist',
+            'id' => 'required|integer',
+        ]);
+        
+        $model = $this->getModel($request->type, $request->id);
+        
+        if (!$model) {
+            return response()->json([
+                'message' => 'Item not found'
+            ], 404);
+        }
+        
+        return response()->json([
+            'is_liked' => $model->is_liked,
+            'likes_count' => $model->likes_count
+        ]);
+    }
+    
+    /**
+     * Get top liked items
+     */
+    public function topLiked(Request $request)
+    {
+        $type = $request->get('type', 'music'); // Default to music
+        $limit = $request->get('limit', 10);
+        
+        $modelClass = $this->getModelClass($type);
+        
+        $items = $modelClass::with(['image'])
+            ->withCount('likes')
+            ->where(function($query) use ($modelClass) {
+                if (property_exists($modelClass, 'type')) {
+                    $query->where('type', 'public');
+                }
+                if (property_exists($modelClass, 'visibility')) {
+                    $query->where('visibility', 'public');
+                }
+            })
+            ->orderBy('likes_count', 'desc')
+            ->limit($limit)
+            ->get();
+        
+        return response()->json([
+            'data' => $items,
+            'type' => $type,
+            'total' => $items->count()
+        ]);
+    }
+    
+    private function getModel($type, $id)
+    {
+        $modelClass = $this->getModelClass($type);
+        return $modelClass::find($id);
+    }
+    
+    private function getModelClass($type)
+    {
+        $models = [
+            'music' => \App\Models\Music::class,
+            'media' => \App\Models\Media::class,
+            'playlist' => \App\Models\MusicPlaylist::class,
+        ];
+
+        return $models[$type] ?? null;
+    }
+}

app/Http/Controllers/MediaController.php

@@ -3,14 +3,20 @@
 namespace App\Http\Controllers;
 
 use App\Models\Media;
+use App\Models\MediaPlay;
 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)
     {
@@ -18,12 +24,17 @@ public function store(Request $request)
             'title' => 'required|string|max:255',
             'caption' => 'nullable|string',
             'type' => 'required|in:audio,video',
-            'category_id' => 'nullable|exists:categories,id',
-            'category_name' => 'nullable|string|max:255',
+            'category_ids' => 'nullable|array',
+            'category_ids.*' => 'integer|exists:categories,id',
+            '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',
 
@@ -31,32 +42,36 @@ public function store(Request $request)
              'tags.*' => 'string',
         ]);
 
-         $categoryId = $data['category_id'] ?? null;
-
-        if (!$categoryId && isset($data['category_name'])) {
-            $category = Category::firstOrCreate([
-                'name' => $data['category_name']
-            ]);
-            $categoryId = $category->id;
-        }
         $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,
-            'category_id' => $categoryId,
+            'external_url' => $externalUrl,
+            'image_id' => $imageId,
+            'detail_image_id' => $detailImageId,
             'duration' => $data['duration'] ?? null,
             'visibility' => $data['visibility'] ?? 'public',
             'is_premium'=> $data['is_premium'] ?? false
         ]);
+
+        $media->categories()->sync($data['category_ids'] ?? []);
+        $media->subCategories()->sync($data['subcategory_ids'] ?? []);
+
         if (!empty($data['tags'])) {
             $tagIds = [];
 
@@ -69,114 +84,139 @@ public function store(Request $request)
         }
         return response()->json([
             'message' => 'Media created successfully',
-            'media' => $media->load(['image', 'category' , 'tags']),
+            'media' => $media->load(['image', 'detailImage', 'categories', 'subCategories', 'tags']),
         ]);
     }
 public function index(Request $request)
 {
-    $query = Media::with(['image', 'category', '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);
 
-    if ($request->filled('categories')) {
-        $categories = explode(',', $request->categories);
-        $query->whereIn('category_id', $categories);
+    $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')));
     }
 
-    /*
-    |--------------------------------------------------------------------------
-    | 2️⃣ Multi Duration Ranges
-    |--------------------------------------------------------------------------
-    | duration stored in minutes (integer)
-    |--------------------------------------------------------------------------
-    */
+    $media = $query->get();
 
-    if ($request->filled('durations')) {
+    // 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 ?? '');
+    });
 
-        $ranges = explode(',', $request->durations);
-
-        $query->where(function ($q) use ($ranges) {
-
-            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);
-                }
-            }
+    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) {
+            $q->whereIn('categories.id', $categories);
         });
     }
 
-    /*
-    |--------------------------------------------------------------------------
-    | 3️⃣ Tags
-    |--------------------------------------------------------------------------
-    */
+    if ($request->filled('subcategories')) {
+        $subcategories = explode(',', $request->subcategories);
+        $query->whereHas('subCategories', function ($q) use ($subcategories) {
+            $q->whereIn('sub_categories.id', $subcategories);
+        });
+    }
+
+    // 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])
+        );
+
+        if (!empty($ranges)) {
+            $query->where(function ($q) use ($ranges, $defs) {
+                foreach ($ranges as $range) {
+                    if ($range === '120-') {
+                        $q->orWhere('duration', '>', $this->durationOtherMin());
+                    } else {
+                        $q->orWhereBetween('duration', $defs[$range]);
+                    }
+                }
+            });
+        }
+    }
 
     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('category', function ($c) use ($search) {
+              ->orWhereHas('categories', function ($c) use ($search) {
                   $c->where('name', 'LIKE', "%$search%");
               })
+              ->orWhereHas('subCategories', function ($s) use ($search) {
+                  $s->where('name', 'LIKE', "%$search%");
+              })
               ->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)
@@ -266,21 +306,28 @@ public function filters(Request $request)
     |--------------------------------------------------------------------------
     */
 
-    $categories = Category::select(
-            'categories.id',
-            'categories.name',
-            DB::raw('COUNT(media.id) as media_count')
-        )
-        ->leftJoin('media', function ($join) {
-            $join->on('categories.id', '=', 'media.category_id')
-                ->where(function ($q) {
-                    $q->where('media.visibility', 'public')
-                      ->orWhere('media.user_id', auth()->id());
-                });
-        })
-        ->groupBy('categories.id', 'categories.name')
+    $visibleMedia = function ($q) {
+        $q->where(function ($inner) {
+            $inner->where('media.visibility', 'public')
+                  ->orWhere('media.user_id', auth()->id());
+        });
+    };
+
+    $categories = Category::query()
+        ->withCount(['media as media_count' => $visibleMedia])
         ->orderByDesc('media_count')
-        ->get();
+        ->get(['id', 'name', 'description', 'icon']);
+
+    /*
+    |--------------------------------------------------------------------------
+    | 1️⃣.5 Subcategories with media count
+    |--------------------------------------------------------------------------
+    */
+
+    $subcategories = SubCategory::query()
+        ->withCount(['media as media_count' => $visibleMedia])
+        ->orderByDesc('media_count')
+        ->get(['id', 'category_id', 'name', 'description']);
 
 
     /*
@@ -291,40 +338,71 @@ 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,
-        'durations'  => $durations,
+        'categories'    => $categories,
+        'subcategories' => $subcategories,
+        'durations'     => $durations,
     ]);
 }
 
+// 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', 
-            'category', 
-            'myNote', 
+            'image',
+            'detailImage',
+            'categories',
+            'subCategories',
+            'myNote',
             'tags',
             'comments' => function($query) {
                 $query->with('user')->latest()->limit(10);
@@ -340,13 +418,15 @@ public function show($id)
 
     // Get user's specific comment
     $userComment = $media->userComment();
-    
+
     // Get paginated comments
     $comments = $media->comments()
         ->with('user')
         ->latest()
         ->paginate(15);
 
+    $similarMedia = $this->similarMedia($media);
+
     return response()->json([
         'id' => $media->id,
         'title' => $media->title,
@@ -360,14 +440,21 @@ public function show($id)
         'updated_at' => $media->updated_at,
         'is_premium' => $media->is_premium,
         'image' => $media->image,
-        'category' => $media->category,
+        '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' => [
@@ -376,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([
@@ -442,33 +580,31 @@ public function update(Request $request, $id)
         'caption' => 'nullable|string',
         'type' => 'nullable|in:audio,video',
 
-        // support both: category_id or category_name
-        'category_id' => 'nullable|exists:categories,id',
-        'category_name' => 'nullable|string|max:255',
+        'category_ids' => 'nullable|array',
+        'category_ids.*' => 'integer|exists:categories,id',
+        'subcategory_ids' => 'nullable|array',
+        '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',
         'tags.*' => 'string',
     ]);
 
-    // --- handle auto-create category ---
-    $categoryId = $data['category_id'] ?? $media->category_id;
-
-    if (isset($data['category_name'])) {
-        $category = Category::firstOrCreate([
-            'name' => $data['category_name']
-        ]);
-        $categoryId = $category->id;
-    }
-
     // --- handle file replace ---
     if ($request->hasFile('file')) {
-        Storage::disk('public')->delete($media->file_path);
-        $data['file_path'] = $request->file('file')->store('media', 'public');
+        if ($media->file_path) {
+            Storage::disk('public')->delete($media->file_path);
+        }
+        $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 ---
@@ -476,7 +612,6 @@ public function update(Request $request, $id)
         'title' => $data['title'] ?? $media->title,
         'caption' => $data['caption'] ?? $media->caption,
         'type' => $data['type'] ?? $media->type,
-        'category_id' => $categoryId,
         'is_premium' => $data['is_premium'] ?? $media->is_premium,
         'duration' => $data['duration'] ?? $media->duration,
         'external_url' => $data['external_url'] ?? $media->external_url,
@@ -484,18 +619,39 @@ 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);
 
+    if (array_key_exists('category_ids', $data)) {
+        $media->categories()->sync($data['category_ids'] ?? []);
+    }
+
+    if (array_key_exists('subcategory_ids', $data)) {
+        $media->subCategories()->sync($data['subcategory_ids'] ?? []);
+    }
+
     if (isset($data['tags'])) {
         $tagIds = [];
 
@@ -509,7 +665,7 @@ public function update(Request $request, $id)
 
     return response()->json([
         'message' => 'Media updated successfully',
-        'media' => $media->load(['image', 'category' , 'tags']),
+        'media' => $media->load(['image', 'detailImage', 'categories', 'subCategories', 'tags']),
     ]);
 }
 
@@ -520,33 +676,106 @@ public function destroy($id)
             ->where('user_id', auth()->id())
             ->firstOrFail();
 
-        Storage::disk('public')->delete($media->file_path);
+        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','category' , '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).
+    public function recordPlay($id)
+    {
+        $media = Media::where('id', $id)
+            ->where(function ($q) {
+                $q->where('visibility', 'public')->orWhere('user_id', auth()->id());
+            })
+            ->firstOrFail();
+
+        $play = MediaPlay::firstOrNew([
+            'user_id' => auth()->id(),
+            'media_id' => $media->id,
+        ]);
+        $play->play_count = ($play->play_count ?? 0) + 1;
+        $play->last_played_at = now();
+        $play->save();
+
+        return response()->json([
+            'message' => 'Play recorded',
+            'play_count' => $play->play_count,
+            'last_played_at' => $play->last_played_at,
+        ]);
+    }
+
+    // POPULAR media (global), ranked by total play count across all users.
+    public function popular(Request $request)
+    {
+        $limit = (int) $request->input('limit', 20);
+
+        $media = Media::query()
+            ->where(function ($q) {
+                $q->where('visibility', 'public')->orWhere('user_id', auth()->id());
+            })
+            ->withCount('plays as listeners_count')                 // distinct users who played
+            ->withSum('plays as plays_count', 'play_count')         // total plays
+            ->with(['image', 'detailImage', 'categories', 'subCategories', 'tags'])
+            ->orderByDesc('plays_count')
+            ->orderByDesc('listeners_count')
+            ->orderByDesc('created_at')
+            ->limit($limit)
+            ->get();
+
+        return response()->json($media);
+    }
+
+    // RECENTLY PLAYED media for the current user, most recent first.
+    public function recentlyPlayed(Request $request)
+    {
+        $limit = (int) $request->input('limit', 20);
+
+        $plays = MediaPlay::where('user_id', auth()->id())
+            ->whereNotNull('last_played_at')
+            ->with(['media' => fn ($q) => $q->with(['image', 'detailImage', 'categories', 'subCategories', 'tags'])])
+            ->orderByDesc('last_played_at')
+            ->limit($limit)
+            ->get();
+
+        $media = $plays->map(function ($play) {
+            $media = $play->media;
+            if (!$media) {
+                return null;
+            }
+            $media->last_played_at = $play->last_played_at;
+            $media->play_count = $play->play_count;
+            return $media;
+        })->filter()->values();
+
+        return response()->json($media);
     }
 
 public function storeNote(Request $request, $mediaId)

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();
@@ -82,13 +89,48 @@ public function show($id)
     {
         $category = MusicCategory::with(['image', 'playlists' => function($q) {
             $q->with(['image', 'musics' => function($q2) {
-                $q2->where('is_active', true)->with('image')->orderBy('order');
+                $q2->where('music.is_active', true)->with('image')->orderBy('music_playlist.order');
             }])->where('is_active', true)->orderBy('order');
         }])->findOrFail($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,14 +139,20 @@ 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',
         ]);
-        
+
         if (isset($data['name'])) {
             $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,17 +5,20 @@
 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()
     {
         $userId = auth()->id();
 
-        $music = Music::with(['image', 'playlist'])
+        $music = Music::with(['image', 'playlists'])
             ->where('type', 'public')
             ->orWhere(function($query) use ($userId) {
                 $query->where('type', 'private')
@@ -29,41 +32,47 @@ public function getAllMusic()
         return response()->json($music);
     }
 
-    public function index()
+    public function index(Request $request)
     {
         $userId = auth()->id();
 
-        $music = Music::with(['image', 'playlist'])
-            ->where('type', 'public')
-            ->orWhere(function($query) use ($userId) {
-                $query->where('type', 'private')
-                      ->where('user_id', $userId);
+        // 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(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)
     {
         $playlist = MusicPlaylist::findOrFail($playlistId);
-        
-        $music = Music::where('playlist_id', $playlistId)
-            ->where('is_active', true)
+
+        $music = $playlist->musics()
+            ->where('music.is_active', true)
             ->with(['image', 'tags'])
-            ->orderBy('order')
+            ->orderBy('music_playlist.order')
             ->get();
-        
+
         return response()->json([
             'playlist' => $playlist->load('image'),
             'musics' => $music
         ]);
     }
-    
+
     public function addToPlaylist(Request $request, $musicId)
     {
         $music = Music::where('id', $musicId)
@@ -72,48 +81,57 @@ public function addToPlaylist(Request $request, $musicId)
                   ->orWhere('user_id', auth()->id());
             })
             ->firstOrFail();
-        
+
         $data = $request->validate([
             'playlist_id' => 'required|exists:music_playlists,id',
             'order' => 'nullable|integer',
         ]);
-        
-        $music->update([
-            'playlist_id' => $data['playlist_id'],
-            'order' => $data['order'] ?? $music->order,
+
+        $order = $data['order'] ?? $this->getNextOrderInPlaylist($data['playlist_id']);
+
+        // Add (or update its order) without removing the music from other playlists.
+        $music->playlists()->syncWithoutDetaching([
+            $data['playlist_id'] => ['order' => $order],
         ]);
-        
+
         return response()->json([
             'message' => 'Music added to playlist successfully',
-            'music' => $music->load(['image', 'playlist'])
+            'music' => $music->load(['image', 'playlists'])
         ]);
     }
-    
-    public function removeFromPlaylist($musicId)
+
+    public function removeFromPlaylist(Request $request, $musicId)
     {
         $music = Music::where('id', $musicId)
             ->where('user_id', auth()->id())
             ->firstOrFail();
-        
-        $music->update(['playlist_id' => null]);
-        
+
+        $data = $request->validate([
+            'playlist_id' => 'required|exists:music_playlists,id',
+        ]);
+
+        $music->playlists()->detach($data['playlist_id']);
+
         return response()->json(['message' => 'Music removed from playlist']);
     }
-    
+
     public function updateOrder(Request $request)
     {
         $data = $request->validate([
+            'playlist_id' => 'required|exists:music_playlists,id',
             'musics' => 'required|array',
             'musics.*.id' => 'required|exists:music,id',
             'musics.*.order' => 'required|integer',
         ]);
-        
+
+        $playlist = MusicPlaylist::findOrFail($data['playlist_id']);
+
         foreach ($data['musics'] as $item) {
-            Music::where('id', $item['id'])
-                ->where('user_id', auth()->id())
-                ->update(['order' => $item['order']]);
+            $playlist->musics()->updateExistingPivot($item['id'], [
+                'order' => $item['order'],
+            ]);
         }
-        
+
         return response()->json(['message' => 'Order updated successfully']);
     }
     // ✅ Upload music
@@ -123,10 +141,13 @@ 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',
-                'playlist_id' => 'nullable|exists:music_playlists,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',
                 'duration' => 'nullable|integer|min:1', // validates mm:ss or hh:mm:ss
             ]);
 
@@ -146,30 +167,44 @@ public function store(Request $request)
                 ], 422);
             }
 
-            $path = $file->store('music', 'public');
-            
+            $path = $this->storeUpload($file, 'music');
+
             if (!$path) {
                 return response()->json([
                     'message' => 'Failed to store the file'
                 ], 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,
-                'playlist_id' => $data['playlist_id'] ?? null,
+                'image_id' => $imageId,
                 'duration' => $data['duration'] ?? null, // Store as string
-                'order' => $this->getNextOrderInPlaylist($data['playlist_id'] ?? null),
                 'is_active' => true,
             ]);
 
+            // Merge single + multiple playlist inputs into a unique list.
+            $playlistIds = collect($data['playlist_ids'] ?? [])
+                ->push($data['playlist_id'] ?? null)
+                ->filter()
+                ->unique()
+                ->values();
+
+            foreach ($playlistIds as $playlistId) {
+                $music->playlists()->syncWithoutDetaching([
+                    $playlistId => ['order' => $this->getNextOrderInPlaylist($playlistId)],
+                ]);
+            }
+
             return response()->json([
                 'message' => 'Music uploaded successfully',
-                'music' => $music->load(['image', 'playlist', 'tags']),
+                'music' => $music->load(['image', 'playlists', 'tags']),
                 'url' => asset('storage/' . $path),
             ], 201);
             
@@ -192,8 +227,11 @@ private function getNextOrderInPlaylist($playlistId)
         if (!$playlistId) {
             return 0;
         }
-        
-        $maxOrder = Music::where('playlist_id', $playlistId)->max('order');
+
+        $maxOrder = \DB::table('music_playlist')
+            ->where('playlist_id', $playlistId)
+            ->max('order');
+
         return ($maxOrder ?? -1) + 1;
     }
 
@@ -207,28 +245,36 @@ 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',
-                'playlist_id' => 'nullable|exists:music_playlists,id',
+                'image' => 'nullable|file|extensions:jpg,jpeg,png,gif,webp,bmp,svg|max:8192',
                 'duration' => 'nullable|integer|min:1',
-                'order' => 'nullable|integer',
                 'is_active' => 'nullable|boolean',
             ]);
 
             if ($request->hasFile('file')) {
                 // Delete old file
-                Storage::disk('public')->delete($music->file_path);
-                $path = $request->file('file')->store('music', 'public');
+                if ($music->file_path) {
+                    Storage::disk('public')->delete($music->file_path);
+                }
+                $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([
                 'message' => 'Music updated successfully',
-                'music' => $music->load(['image', 'playlist', 'tags']),
+                'music' => $music->load(['image', 'playlists', 'tags']),
                 'url' => asset('storage/' . $music->file_path),
             ]);
             
@@ -247,8 +293,8 @@ public function show($id)
     $userId = auth()->id();
 
     $music = Music::with([
-            'image', 
-            'playlist', 
+            'image',
+            'playlists',
             'tags',
             'comments' => function($query) {
                 $query->with('user')->latest()->limit(10);
@@ -296,7 +342,9 @@ public function show($id)
     public function destroy($id)
     {
         $music = Music::where('id', $id)->where('user_id', auth()->id())->firstOrFail();
-        Storage::disk('public')->delete($music->file_path);
+        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,102 +3,207 @@
 namespace App\Http\Controllers;
 
 use App\Models\MusicPlaylist;
+use App\Traits\HandlesImageUpload;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
 
 class MusicPlaylistController extends Controller
 {
-   public function index(Request $request)
+    use HandlesImageUpload;
+
+   public function index(Request $request, $categoryId = null)
         {
-            $query = MusicPlaylist::with(['category', 'subcategory', 'image']);
-            
-            if ($request->has('category_id')) {
-                $query->where('category_id', $request->category_id)->whereNull('subcategory_id');
+            $query = MusicPlaylist::with(['categories', 'subcategories', 'image', 'detailImage']);
+
+            $categoryId = $categoryId ?? $request->input('category_id');
+
+            if ($categoryId) {
+                $query->whereHas('categories', function ($q) use ($categoryId) {
+                    $q->where('music_categories.id', $categoryId);
+                });
             }
-            
-            if ($request->has('subcategory_id')) {
-                $query->where('subcategory_id', $request->subcategory_id);
+
+            if ($request->filled('subcategory_id')) {
+                $subcategoryId = $request->input('subcategory_id');
+                $query->whereHas('subcategories', function ($q) use ($subcategoryId) {
+                    $q->where('music_subcategories.id', $subcategoryId);
+                });
             }
-            
+
             $playlists = $query->where('is_active', true)->orderBy('order')->get();
-            
+
             return response()->json($playlists);
         }
             
     public function store(Request $request)
 {
     $data = $request->validate([
-        'category_id' => 'nullable|exists:music_categories,id',
-        'subcategory_id' => 'nullable|exists:music_subcategories,id',
+        'category_ids' => 'nullable|array',
+        'category_ids.*' => 'integer|exists:music_categories,id',
+        'subcategory_ids' => 'nullable|array',
+        'subcategory_ids.*' => 'integer|exists:music_subcategories,id',
         '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 either category_id or subcategory_id is provided
-    if (!$data['category_id'] && !$data['subcategory_id']) {
+
+    // Ensure at least one category or subcategory is provided
+    if (empty($data['category_ids']) && empty($data['subcategory_ids'])) {
         return response()->json([
-            'message' => 'Either category_id or subcategory_id is required'
+            'message' => 'At least one category or subcategory is required'
         ], 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);
-    
+
+    $playlist->categories()->sync($data['category_ids'] ?? []);
+    $playlist->subcategories()->sync($data['subcategory_ids'] ?? []);
+
     return response()->json([
         'message' => 'Playlist created successfully',
-        'playlist' => $playlist->load(['category', 'subcategory', 'image'])
+        'playlist' => $playlist->load(['categories', 'subcategories', 'image', 'detailImage'])
     ], 201);
 }
     
     public function show($id)
-    {
-        $playlist = MusicPlaylist::with([
-            'category', 
-            'image', 
-            'musics' => function($q) {
-                $q->where('is_active', true)
-                  ->with(['image', 'tags'])
-                  ->orderBy('order');
-            }
-        ])->findOrFail($id);
-        
-        return response()->json($playlist);
-    }
+        {
+            $playlist = MusicPlaylist::with([
+                'categories',
+                'subcategories',
+                'image',
+                'detailImage',
+                'musics' => function($q) {
+                    $q->where('music.is_active', true)
+                    ->with(['image', 'tags'])
+                    ->orderBy('music_playlist.order');
+                },
+                'comments' => function($q) { // Add comments relationship
+                    $q->with('user')->latest()->limit(10);
+                }
+            ])->findOrFail($id);
+            $userComment = $playlist->userComment();
+            $comments = $playlist->comments()
+                ->with('user')
+                ->latest()
+                ->paginate(15);
+            
+            $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,
+                        'user_comment' => $playlist->user_comment,
+                        '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)
     {
         $playlist = MusicPlaylist::findOrFail($id);
         
         $data = $request->validate([
-            'category_id' => 'sometimes|exists:music_categories,id',
+            'category_ids' => 'sometimes|array',
+            'category_ids.*' => 'integer|exists:music_categories,id',
+            'subcategory_ids' => 'sometimes|array',
+            'subcategory_ids.*' => 'integer|exists:music_subcategories,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);
-        
+
+        if (array_key_exists('category_ids', $data)) {
+            $playlist->categories()->sync($data['category_ids'] ?? []);
+        }
+
+        if (array_key_exists('subcategory_ids', $data)) {
+            $playlist->subcategories()->sync($data['subcategory_ids'] ?? []);
+        }
+
         return response()->json([
             'message' => 'Playlist updated successfully',
-            'playlist' => $playlist->load(['category', '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);
         $playlist->delete();
-        
+
         return response()->json(['message' => 'Playlist deleted successfully']);
     }
 }

app/Http/Controllers/MusicSubcategoryController.php

@@ -74,7 +74,7 @@ public function show($id)
             'image',
             'playlists' => function($q) {
                 $q->with(['image', 'musics' => function($q2) {
-                    $q2->where('is_active', true)->with('image')->orderBy('order');
+                    $q2->where('music.is_active', true)->with('image')->orderBy('music_playlist.order');
                 }])->where('is_active', true)->orderBy('order');
             }
         ])->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,16 +4,29 @@
 
 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.)
      */
     public function save(Request $request)
     {
         $request->validate([
-            'type' => 'required|string|in:music,media,breathing-template',
+            'type' => 'required|string|in:music,media,breathing-template,playlist',
             'id' => 'required|integer',
         ]);
         
@@ -40,7 +53,7 @@ public function save(Request $request)
     public function unsave(Request $request)
     {
         $request->validate([
-            'type' => 'required|string|in:music,media,breathing-template',
+            'type' => 'required|string|in:music,media,breathing-template,playlist',
             'id' => 'required|integer',
         ]);
         
@@ -67,7 +80,7 @@ public function unsave(Request $request)
     public function toggleSave(Request $request)
     {
         $request->validate([
-            'type' => 'required|string|in:music,media,breathing-template',
+            'type' => 'required|string|in:music,media,breathing-template,playlist',
             'id' => 'required|integer',
         ]);
         
@@ -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) {
@@ -112,6 +125,7 @@ public function mySavedItems(Request $request)
                 'music' => 'App\\Models\\Music',
                 'media' => 'App\\Models\\Media',
                 'breathing-template' => 'App\\Models\\BreathingTemplate',
+                'playlist' => 'App\\Models\\MusicPlaylist',
             ]
         ]);
     }
@@ -121,7 +135,7 @@ public function mySavedItems(Request $request)
     public function checkSaved(Request $request)
     {
         $request->validate([
-            'type' => 'required|string|in:music,media,breathing-template',
+            'type' => 'required|string|in:music,media,breathing-template,playlist',
             'id' => 'required|integer',
         ]);
         
@@ -151,8 +165,9 @@ private function getModelClass($type)
             'music' => \App\Models\Music::class,
             'media' => \App\Models\Media::class,
             'breathing-template' => \App\Models\BreathingTemplate::class,
+            'playlist' => \App\Models\MusicPlaylist::class,
         ];
-        
+
         return $models[$type] ?? null;
     }
 }

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,37 +4,75 @@
 
 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([
             'title' => 'required|string|max:255',
             'description' => 'nullable|string',
             'url' => 'nullable|string|max:500',
-            'action' => 'nullable|array', 
+            '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

@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\SubCategory;
+use Illuminate\Http\Request;
+
+class SubCategoryController extends Controller
+{
+    public function index(Request $request, $categoryId = null)
+    {
+        $query = SubCategory::with('category')->withCount('media');
+
+        $categoryId = $categoryId ?? $request->input('category_id');
+
+        if ($categoryId) {
+            $query->where('category_id', $categoryId);
+        }
+
+        return response()->json(
+            $query->orderBy('name')->get()
+        );
+    }
+
+    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'])
+            ->where('name', $data['name'])
+            ->first();
+
+        if ($existing) {
+            return response()->json([
+                'message' => 'A subcategory with this name already exists in this category',
+                'errors' => ['name' => ['The subcategory name must be unique within this category.']],
+            ], 422);
+        }
+
+        $subCategory = SubCategory::create($data);
+
+        return response()->json([
+            'message' => 'Subcategory created successfully',
+            'sub_category' => $subCategory->load('category'),
+        ], 201);
+    }
+
+    public function show($id)
+    {
+        $subCategory = SubCategory::with('category')->withCount('media')->findOrFail($id);
+
+        return response()->json($subCategory);
+    }
+
+    public function update(Request $request, $id)
+    {
+        $subCategory = SubCategory::findOrFail($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;
+        $name = $data['name'] ?? $subCategory->name;
+
+        $existing = SubCategory::where('category_id', $categoryId)
+            ->where('name', $name)
+            ->where('id', '!=', $subCategory->id)
+            ->first();
+
+        if ($existing) {
+            return response()->json([
+                'message' => 'A subcategory with this name already exists in this category',
+                'errors' => ['name' => ['The subcategory name must be unique within this category.']],
+            ], 422);
+        }
+
+        $subCategory->update($data);
+
+        return response()->json([
+            'message' => 'Subcategory updated successfully',
+            'sub_category' => $subCategory->load('category'),
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        $subCategory = SubCategory::findOrFail($id);
+        $subCategory->delete();
+
+        return response()->json(['message' => 'Subcategory deleted successfully']);
+    }
+}

app/Http/Controllers/SurveyQuestionController.php

@@ -0,0 +1,499 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Models\Media;
+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
+{
+    // USER: list active questions with their options and the current user's own answers.
+    public function index(Request $request)
+    {
+        $questions = SurveyQuestion::with(['options.tags', 'userAnswers'])
+            ->where('is_active', true)
+            ->orderBy('order')
+            ->get();
+
+        return response()->json($questions);
+    }
+
+    // USER: a single question with its options and the current user's own answers.
+    public function show($id)
+    {
+        $question = SurveyQuestion::with(['options.tags', 'userAnswers'])->findOrFail($id);
+
+        return response()->json($question);
+    }
+
+    // ADMIN: list every question (incl. inactive) with options (+ vote tallies) and all answers.
+    public function adminIndex(Request $request)
+    {
+        $questions = SurveyQuestion::with([
+                'options' => fn ($q) => $q->withCount('answers')->with('tags'),
+                'answers' => fn ($q) => $q->with(['user', 'option']),
+            ])
+            ->orderBy('order')
+            ->get();
+
+        return response()->json($questions);
+    }
+
+    // ADMIN: a single question with options (+ vote tallies) and all users' answers.
+    public function adminShow($id)
+    {
+        $question = SurveyQuestion::with([
+                'options' => fn ($q) => $q->withCount('answers')->with('tags'),
+                'answers' => fn ($q) => $q->with(['user', 'option']),
+            ])
+            ->findOrFail($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)
+    {
+        $query = SurveyQuestion::with(['options' => fn ($q) => $q->withCount('answers')]);
+
+        if (!is_null($id)) {
+            $query->where('id', $id);
+        }
+
+        $questions = $query->orderBy('order')->get();
+
+        if (!is_null($id) && $questions->isEmpty()) {
+            abort(404);
+        }
+
+        $analytics = $questions->map(function (SurveyQuestion $question) {
+            // Respondents = distinct users who answered (not number of selections).
+            $respondents = $question->answers()->distinct('user_id')->count('user_id');
+            $totalSelections = (int) $question->options->sum('answers_count');
+
+            return [
+                'id' => $question->id,
+                'question' => $question->question,
+                'description' => $question->description,
+                'type' => $question->type,
+                'is_active' => $question->is_active,
+                'total_respondents' => $respondents,
+                'total_selections' => $totalSelections,
+                'options' => $question->options->map(function ($option) use ($respondents) {
+                    $votes = (int) $option->answers_count;
+
+                    return [
+                        'id' => $option->id,
+                        'label' => $option->label,
+                        'value' => $option->value,
+                        'votes' => $votes,
+                        // % of respondents who picked this option (can exceed 100% summed for multi-select).
+                        'percentage' => $respondents > 0 ? round($votes / $respondents * 100, 1) : 0,
+                    ];
+                })->values(),
+            ];
+        });
+
+        return response()->json(is_null($id) ? $analytics->values() : $analytics->first());
+    }
+
+    // CREATE a question together with its options.
+    public function store(Request $request)
+    {
+        $data = $request->validate([
+            'question' => 'required|string|max:255',
+            'description' => 'nullable|string',
+            'type' => 'required|in:single,multiple',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+            'options' => 'required|array|min:1',
+            'options.*.label' => 'required|string|max:255',
+            'options.*.value' => 'nullable|string|max:255',
+            'options.*.order' => 'nullable|integer',
+            'options.*.tags' => 'nullable|array',
+            'options.*.tags.*' => 'string',
+        ]);
+
+        $question = DB::transaction(function () use ($data) {
+            $question = SurveyQuestion::create([
+                'question' => $data['question'],
+                'description' => $data['description'] ?? null,
+                'type' => $data['type'],
+                'order' => $data['order'] ?? 0,
+                'is_active' => $data['is_active'] ?? true,
+            ]);
+
+            $this->syncOptions($question, $data['options']);
+
+            return $question;
+        });
+
+        return response()->json([
+            'message' => 'Question created successfully',
+            'question' => $question->load('options.tags'),
+        ], 201);
+    }
+
+    // UPDATE a question; if options are provided they replace the existing set.
+    public function update(Request $request, $id)
+    {
+        $question = SurveyQuestion::findOrFail($id);
+
+        $data = $request->validate([
+            'question' => 'sometimes|string|max:255',
+            'description' => 'nullable|string',
+            'type' => 'sometimes|in:single,multiple',
+            'order' => 'nullable|integer',
+            'is_active' => 'nullable|boolean',
+            'options' => 'sometimes|array|min:1',
+            'options.*.label' => 'required_with:options|string|max:255',
+            'options.*.value' => 'nullable|string|max:255',
+            'options.*.order' => 'nullable|integer',
+            'options.*.tags' => 'nullable|array',
+            'options.*.tags.*' => 'string',
+        ]);
+
+        DB::transaction(function () use ($question, $data) {
+            $question->update(array_filter(
+                [
+                    'question' => $data['question'] ?? null,
+                    'description' => array_key_exists('description', $data) ? $data['description'] : null,
+                    'type' => $data['type'] ?? null,
+                    'order' => $data['order'] ?? null,
+                    'is_active' => $data['is_active'] ?? null,
+                ],
+                fn ($value) => !is_null($value)
+            ));
+
+            if (array_key_exists('options', $data)) {
+                // Replacing options invalidates existing answers for this question.
+                $question->answers()->delete();
+                $question->options()->delete();
+                $this->syncOptions($question, $data['options']);
+            }
+        });
+
+        return response()->json([
+            'message' => 'Question updated successfully',
+            'question' => $question->load('options.tags'),
+        ]);
+    }
+
+    public function destroy($id)
+    {
+        $question = SurveyQuestion::findOrFail($id);
+        $question->delete(); // options + answers cascade
+
+        return response()->json(['message' => 'Question deleted successfully']);
+    }
+
+    // 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' => 'nullable|array',
+            'option_ids.*' => 'integer',
+        ]);
+
+        $userId = auth()->id();
+
+        DB::transaction(function () use ($question, $data, $userId) {
+            $this->syncAnswerFor($question, $data['option_ids'] ?? [], $userId);
+        });
+
+        return response()->json([
+            'message' => 'Answer submitted successfully',
+            'question' => $question->load(['options', 'userAnswers']),
+        ]);
+    }
+
+    // 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');
+
+        // 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();
+
+        // Visible to this user: public or their own.
+        $visible = function ($q) use ($userId) {
+            $q->where('visibility', 'public')->orWhere('user_id', $userId);
+        };
+
+        $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($visible)
+                ->with($eager)
+                ->orderByDesc('match_count')
+                ->orderByDesc('created_at')
+                ->get();
+
+            // 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
+    {
+        foreach (array_values($options) as $i => $option) {
+            $created = $question->options()->create([
+                'label' => $option['label'],
+                'value' => $option['value'] ?? null,
+                'order' => $option['order'] ?? $i,
+            ]);
+
+            if (!empty($option['tags'])) {
+                $tagIds = collect($option['tags'])
+                    ->map(fn ($name) => Tag::firstOrCreate(['name' => $name])->id)
+                    ->all();
+
+                $created->tags()->sync($tagIds);
+            }
+        }
+    }
+}

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

@@ -43,11 +43,17 @@ public function loginV2(Request $request)
         if (!empty($response['uuid'])) {
             $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, 
+            '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,11 +6,42 @@
 
 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()
     {
         return $this->hasMany(Question::class);
     }
+
+    public function subcategories()
+    {
+        return $this->hasMany(SubCategory::class);
+    }
+
+    public function media()
+    {
+        return $this->belongsToMany(Media::class, 'category_media');
+    }
 }
 

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/Like.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+class Like extends Model
+{
+    protected $table = 'likes';
+    
+    protected $fillable = [
+        'user_id',
+        'likeable_id',
+        'likeable_type',
+    ];
+    
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+    
+    public function likeable(): MorphTo
+    {
+        return $this->morphTo();
+    }
+    
+    // Helper methods
+    public static function getLikedItemsForUser($userId, $type = null)
+    {
+        $query = self::with('likeable')->where('user_id', $userId);
+        
+        if ($type) {
+            $query->where('likeable_type', $type);
+        }
+        
+        return $query->latest()->get();
+    }
+    
+    public static function isLikedByUser($userId, $likeableId, $likeableType)
+    {
+        return self::where([
+            'user_id' => $userId,
+            'likeable_id' => $likeableId,
+            'likeable_type' => $likeableType,
+        ])->exists();
+    }
+    
+    public static function getLikeCount($likeableId, $likeableType)
+    {
+        return self::where([
+            'likeable_id' => $likeableId,
+            'likeable_type' => $likeableType,
+        ])->count();
+    }
+}

app/Models/Media.php

@@ -6,14 +6,14 @@
 use App\Traits\HasRatings;
 use App\Traits\HasComments;
 use App\Traits\HasSaves;
-
+use App\Traits\HasLikes;
 class Media extends Model
 {
-     use HasRatings, HasComments,HasSaves;
+     use HasRatings, HasComments,HasSaves,HasLikes;
   protected $fillable = [
         'user_id',
         'image_id',
-        'category_id',
+        'detail_image_id',
         'title',
         'caption',
         'type',
@@ -32,22 +32,41 @@ class Media extends Model
         'user_comment',         
         'user_comment_id',      
         'has_user_rated',   
-        'is_saved', 
-        'saved_count'      
+        'is_saved',
+        'saved_count',
+        'is_liked',
+        'likes_count',
+        'url',
     ];
     public function image()
     {
         return $this->belongsTo(Image::class);
     }
 
-    public function category()
+    // Image shown on the detail (show-by-id) screen; image() is the list thumbnail.
+    public function detailImage()
     {
-        return $this->belongsTo(Category::class);
+        return $this->belongsTo(Image::class, 'detail_image_id');
+    }
+
+    public function categories()
+    {
+        return $this->belongsToMany(Category::class, 'category_media');
+    }
+
+    public function subCategories()
+    {
+        return $this->belongsToMany(SubCategory::class, 'media_sub_category');
     }
     public function tags()
     {
         return $this->belongsToMany(Tag::class, 'media_tag');
     }
+
+    public function plays()
+    {
+        return $this->hasMany(MediaPlay::class);
+    }
     public function notes()
     {
         return $this->morphMany(Note::class, 'noteable');
@@ -70,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/MediaPlay.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class MediaPlay extends Model
+{
+    protected $fillable = ['user_id', 'media_id', 'play_count', 'last_played_at'];
+
+    protected $casts = [
+        'play_count' => 'integer',
+        'last_played_at' => 'datetime',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function media(): BelongsTo
+    {
+        return $this->belongsTo(Media::class);
+    }
+}

app/Models/Music.php

@@ -11,20 +11,20 @@
 use App\Traits\HasRatings;
 use App\Traits\HasComments;
 use App\Traits\HasSaves;
+use App\Traits\HasLikes;
 
 class Music extends Model
 {   
-     use HasFactory, HasRatings, HasComments , HasSaves;
+     use HasFactory, HasRatings, HasComments , HasSaves,HasLikes;
      protected $table = 'music';
     
 
     protected $fillable = [
-    'user_id', 'title', 'artist', 'file_path', 'type', 
-        'playlist_id', 'image_id', 'duration', 'order', 'is_active'
+    'user_id', 'title', 'artist', 'file_path', 'type',
+        'image_id', 'duration', 'is_active'
     ];
  protected $casts = [
         'duration' => 'integer',
-        'order' => 'integer',
         'is_active' => 'boolean',
     ];
     protected $attributes = [
@@ -35,9 +35,11 @@ public function user()
     {
         return $this->belongsTo(User::class);
     }
-     public function playlist(): BelongsTo
+     public function playlists(): BelongsToMany
     {
-        return $this->belongsTo(MusicPlaylist::class, 'playlist_id');
+        return $this->belongsToMany(MusicPlaylist::class, 'music_playlist', 'music_id', 'playlist_id')
+            ->withPivot('order')
+            ->withTimestamps();
     }
      public function tags(): BelongsToMany
     {
@@ -54,7 +56,9 @@ public function tags(): BelongsToMany
     'user_comment_id',         
     'has_user_rated' ,
     'is_saved', 
-    'saved_count'         
+    'saved_count',
+    'is_liked',
+    'likes_count'      
     ];
 
     public function getUrlAttribute()

app/Models/MusicCategory.php

@@ -4,23 +4,34 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;  // ← Add this
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 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 = [
         'name', 'slug', 'description', 'image_id', 'order', 'is_active'
     ];
-    
+
     protected $casts = [
         'is_active' => 'boolean',
         'order' => 'integer',
     ];
 
-    public function playlists(): HasMany
+    protected $appends = ['type'];
+
+    public function getTypeAttribute(): string
     {
-        return $this->hasMany(MusicPlaylist::class, 'category_id');
+        return self::TYPE;
+    }
+
+    public function playlists(): BelongsToMany
+    {
+        return $this->belongsToMany(MusicPlaylist::class, 'music_category_playlist', 'category_id', 'playlist_id');
     }
 
     public function subcategories(): HasMany
@@ -45,7 +56,7 @@ public function image(): BelongsTo
     
     public function getActivePlaylistsAttribute()
     {
-        return $this->playlists()->where('is_active', true)->get();
+        return $this->playlists()->where('music_playlists.is_active', true)->get();
     }
 
       // Total music count across all playlists and subcategories

app/Models/MusicPlaylist.php

@@ -4,48 +4,79 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;  // ← Add this
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;    // ← Add this
+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, HasRatings;
     protected $table = 'music_playlists';
     
     protected $fillable = [
-        'category_id', 'subcategory_id','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',
     ];
-    
-    public function category(): BelongsTo
+    protected $appends = [
+        'comments_count',
+        'has_user_commented',
+        'user_comment',
+        'user_comment_id',
+        'is_liked',
+        'likes_count',
+        'is_saved',
+        'saved_count',
+        'duration',
+    ];
+    public function categories(): BelongsToMany
     {
-        return $this->belongsTo(MusicCategory::class, 'category_id');
+        return $this->belongsToMany(MusicCategory::class, 'music_category_playlist', 'playlist_id', 'category_id');
     }
-    
-     public function subcategory(): BelongsTo
+
+    public function subcategories(): BelongsToMany
     {
-        return $this->belongsTo(MusicSubcategory::class, 'subcategory_id');
+        return $this->belongsToMany(MusicSubcategory::class, 'music_subcategory_playlist', 'playlist_id', 'subcategory_id');
     }
     
     
-    public function musics(): HasMany
+    public function musics(): BelongsToMany
     {
-        return $this->hasMany(Music::class, 'playlist_id');
+        return $this->belongsToMany(Music::class, 'music_playlist', 'playlist_id', 'music_id')
+            ->withPivot('order')
+            ->withTimestamps();
     }
     
     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('is_active', true)->orderBy('order')->get();
+        return $this->musics()->where('music.is_active', true)->orderBy('music_playlist.order')->get();
     }
-    
+
     public function getTotalDurationAttribute()
     {
-        return $this->musics()->where('is_active', true)->sum('duration');
+        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/MusicSubcategory.php

@@ -4,6 +4,7 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 class MusicSubcategory extends Model
 {
@@ -23,9 +24,9 @@ public function category(): BelongsTo
         return $this->belongsTo(MusicCategory::class, 'category_id');
     }
     
-    public function playlists(): HasMany
+    public function playlists(): BelongsToMany
     {
-        return $this->hasMany(MusicPlaylist::class, 'subcategory_id');
+        return $this->belongsToMany(MusicPlaylist::class, 'music_subcategory_playlist', 'subcategory_id', 'playlist_id');
     }
     
     public function image(): BelongsTo
@@ -35,7 +36,7 @@ public function image(): BelongsTo
     
     public function getActivePlaylistsAttribute()
     {
-        return $this->playlists()->where('is_active', true)->orderBy('order')->get();
+        return $this->playlists()->where('music_playlists.is_active', true)->orderBy('music_playlists.order')->get();
     }
     
     // Get total music count across all playlists in this subcategory

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

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+
+class SubCategory extends Model
+{
+    protected $table = 'sub_categories';
+
+    protected $fillable = ['category_id', 'name', 'description'];
+
+    public function category(): BelongsTo
+    {
+        return $this->belongsTo(Category::class);
+    }
+
+    public function media(): BelongsToMany
+    {
+        return $this->belongsToMany(Media::class, 'media_sub_category');
+    }
+}

app/Models/SurveyAnswer.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class SurveyAnswer extends Model
+{
+    protected $fillable = ['user_id', 'survey_question_id', 'survey_option_id'];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function question(): BelongsTo
+    {
+        return $this->belongsTo(SurveyQuestion::class, 'survey_question_id');
+    }
+
+    public function option(): BelongsTo
+    {
+        return $this->belongsTo(SurveyOption::class, 'survey_option_id');
+    }
+}

app/Models/SurveyOption.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class SurveyOption extends Model
+{
+    protected $fillable = ['survey_question_id', 'label', 'value', 'order'];
+
+    protected $casts = [
+        'order' => 'integer',
+    ];
+
+    public function question(): BelongsTo
+    {
+        return $this->belongsTo(SurveyQuestion::class, 'survey_question_id');
+    }
+
+    public function answers(): HasMany
+    {
+        return $this->hasMany(SurveyAnswer::class);
+    }
+
+    // Tags used to suggest media when a user picks this option.
+    public function tags(): BelongsToMany
+    {
+        return $this->belongsToMany(Tag::class, 'survey_option_tag');
+    }
+}

app/Models/SurveyQuestion.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class SurveyQuestion extends Model
+{
+    protected $fillable = ['question', 'description', 'type', 'order', 'is_active'];
+
+    protected $casts = [
+        'is_active' => 'boolean',
+        'order' => 'integer',
+    ];
+
+    public function options(): HasMany
+    {
+        return $this->hasMany(SurveyOption::class)->orderBy('order');
+    }
+
+    public function answers(): HasMany
+    {
+        return $this->hasMany(SurveyAnswer::class);
+    }
+
+    // The current user's selected option ids for this question.
+    public function userAnswers(): HasMany
+    {
+        return $this->hasMany(SurveyAnswer::class)->where('user_id', auth()->id());
+    }
+}

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/HasLikes.php

@@ -0,0 +1,59 @@
+<?php
+// app/Traits/HasLikes.php
+namespace App\Traits;
+
+use App\Models\Like;
+use Illuminate\Database\Eloquent\Relations\MorphMany;
+
+trait HasLikes
+{
+    public function likes(): MorphMany
+    {
+        return $this->morphMany(Like::class, 'likeable');
+    }
+    
+    public function getIsLikedAttribute()
+    {
+        if (!auth()->check()) return false;
+        
+        return $this->likes()
+            ->where('user_id', auth()->id())
+            ->exists();
+    }
+    
+    public function getLikesCountAttribute()
+    {
+        return $this->likes()->count();
+    }
+    
+    public function toggleLike()
+    {
+        if ($this->getIsLikedAttribute()) {
+            return $this->removeLike();
+        } else {
+            return $this->addLike();
+        }
+    }
+    
+    public function addLike()
+    {
+        if ($this->getIsLikedAttribute()) return false;
+        
+        return Like::create([
+            'user_id' => auth()->id(),
+            'likeable_id' => $this->id,
+            'likeable_type' => get_class($this),
+        ]);
+    }
+    
+    public function removeLike()
+    {
+        if (!$this->getIsLikedAttribute()) return false;
+        
+        return Like::where([
+            'user_id' => auth()->id(),
+            'likeable_id' => $this->id,
+            'likeable_type' => get_class($this),
+        ])->delete();
+    }
+}

app/Traits/HasSaves.php

@@ -3,7 +3,6 @@
 namespace App\Traits;
 
 use App\Models\SavedItem;
-use Illuminate\Database\Eloquent\Relations\MorphMany;
 
 trait HasSaves
 {
@@ -11,49 +10,58 @@ public function saves()
     {
         return $this->morphMany(SavedItem::class, 'saveable');
     }
-    
+
     public function getIsSavedAttribute()
     {
-        if (!auth()->check()) return false;
-        
-        return $this->saves()
-            ->where('user_id', auth()->id())
-            ->exists();
+        return $this->isSavedByAuthUser();
     }
-    
+
     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;
-        
-        return SavedItem::create([
+        if (!auth()->check()) {
+            return false;
+        }
+
+        // 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),
         ]);
     }
-    
+
     public function removeSave()
     {
-        if (!$this->getIsSavedAttribute()) return false;
-        
+        if (!auth()->check()) {
+            return false;
+        }
+
         return SavedItem::where([
             'user_id' => auth()->id(),
             'saveable_id' => $this->id,
             'saveable_type' => get_class($this),
         ])->delete();
     }
-}
+}

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_05_22_175608_change_duration_to_integer_in_music_table.php

@@ -3,6 +3,7 @@
 use Illuminate\Database\Migrations\Migration;
 use Illuminate\Database\Schema\Blueprint;
 use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Facades\DB;
 
 return new class extends Migration
 {
@@ -11,9 +12,22 @@
      */
     public function up(): void
     {
-        Schema::table('music', function (Blueprint $table) {
-            $table->integer('duration')->nullable()->change();
-        });
+        // Get the database driver
+        $driver = DB::connection()->getDriverName();
+        
+        if ($driver === 'pgsql') {
+            // PostgreSQL: Use raw statement with USING clause
+            DB::statement('ALTER TABLE music ALTER COLUMN duration TYPE integer USING (duration::integer)');
+            
+            Schema::table('music', function (Blueprint $table) {
+                $table->integer('duration')->nullable()->change();
+            });
+        } elseif ($driver === 'mysql') {
+            // MySQL: Can directly change column type
+            Schema::table('music', function (Blueprint $table) {
+                $table->integer('duration')->nullable()->change();
+            });
+        }
     }
 
     /**
@@ -21,8 +35,21 @@ public function up(): void
      */
     public function down(): void
     {
-        Schema::table('music', function (Blueprint $table) {
-            $table->string('duration')->nullable()->change();
-        });
+        // Get the database driver
+        $driver = DB::connection()->getDriverName();
+        
+        if ($driver === 'pgsql') {
+            // PostgreSQL: Convert back to text
+            DB::statement('ALTER TABLE music ALTER COLUMN duration TYPE text USING (duration::text)');
+            
+            Schema::table('music', function (Blueprint $table) {
+                $table->string('duration')->nullable()->change();
+            });
+        } elseif ($driver === 'mysql') {
+            // MySQL: Change back to string
+            Schema::table('music', function (Blueprint $table) {
+                $table->string('duration')->nullable()->change();
+            });
+        }
     }
-};
+};

database/migrations/2026_05_24_192058_create_likes_table.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
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('likes', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained()->onDelete('cascade');
+            $table->morphs('likeable'); 
+            $table->timestamps();
+            $table->unique(['user_id', 'likeable_id', 'likeable_type']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('likes');
+    }
+};

database/migrations/2026_05_30_100000_create_sub_categories_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('sub_categories', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('category_id')->constrained('categories')->cascadeOnDelete();
+            $table->string('name');
+            $table->timestamps();
+
+            $table->unique(['category_id', 'name']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('sub_categories');
+    }
+};

database/migrations/2026_05_30_100100_add_subcategory_id_to_media_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::table('media', function (Blueprint $table) {
+            $table->unsignedBigInteger('subcategory_id')->nullable()->after('category_id');
+
+            $table->foreign('subcategory_id')->references('id')->on('sub_categories')->nullOnDelete();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('media', function (Blueprint $table) {
+            $table->dropForeign(['subcategory_id']);
+            $table->dropColumn('subcategory_id');
+        });
+    }
+};

database/migrations/2026_05_31_100000_create_media_category_pivot_tables.php

@@ -0,0 +1,79 @@
+<?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::create('category_media', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('media_id')->constrained('media')->cascadeOnDelete();
+            $table->foreignId('category_id')->constrained('categories')->cascadeOnDelete();
+            $table->timestamps();
+
+            $table->unique(['media_id', 'category_id']);
+        });
+
+        Schema::create('media_sub_category', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('media_id')->constrained('media')->cascadeOnDelete();
+            $table->foreignId('sub_category_id')->constrained('sub_categories')->cascadeOnDelete();
+            $table->timestamps();
+
+            $table->unique(['media_id', 'sub_category_id']);
+        });
+
+        // Backfill the new pivots from the existing single columns.
+        if (Schema::hasColumn('media', 'category_id')) {
+            DB::table('media')
+                ->whereNotNull('category_id')
+                ->orderBy('id')
+                ->select('id', 'category_id')
+                ->chunk(200, function ($rows) {
+                    $now = now();
+                    $insert = $rows->map(fn ($row) => [
+                        'media_id' => $row->id,
+                        'category_id' => $row->category_id,
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ])->all();
+
+                    DB::table('category_media')->insertOrIgnore($insert);
+                });
+        }
+
+        if (Schema::hasColumn('media', 'subcategory_id')) {
+            DB::table('media')
+                ->whereNotNull('subcategory_id')
+                ->orderBy('id')
+                ->select('id', 'subcategory_id')
+                ->chunk(200, function ($rows) {
+                    $now = now();
+                    $insert = $rows->map(fn ($row) => [
+                        'media_id' => $row->id,
+                        'sub_category_id' => $row->subcategory_id,
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ])->all();
+
+                    DB::table('media_sub_category')->insertOrIgnore($insert);
+                });
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('media_sub_category');
+        Schema::dropIfExists('category_media');
+    }
+};

database/migrations/2026_05_31_100100_drop_category_columns_from_media_table.php

@@ -0,0 +1,36 @@
+<?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('media', function (Blueprint $table) {
+            $table->dropForeign(['category_id']);
+            $table->dropColumn('category_id');
+
+            $table->dropForeign(['subcategory_id']);
+            $table->dropColumn('subcategory_id');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('media', function (Blueprint $table) {
+            $table->unsignedBigInteger('category_id')->nullable()->after('image_id');
+            $table->foreign('category_id')->references('id')->on('categories')->nullOnDelete();
+
+            $table->unsignedBigInteger('subcategory_id')->nullable()->after('category_id');
+            $table->foreign('subcategory_id')->references('id')->on('sub_categories')->nullOnDelete();
+        });
+    }
+};

database/migrations/2026_05_31_110000_create_music_playlist_category_pivot_tables.php

@@ -0,0 +1,79 @@
+<?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::create('music_category_playlist', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('playlist_id')->constrained('music_playlists')->cascadeOnDelete();
+            $table->foreignId('category_id')->constrained('music_categories')->cascadeOnDelete();
+            $table->timestamps();
+
+            $table->unique(['playlist_id', 'category_id']);
+        });
+
+        Schema::create('music_subcategory_playlist', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('playlist_id')->constrained('music_playlists')->cascadeOnDelete();
+            $table->foreignId('subcategory_id')->constrained('music_subcategories')->cascadeOnDelete();
+            $table->timestamps();
+
+            $table->unique(['playlist_id', 'subcategory_id']);
+        });
+
+        // Backfill the new pivots from the existing single columns.
+        if (Schema::hasColumn('music_playlists', 'category_id')) {
+            DB::table('music_playlists')
+                ->whereNotNull('category_id')
+                ->orderBy('id')
+                ->select('id', 'category_id')
+                ->chunk(200, function ($rows) {
+                    $now = now();
+                    $insert = $rows->map(fn ($row) => [
+                        'playlist_id' => $row->id,
+                        'category_id' => $row->category_id,
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ])->all();
+
+                    DB::table('music_category_playlist')->insertOrIgnore($insert);
+                });
+        }
+
+        if (Schema::hasColumn('music_playlists', 'subcategory_id')) {
+            DB::table('music_playlists')
+                ->whereNotNull('subcategory_id')
+                ->orderBy('id')
+                ->select('id', 'subcategory_id')
+                ->chunk(200, function ($rows) {
+                    $now = now();
+                    $insert = $rows->map(fn ($row) => [
+                        'playlist_id' => $row->id,
+                        'subcategory_id' => $row->subcategory_id,
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ])->all();
+
+                    DB::table('music_subcategory_playlist')->insertOrIgnore($insert);
+                });
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('music_subcategory_playlist');
+        Schema::dropIfExists('music_category_playlist');
+    }
+};

database/migrations/2026_05_31_110100_drop_category_columns_from_music_playlists_table.php

@@ -0,0 +1,35 @@
+<?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('music_playlists', function (Blueprint $table) {
+            $table->dropForeign(['subcategory_id']);
+            $table->dropColumn('subcategory_id');
+
+            $table->dropForeign(['category_id']);
+            $table->dropColumn('category_id');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('music_playlists', function (Blueprint $table) {
+            $table->foreignId('category_id')->nullable()->after('id')
+                ->constrained('music_categories')->nullOnDelete();
+            $table->foreignId('subcategory_id')->nullable()->after('category_id')
+                ->constrained('music_subcategories')->nullOnDelete();
+        });
+    }
+};

database/migrations/2026_05_31_120000_create_music_playlist_pivot_table.php

@@ -0,0 +1,53 @@
+<?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::create('music_playlist', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('music_id')->constrained('music')->cascadeOnDelete();
+            $table->foreignId('playlist_id')->constrained('music_playlists')->cascadeOnDelete();
+            $table->integer('order')->default(0);
+            $table->timestamps();
+
+            $table->unique(['music_id', 'playlist_id']);
+        });
+
+        // Backfill the pivot from the existing single playlist_id column.
+        if (Schema::hasColumn('music', 'playlist_id')) {
+            DB::table('music')
+                ->whereNotNull('playlist_id')
+                ->orderBy('id')
+                ->select('id', 'playlist_id', 'order')
+                ->chunk(200, function ($rows) {
+                    $now = now();
+                    $insert = $rows->map(fn ($row) => [
+                        'music_id' => $row->id,
+                        'playlist_id' => $row->playlist_id,
+                        'order' => $row->order ?? 0,
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ])->all();
+
+                    DB::table('music_playlist')->insertOrIgnore($insert);
+                });
+        }
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('music_playlist');
+    }
+};

database/migrations/2026_05_31_120100_drop_playlist_columns_from_music_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
+    {
+        Schema::table('music', function (Blueprint $table) {
+            $table->dropForeign(['playlist_id']);
+            $table->dropColumn('playlist_id');
+            $table->dropColumn('order');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('music', function (Blueprint $table) {
+            $table->foreignId('playlist_id')->nullable()->after('type')
+                ->constrained('music_playlists')->nullOnDelete();
+            $table->integer('order')->default(0)->after('duration');
+        });
+    }
+};

database/migrations/2026_06_01_100000_create_survey_questions_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('survey_questions', function (Blueprint $table) {
+            $table->id();
+            $table->string('question');
+            $table->text('description')->nullable();
+            // single = user picks exactly one option, multiple = user can pick many
+            $table->enum('type', ['single', 'multiple'])->default('single');
+            $table->integer('order')->default(0);
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('survey_questions');
+    }
+};

database/migrations/2026_06_01_100100_create_survey_options_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('survey_options', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('survey_question_id')->constrained('survey_questions')->cascadeOnDelete();
+            $table->string('label');
+            $table->string('value')->nullable(); // optional machine value
+            $table->integer('order')->default(0);
+            $table->timestamps();
+
+            $table->index(['survey_question_id', 'order']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('survey_options');
+    }
+};

database/migrations/2026_06_01_100200_create_survey_answers_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('survey_answers', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();
+            $table->foreignId('survey_question_id')->constrained('survey_questions')->cascadeOnDelete();
+            $table->foreignId('survey_option_id')->constrained('survey_options')->cascadeOnDelete();
+            $table->timestamps();
+
+            // A user can select a given option only once.
+            $table->unique(['user_id', 'survey_option_id']);
+            $table->index(['user_id', 'survey_question_id']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('survey_answers');
+    }
+};

database/migrations/2026_06_01_110000_create_survey_option_tag_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('survey_option_tag', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('survey_option_id')->constrained('survey_options')->cascadeOnDelete();
+            $table->foreignId('tag_id')->constrained('tags')->cascadeOnDelete();
+            $table->timestamps();
+
+            $table->unique(['survey_option_id', 'tag_id']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('survey_option_tag');
+    }
+};

database/migrations/2026_06_01_120000_create_media_plays_table.php

@@ -0,0 +1,35 @@
+<?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('media_plays', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();
+            $table->foreignId('media_id')->constrained('media')->cascadeOnDelete();
+            $table->unsignedInteger('play_count')->default(0);
+            $table->timestamp('last_played_at')->nullable();
+            $table->timestamps();
+
+            // One row per user + media; updated on each play.
+            $table->unique(['user_id', 'media_id']);
+            $table->index('last_played_at');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('media_plays');
+    }
+};

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();
+        });
+    }
+};