Upload beautify

app/Http/Controllers/Api/Admin/FeedPerformanceReportController.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class FeedPerformanceReportController extends Controller
+{
+    public function index(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'from' => ['nullable', 'date_format:Y-m-d'],
+            'to' => ['nullable', 'date_format:Y-m-d'],
+            'limit' => ['nullable', 'integer', 'min:1', 'max:1000'],
+        ]);
+
+        $from = (string) ($validated['from'] ?? now()->subDays(29)->toDateString());
+        $to = (string) ($validated['to'] ?? now()->toDateString());
+        $limit = (int) ($validated['limit'] ?? 100);
+
+        if ($from > $to) {
+            return response()->json([
+                'message' => 'Invalid date range: from must be before or equal to to.',
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $rows = DB::table('feed_daily_metrics')
+            ->selectRaw('algo_version, source')
+            ->selectRaw('SUM(impressions) as impressions')
+            ->selectRaw('SUM(clicks) as clicks')
+            ->selectRaw('SUM(saves) as saves')
+            ->selectRaw('SUM(dwell_0_5) as dwell_0_5')
+            ->selectRaw('SUM(dwell_5_30) as dwell_5_30')
+            ->selectRaw('SUM(dwell_30_120) as dwell_30_120')
+            ->selectRaw('SUM(dwell_120_plus) as dwell_120_plus')
+            ->whereBetween('metric_date', [$from, $to])
+            ->groupBy('algo_version', 'source')
+            ->orderBy('algo_version')
+            ->orderBy('source')
+            ->get();
+
+        $byAlgoSource = $rows->map(static function ($row): array {
+            $impressions = (int) ($row->impressions ?? 0);
+            $clicks = (int) ($row->clicks ?? 0);
+            $saves = (int) ($row->saves ?? 0);
+
+            return [
+                'algo_version' => (string) $row->algo_version,
+                'source' => (string) $row->source,
+                'impressions' => $impressions,
+                'clicks' => $clicks,
+                'saves' => $saves,
+                'ctr' => round($impressions > 0 ? $clicks / $impressions : 0.0, 6),
+                'save_rate' => round($clicks > 0 ? $saves / $clicks : 0.0, 6),
+                'dwell_buckets' => [
+                    '0_5' => (int) ($row->dwell_0_5 ?? 0),
+                    '5_30' => (int) ($row->dwell_5_30 ?? 0),
+                    '30_120' => (int) ($row->dwell_30_120 ?? 0),
+                    '120_plus' => (int) ($row->dwell_120_plus ?? 0),
+                ],
+            ];
+        })->values();
+
+        $topClickedArtworks = DB::table('feed_events as e')
+            ->leftJoin('artworks as a', 'a.id', '=', 'e.artwork_id')
+            ->selectRaw('e.algo_version')
+            ->selectRaw('e.source')
+            ->selectRaw('e.artwork_id')
+            ->selectRaw('a.title as artwork_title')
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'feed_impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'feed_click' THEN 1 ELSE 0 END) AS clicks")
+            ->whereBetween('e.event_date', [$from, $to])
+            ->groupBy('e.algo_version', 'e.source', 'e.artwork_id', 'a.title')
+            ->get()
+            ->map(static function ($row): array {
+                $impressions = (int) ($row->impressions ?? 0);
+                $clicks = (int) ($row->clicks ?? 0);
+
+                return [
+                    'algo_version' => (string) $row->algo_version,
+                    'source' => (string) $row->source,
+                    'artwork_id' => (int) $row->artwork_id,
+                    'artwork_title' => (string) ($row->artwork_title ?? ''),
+                    'impressions' => $impressions,
+                    'clicks' => $clicks,
+                    'ctr' => round($impressions > 0 ? $clicks / $impressions : 0.0, 6),
+                ];
+            })
+            ->sort(static function (array $a, array $b): int {
+                $clickCompare = $b['clicks'] <=> $a['clicks'];
+                if ($clickCompare !== 0) {
+                    return $clickCompare;
+                }
+
+                return $b['ctr'] <=> $a['ctr'];
+            })
+            ->take($limit)
+            ->values();
+
+        return response()->json([
+            'meta' => [
+                'from' => $from,
+                'to' => $to,
+                'generated_at' => now()->toISOString(),
+                'limit' => $limit,
+            ],
+            'by_algo_source' => $byAlgoSource,
+            'top_clicked_artworks' => $topClickedArtworks,
+        ], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/Admin/SimilarArtworkReportController.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class SimilarArtworkReportController extends Controller
+{
+    public function index(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'from' => ['nullable', 'date_format:Y-m-d'],
+            'to' => ['nullable', 'date_format:Y-m-d'],
+            'limit' => ['nullable', 'integer', 'min:1', 'max:1000'],
+        ]);
+
+        $from = (string) ($validated['from'] ?? now()->subDays(29)->toDateString());
+        $to = (string) ($validated['to'] ?? now()->toDateString());
+        $limit = (int) ($validated['limit'] ?? 100);
+
+        if ($from > $to) {
+            return response()->json([
+                'message' => 'Invalid date range: from must be before or equal to to.',
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $byAlgoRows = DB::table('similar_artwork_events')
+            ->selectRaw('algo_version')
+            ->selectRaw("SUM(CASE WHEN event_type = 'impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN event_type = 'click' THEN 1 ELSE 0 END) AS clicks")
+            ->whereBetween('event_date', [$from, $to])
+            ->groupBy('algo_version')
+            ->orderBy('algo_version')
+            ->get();
+
+        $byAlgo = $byAlgoRows->map(static function ($row): array {
+            $impressions = (int) ($row->impressions ?? 0);
+            $clicks = (int) ($row->clicks ?? 0);
+            $ctr = $impressions > 0 ? $clicks / $impressions : 0.0;
+
+            return [
+                'algo_version' => (string) $row->algo_version,
+                'impressions' => $impressions,
+                'clicks' => $clicks,
+                'ctr' => round($ctr, 6),
+            ];
+        })->values();
+
+        $pairRows = DB::table('similar_artwork_events as e')
+            ->leftJoin('artworks as source', 'source.id', '=', 'e.source_artwork_id')
+            ->leftJoin('artworks as similar', 'similar.id', '=', 'e.similar_artwork_id')
+            ->selectRaw('e.algo_version')
+            ->selectRaw('e.source_artwork_id')
+            ->selectRaw('e.similar_artwork_id')
+            ->selectRaw('source.title as source_title')
+            ->selectRaw('similar.title as similar_title')
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'click' THEN 1 ELSE 0 END) AS clicks")
+            ->whereBetween('e.event_date', [$from, $to])
+            ->whereNotNull('e.similar_artwork_id')
+            ->groupBy('e.algo_version', 'e.source_artwork_id', 'e.similar_artwork_id', 'source.title', 'similar.title')
+            ->get();
+
+        $topSimilarities = $pairRows
+            ->map(static function ($row): array {
+                $impressions = (int) ($row->impressions ?? 0);
+                $clicks = (int) ($row->clicks ?? 0);
+                $ctr = $impressions > 0 ? $clicks / $impressions : 0.0;
+
+                return [
+                    'algo_version' => (string) $row->algo_version,
+                    'source_artwork_id' => (int) $row->source_artwork_id,
+                    'source_title' => (string) ($row->source_title ?? ''),
+                    'similar_artwork_id' => (int) $row->similar_artwork_id,
+                    'similar_title' => (string) ($row->similar_title ?? ''),
+                    'impressions' => $impressions,
+                    'clicks' => $clicks,
+                    'ctr' => round($ctr, 6),
+                ];
+            })
+            ->sort(function (array $a, array $b): int {
+                $ctrCompare = $b['ctr'] <=> $a['ctr'];
+                if ($ctrCompare !== 0) {
+                    return $ctrCompare;
+                }
+
+                $clickCompare = $b['clicks'] <=> $a['clicks'];
+                if ($clickCompare !== 0) {
+                    return $clickCompare;
+                }
+
+                return $b['impressions'] <=> $a['impressions'];
+            })
+            ->take($limit)
+            ->values();
+
+        return response()->json([
+            'meta' => [
+                'from' => $from,
+                'to' => $to,
+                'generated_at' => now()->toISOString(),
+                'limit' => $limit,
+            ],
+            'by_algo_version' => $byAlgo,
+            'top_similarities' => $topSimilarities,
+        ], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/Admin/UploadModerationController.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\Upload;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+final class UploadModerationController extends Controller
+{
+    public function pending(): JsonResponse
+    {
+        $uploads = Upload::query()
+            ->where('status', 'draft')
+            ->where('moderation_status', 'pending')
+            ->orderBy('created_at')
+            ->get([
+                'id',
+                'user_id',
+                'type',
+                'status',
+                'processing_state',
+                'title',
+                'preview_path',
+                'created_at',
+                'moderation_status',
+            ]);
+
+        return response()->json([
+            'data' => $uploads,
+        ], Response::HTTP_OK);
+    }
+
+    public function approve(string $id, Request $request): JsonResponse
+    {
+        $upload = Upload::query()->find($id);
+
+        if (! $upload) {
+            return response()->json(['message' => 'Upload not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        $upload->moderation_status = 'approved';
+        $upload->moderated_at = now();
+        $upload->moderated_by = (int) $request->user()->id;
+        $upload->moderation_note = $request->input('note');
+        $upload->save();
+
+        return response()->json([
+            'success' => true,
+            'id' => (string) $upload->id,
+            'moderation_status' => (string) $upload->moderation_status,
+        ], Response::HTTP_OK);
+    }
+
+    public function reject(string $id, Request $request): JsonResponse
+    {
+        $upload = Upload::query()->find($id);
+
+        if (! $upload) {
+            return response()->json(['message' => 'Upload not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        $upload->moderation_status = 'rejected';
+        $upload->status = 'rejected';
+        $upload->processing_state = 'rejected';
+        $upload->moderated_at = now();
+        $upload->moderated_by = (int) $request->user()->id;
+        $upload->moderation_note = (string) $request->input('note', '');
+        $upload->save();
+
+        return response()->json([
+            'success' => true,
+            'id' => (string) $upload->id,
+            'status' => (string) $upload->status,
+            'processing_state' => (string) $upload->processing_state,
+            'moderation_status' => (string) $upload->moderation_status,
+        ], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/ArtworkController.php

@@ -2,11 +2,14 @@
 namespace App\Http\Controllers\Api;
 
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Artworks\ArtworkCreateRequest;
 use App\Http\Resources\ArtworkListResource;
 use App\Http\Resources\ArtworkResource;
 use App\Services\ArtworkService;
+use App\Services\Artworks\ArtworkDraftService;
 use App\Models\Category;
 use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
 
 class ArtworkController extends Controller
 {
@@ -17,6 +20,27 @@ class ArtworkController extends Controller
         $this->service = $service;
     }
 
+    /**
+     * POST /api/artworks
+     * Creates a draft artwork placeholder for the upload pipeline.
+     */
+    public function store(ArtworkCreateRequest $request, ArtworkDraftService $drafts)
+    {
+        $user = $request->user();
+        $data = $request->validated();
+
+        $result = $drafts->createDraft(
+            (int) $user->id,
+            (string) $data['title'],
+            isset($data['description']) ? (string) $data['description'] : null
+        );
+
+        return response()->json([
+            'artwork_id' => $result->artworkId,
+            'status' => $result->status,
+        ], Response::HTTP_CREATED);
+    }
+
     /**
      * GET /api/v1/artworks/{slug}
      * Returns a single public artwork resource by slug.

app/Http/Controllers/Api/ArtworkTagController.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Artworks\ArtworkTagsStoreRequest;
+use App\Http\Requests\Artworks\ArtworkTagsUpdateRequest;
+use App\Models\Artwork;
+use App\Models\Tag;
+use App\Services\TagService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response;
+
+final class ArtworkTagController extends Controller
+{
+    public function __construct(
+        private readonly TagService $tags,
+    ) {
+    }
+
+    public function store(int $id, ArtworkTagsStoreRequest $request): JsonResponse
+    {
+        $artwork = Artwork::query()->findOrFail($id);
+        $this->authorizeOrNotFound($request->user(), $artwork);
+
+        try {
+            $payload = $request->validated();
+            $this->tags->attachUserTags($artwork, $payload['tags']);
+
+            return response()->json(['ok' => true], Response::HTTP_CREATED);
+        } catch (\Throwable $e) {
+            $ref = (string) Str::uuid();
+            logger()->error('Artwork tag attach failed', ['ref' => $ref, 'artwork_id' => $artwork->id, 'user_id' => $request->user()?->id, 'exception' => $e]);
+            return response()->json([
+                'message' => 'Unable to update tags right now.',
+                'ref' => $ref,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    public function update(int $id, ArtworkTagsUpdateRequest $request): JsonResponse
+    {
+        $artwork = Artwork::query()->findOrFail($id);
+        $this->authorizeOrNotFound($request->user(), $artwork);
+
+        try {
+            $payload = $request->validated();
+            $this->tags->syncTags($artwork, $payload['tags']);
+            return response()->json(['ok' => true]);
+        } catch (\Throwable $e) {
+            $ref = (string) Str::uuid();
+            logger()->error('Artwork tag sync failed', ['ref' => $ref, 'artwork_id' => $artwork->id, 'user_id' => $request->user()?->id, 'exception' => $e]);
+            return response()->json([
+                'message' => 'Unable to update tags right now.',
+                'ref' => $ref,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    public function destroy(int $id, Tag $tag): JsonResponse
+    {
+        $artwork = Artwork::query()->findOrFail($id);
+        $this->authorizeOrNotFound(request()->user(), $artwork);
+
+        try {
+            $this->tags->detachTags($artwork, [$tag->id]);
+            return response()->json(['ok' => true]);
+        } catch (\Throwable $e) {
+            $ref = (string) Str::uuid();
+            logger()->error('Artwork tag detach failed', ['ref' => $ref, 'artwork_id' => $artwork->id, 'tag_id' => $tag->id, 'user_id' => request()->user()?->id, 'exception' => $e]);
+            return response()->json([
+                'message' => 'Unable to update tags right now.',
+                'ref' => $ref,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    private function authorizeOrNotFound($user, Artwork $artwork): void
+    {
+        if (! $user) {
+            abort(404);
+        }
+
+        if (! $user->can('updateTags', $artwork)) {
+            abort(404);
+        }
+    }
+}

app/Http/Controllers/Api/DiscoveryEventController.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Jobs\IngestUserDiscoveryEventJob;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response;
+
+final class DiscoveryEventController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'event_id' => ['nullable', 'uuid'],
+            'event_type' => ['required', 'string', 'in:view,click,favorite,download'],
+            'artwork_id' => ['required', 'integer', 'exists:artworks,id'],
+            'occurred_at' => ['nullable', 'date'],
+            'algo_version' => ['nullable', 'string', 'max:64'],
+            'meta' => ['nullable', 'array'],
+        ]);
+
+        $eventId = (string) ($payload['event_id'] ?? (string) Str::uuid());
+        $algoVersion = (string) ($payload['algo_version'] ?? config('discovery.algo_version', 'clip-cosine-v1'));
+        $occurredAt = isset($payload['occurred_at'])
+            ? (string) $payload['occurred_at']
+            : now()->toIso8601String();
+
+        IngestUserDiscoveryEventJob::dispatch(
+            eventId: $eventId,
+            userId: (int) $request->user()->id,
+            artworkId: (int) $payload['artwork_id'],
+            eventType: (string) $payload['event_type'],
+            algoVersion: $algoVersion,
+            occurredAt: $occurredAt,
+            meta: (array) ($payload['meta'] ?? [])
+        )->onQueue((string) config('discovery.queue', 'default'));
+
+        return response()->json([
+            'queued' => true,
+            'event_id' => $eventId,
+            'algo_version' => $algoVersion,
+        ], Response::HTTP_ACCEPTED);
+    }
+}

app/Http/Controllers/Api/FeedAnalyticsController.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class FeedAnalyticsController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'event_type' => ['required', 'string', 'in:feed_impression,feed_click'],
+            'artwork_id' => ['required', 'integer', 'exists:artworks,id'],
+            'position' => ['nullable', 'integer', 'min:1', 'max:500'],
+            'algo_version' => ['required', 'string', 'max:64'],
+            'source' => ['required', 'string', 'in:personalized,cold_start,fallback'],
+            'dwell_seconds' => ['nullable', 'integer', 'min:0', 'max:86400'],
+            'occurred_at' => ['nullable', 'date'],
+        ]);
+
+        $occurredAt = isset($payload['occurred_at']) ? now()->parse((string) $payload['occurred_at']) : now();
+
+        DB::table('feed_events')->insert([
+            'event_date' => $occurredAt->toDateString(),
+            'event_type' => (string) $payload['event_type'],
+            'user_id' => (int) $request->user()->id,
+            'artwork_id' => (int) $payload['artwork_id'],
+            'position' => isset($payload['position']) ? (int) $payload['position'] : null,
+            'algo_version' => (string) $payload['algo_version'],
+            'source' => (string) $payload['source'],
+            'dwell_seconds' => isset($payload['dwell_seconds']) ? (int) $payload['dwell_seconds'] : null,
+            'occurred_at' => $occurredAt,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        return response()->json(['success' => true], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/FeedController.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\Recommendations\PersonalizedFeedService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+final class FeedController extends Controller
+{
+    public function __construct(private readonly PersonalizedFeedService $feedService)
+    {
+    }
+
+    public function index(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'limit' => ['nullable', 'integer', 'min:1', 'max:50'],
+            'cursor' => ['nullable', 'string', 'max:512'],
+            'algo_version' => ['nullable', 'string', 'max:64'],
+        ]);
+
+        $result = $this->feedService->getFeed(
+            userId: (int) $request->user()->id,
+            limit: isset($payload['limit']) ? (int) $payload['limit'] : 24,
+            cursor: isset($payload['cursor']) ? (string) $payload['cursor'] : null,
+            algoVersion: isset($payload['algo_version']) ? (string) $payload['algo_version'] : null
+        );
+
+        return response()->json($result);
+    }
+}

app/Http/Controllers/Api/SimilarArtworkAnalyticsController.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class SimilarArtworkAnalyticsController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'event_type' => ['required', 'string', 'in:impression,click'],
+            'algo_version' => ['required', 'string', 'max:64'],
+            'source_artwork_id' => ['required', 'integer', 'exists:artworks,id'],
+            'similar_artwork_id' => ['nullable', 'integer', 'exists:artworks,id'],
+            'position' => ['nullable', 'integer', 'min:1', 'max:100'],
+            'items_count' => ['nullable', 'integer', 'min:0', 'max:100'],
+        ]);
+
+        DB::table('similar_artwork_events')->insert([
+            'event_date' => now()->toDateString(),
+            'event_type' => (string) $payload['event_type'],
+            'algo_version' => (string) $payload['algo_version'],
+            'source_artwork_id' => (int) $payload['source_artwork_id'],
+            'similar_artwork_id' => isset($payload['similar_artwork_id']) ? (int) $payload['similar_artwork_id'] : null,
+            'position' => isset($payload['position']) ? (int) $payload['position'] : null,
+            'items_count' => isset($payload['items_count']) ? (int) $payload['items_count'] : null,
+            'occurred_at' => now(),
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        return response()->json(['success' => true], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/TagController.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Tags\PopularTagsRequest;
+use App\Http\Requests\Tags\TagSearchRequest;
+use App\Models\Tag;
+use Illuminate\Http\JsonResponse;
+
+final class TagController extends Controller
+{
+    public function search(TagSearchRequest $request): JsonResponse
+    {
+        $q = (string) ($request->validated()['q'] ?? '');
+        $q = trim($q);
+
+        $query = Tag::query()->where('is_active', true);
+        if ($q !== '') {
+            $query->where(function ($sub) use ($q): void {
+                $sub->where('name', 'like', $q . '%')
+                    ->orWhere('slug', 'like', $q . '%');
+            });
+        }
+
+        $tags = $query
+            ->orderByDesc('usage_count')
+            ->limit(20)
+            ->get(['id', 'name', 'slug', 'usage_count']);
+
+        return response()->json([
+            'data' => $tags,
+        ]);
+    }
+
+    public function popular(PopularTagsRequest $request): JsonResponse
+    {
+        $limit = (int) ($request->validated()['limit'] ?? 20);
+
+        $tags = Tag::query()
+            ->where('is_active', true)
+            ->orderByDesc('usage_count')
+            ->limit($limit)
+            ->get(['id', 'name', 'slug', 'usage_count']);
+
+        return response()->json([
+            'data' => $tags,
+        ]);
+    }
+}

app/Http/Controllers/Api/UploadController.php

@@ -0,0 +1,497 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Uploads\UploadFinishRequest;
+use App\Http\Requests\Uploads\UploadInitRequest;
+use App\Http\Requests\Uploads\UploadChunkRequest;
+use App\Http\Requests\Uploads\UploadCancelRequest;
+use App\Http\Requests\Uploads\UploadStatusRequest;
+use App\Jobs\GenerateDerivativesJob;
+use App\Jobs\AutoTagArtworkJob;
+use App\Jobs\GenerateArtworkEmbeddingJob;
+use App\Repositories\Uploads\UploadSessionRepository;
+use App\Services\Uploads\UploadChunkService;
+use App\Services\Uploads\UploadCancelService;
+use App\Services\Uploads\UploadAuditService;
+use App\Services\Uploads\UploadPipelineService;
+use App\Services\Uploads\UploadQuotaService;
+use App\Services\Uploads\UploadSessionStatus;
+use App\Services\Uploads\UploadStatusService;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Symfony\Component\HttpFoundation\Response;
+use Throwable;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Validator;
+use App\Services\Upload\Contracts\UploadDraftServiceInterface;
+use Carbon\Carbon;
+use App\Uploads\Jobs\VirusScanJob;
+use App\Uploads\Services\PublishService;
+use App\Uploads\Exceptions\UploadNotFoundException;
+use App\Uploads\Exceptions\UploadOwnershipException;
+use App\Uploads\Exceptions\UploadPublishValidationException;
+use App\Uploads\Services\ArchiveInspectorService;
+use App\Uploads\Services\DraftQuotaService;
+use App\Uploads\Exceptions\DraftQuotaException;
+
+final class UploadController extends Controller
+{
+    public function init(
+        UploadInitRequest $request,
+        UploadPipelineService $pipeline,
+        UploadQuotaService $quota,
+        UploadAuditService $audit
+    )
+    {
+        $user = $request->user();
+
+        try {
+            $quota->enforce($user->id);
+        } catch (Throwable $e) {
+            return response()->json([
+                'message' => $e->getMessage(),
+            ], Response::HTTP_TOO_MANY_REQUESTS);
+        }
+
+        $result = $pipeline->initSession($user->id, (string) $request->ip());
+
+        $audit->log($user->id, 'upload_init_issued', (string) $request->ip(), [
+            'session_id' => $result->sessionId,
+        ]);
+
+        return response()->json([
+            'session_id' => $result->sessionId,
+            'upload_token' => $result->token,
+            'status' => $result->status,
+        ], Response::HTTP_OK);
+    }
+
+    public function finish(
+        UploadFinishRequest $request,
+        UploadPipelineService $pipeline,
+        UploadSessionRepository $sessions,
+        UploadAuditService $audit
+    ) {
+        $user = $request->user();
+        $sessionId = (string) $request->validated('session_id');
+        $artworkId = (int) $request->validated('artwork_id');
+
+        $session = $sessions->getOrFail($sessionId);
+
+        $request->artwork();
+
+        $validated = $pipeline->validateAndHash($sessionId);
+        if (! $validated->validation->ok || ! $validated->hash) {
+            return response()->json([
+                'message' => 'Upload validation failed.',
+                'reason' => $validated->validation->reason,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $scan = $pipeline->scan($sessionId);
+        if (! $scan->ok) {
+            return response()->json([
+                'message' => 'Upload scan failed.',
+                'reason' => $scan->reason,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        try {
+            $previewPath = null;
+            $status = DB::transaction(function () use ($pipeline, $sessionId, $validated, $artworkId, &$previewPath) {
+                if ((bool) config('uploads.queue_derivatives', false)) {
+                    GenerateDerivativesJob::dispatch($sessionId, $validated->hash, $artworkId)->afterCommit();
+                    return 'queued';
+                }
+
+                $result = $pipeline->processAndPublish($sessionId, $validated->hash, $artworkId);
+                $previewPath = $result['public']['md'] ?? $result['public']['lg'] ?? null;
+
+                // Derivatives are available now; dispatch AI auto-tagging.
+                AutoTagArtworkJob::dispatch($artworkId, $validated->hash)->afterCommit();
+                GenerateArtworkEmbeddingJob::dispatch($artworkId, $validated->hash)->afterCommit();
+                return UploadSessionStatus::PROCESSED;
+            });
+
+            $audit->log($user->id, 'upload_finished', $session->ip, [
+                'session_id' => $sessionId,
+                'hash' => $validated->hash,
+                'artwork_id' => $artworkId,
+                'status' => $status,
+            ]);
+
+            return response()->json([
+                'artwork_id' => $artworkId,
+                'status' => $status,
+                'preview_path' => $previewPath,
+            ], Response::HTTP_OK);
+        } catch (Throwable $e) {
+            Log::error('Upload finish failed', [
+                'session_id' => $sessionId,
+                'artwork_id' => $artworkId,
+                'error' => $e->getMessage(),
+            ]);
+
+            return response()->json([
+                'message' => 'Upload finish failed.',
+            ], Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+    }
+
+    public function chunk(UploadChunkRequest $request, UploadChunkService $chunks)
+    {
+        $user = $request->user();
+        $chunkFile = $request->file('chunk');
+
+        // Debug: log uploaded file object details to help diagnose missing chunk
+        try {
+            if (! $chunkFile) {
+                logger()->warning('Chunk upload: no file present on request', [
+                    'session_id' => (string) $request->input('session_id'),
+                    'headers' => $request->headers->all(),
+                ]);
+            } else {
+                logger()->warning('Chunk upload file details', [
+                    'session_id' => (string) $request->input('session_id'),
+                    'client_name' => $chunkFile->getClientOriginalName() ?? null,
+                    'client_size' => $chunkFile->getSize() ?? null,
+                    'error' => $chunkFile->getError(),
+                    'realpath' => $chunkFile->getRealPath(),
+                ]);
+            }
+        } catch (\Throwable $e) {
+            logger()->warning('Chunk upload debug logging failed', ['error' => $e->getMessage()]);
+        }
+
+        try {
+            // Use getPathname() — this returns the PHP temp filename even when
+            // getRealPath() may be false (platform/stream wrappers can cause
+            // getRealPath() to return false). getPathname() is safe for reading
+            // the uploaded chunk file.
+            $chunkPath = $chunkFile ? $chunkFile->getPathname() : '';
+
+            $result = $chunks->appendChunk(
+                (string) $request->input('session_id'),
+                (string) $chunkPath,
+                (int) $request->input('offset'),
+                (int) $request->input('chunk_size'),
+                (int) $request->input('total_size'),
+                (int) $user->id,
+                (string) $request->ip()
+            );
+
+            return response()->json([
+                'session_id' => $result->sessionId,
+                'status' => $result->status,
+                'received_bytes' => $result->receivedBytes,
+                'total_bytes' => $result->totalBytes,
+                'progress' => $result->progress,
+            ], Response::HTTP_OK);
+        } catch (\Throwable $e) {
+            logger()->warning('Upload chunk failed', [
+                'session_id' => (string) $request->input('session_id'),
+                'error' => $e->getMessage(),
+            ]);
+
+            // Include the underlying error message in the response during debugging
+            // so the frontend can show a useful description. Remove or hide this
+            // in production if you prefer more generic errors.
+            return response()->json([
+                'message' => 'Upload chunk failed.',
+                'error' => $e->getMessage(),
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    public function status(string $id, UploadStatusRequest $request, UploadStatusService $statusService, UploadAuditService $audit)
+    {
+        $user = $request->user();
+        $payload = $statusService->get($id);
+
+        $audit->log($user->id, 'upload_status_checked', (string) $request->ip(), [
+            'session_id' => $id,
+            'status' => $payload['status'],
+        ]);
+
+        return response()->json([
+            'session_id' => $payload['session_id'],
+            'status' => $payload['status'],
+            'progress' => $payload['progress'],
+            'failure_reason' => $payload['failure_reason'],
+            'received_bytes' => $payload['received_bytes'] ?? 0,
+        ], Response::HTTP_OK);
+    }
+
+    public function cancel(UploadCancelRequest $request, UploadCancelService $cancel)
+    {
+        $user = $request->user();
+
+        try {
+            $result = $cancel->cancel(
+                (string) $request->input('session_id'),
+                (int) $user->id,
+                (string) $request->ip()
+            );
+
+            return response()->json([
+                'session_id' => $result['session_id'],
+                'status' => $result['status'],
+            ], Response::HTTP_OK);
+        } catch (\Throwable $e) {
+            logger()->warning('Upload cancel failed', [
+                'session_id' => (string) $request->input('session_id'),
+                'error' => $e->getMessage(),
+            ]);
+
+            return response()->json([
+                'message' => 'Upload cancel failed.',
+            ], Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+    }
+
+    /**
+     * Preload an upload draft: validate main file, create draft and store files.
+     *
+     * Returns JSON: { upload_id, status, expires_at }
+     */
+    public function preload(Request $request, UploadDraftServiceInterface $draftService, ArchiveInspectorService $archiveInspector, DraftQuotaService $draftQuotaService)
+    {
+        $user = $request->user();
+
+        $request->validate([
+            'main' => ['required', 'file'],
+            'screenshots' => ['sometimes', 'array'],
+            'screenshots.*' => ['file', 'image', 'max:5120'],
+        ]);
+
+        $main = $request->file('main');
+
+        // Detect type from mime
+        $mime = (string) $main->getClientMimeType();
+        $type = null;
+        if (str_starts_with($mime, 'image/')) {
+            $type = 'image';
+        } elseif (in_array($mime, ['application/zip', 'application/x-zip-compressed', 'application/x-tar', 'application/x-gzip', 'application/x-rar-compressed', 'application/octet-stream'])) {
+            $type = 'archive';
+        }
+
+        if ($type === null) {
+            return response()->json([
+                'message' => 'Invalid main file type.',
+                'errors' => [
+                    'main' => ['The main file must be an image or archive.'],
+                ],
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        if ($type === 'archive') {
+            $validator = Validator::make($request->all(), [
+                'screenshots' => ['required', 'array', 'min:1'],
+                'screenshots.*' => ['file', 'image', 'max:5120'],
+            ]);
+
+            if ($validator->fails()) {
+                return response()->json([
+                    'message' => 'The given data was invalid.',
+                    'errors' => $validator->errors(),
+                ], Response::HTTP_UNPROCESSABLE_ENTITY);
+            }
+
+            $inspection = $archiveInspector->inspect((string) $main->getPathname());
+            if (! $inspection->valid) {
+                return response()->json([
+                    'message' => 'Archive inspection failed.',
+                    'reason' => $inspection->reason,
+                    'stats' => $inspection->stats,
+                ], Response::HTTP_UNPROCESSABLE_ENTITY);
+            }
+        }
+
+        $incomingFiles = [$main];
+        if ($type === 'archive' && $request->hasFile('screenshots')) {
+            foreach ($request->file('screenshots') as $screenshot) {
+                $incomingFiles[] = $screenshot;
+            }
+        }
+
+        $mainHash = $draftService->calculateHash((string) $main->getPathname());
+
+        try {
+            $warnings = $draftQuotaService->assertCanCreateDraft($user, [
+                'files' => $incomingFiles,
+                'main_hash' => $mainHash,
+            ]);
+        } catch (DraftQuotaException $e) {
+            return response()->json([
+                'message' => $e->machineCode(),
+                'code' => $e->machineCode(),
+            ], $e->httpStatus());
+        }
+
+        // Create draft record (meta-only) and store main file via service
+        $draft = $draftService->createDraft(['user_id' => $user->id, 'type' => $type]);
+
+        try {
+            $mainInfo = $draftService->storeMainFile($draft['id'], $main);
+
+            // If archive, allow optional screenshots to be uploaded in the same request
+            if ($type === 'archive' && $request->hasFile('screenshots')) {
+                foreach ($request->file('screenshots') as $ss) {
+                    try {
+                        $draftService->storeScreenshot($draft['id'], $ss);
+                    } catch (Throwable $e) {
+                        // Keep controller thin: log and continue
+                        logger()->warning('Screenshot store failed during preload', ['error' => $e->getMessage(), 'draft' => $draft['id']]);
+                    }
+                }
+            }
+
+            // Set expiration (default 7 days) and return info
+            $ttlDays = (int) config('uploads.draft_ttl_days', 7);
+            $expiresAt = Carbon::now()->addDays($ttlDays);
+            $draftService->setExpiration($draft['id'], $expiresAt);
+
+            VirusScanJob::dispatch($draft['id']);
+
+            $response = [
+                'upload_id' => $draft['id'],
+                'status' => 'draft',
+                'expires_at' => $expiresAt->toISOString(),
+            ];
+
+            if (! empty($warnings)) {
+                $response['warnings'] = array_values($warnings);
+            }
+
+            return response()->json($response, Response::HTTP_OK);
+        } catch (Throwable $e) {
+            logger()->error('Upload preload failed', ['error' => $e->getMessage()]);
+            return response()->json(['message' => 'Preload failed.'], Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+    }
+
+    public function autosave(string $id, Request $request)
+    {
+        $user = $request->user();
+
+        $upload = DB::table('uploads')->where('id', $id)->first();
+        if (! $upload) {
+            return response()->json(['message' => 'Upload draft not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        if ((int) $upload->user_id !== (int) $user->id) {
+            return response()->json(['message' => 'Forbidden.'], Response::HTTP_FORBIDDEN);
+        }
+
+        if ((string) $upload->status !== 'draft') {
+            return response()->json([
+                'message' => 'Only draft uploads can be autosaved.',
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $validated = $request->validate([
+            'title' => ['nullable', 'string', 'max:255'],
+            'category_id' => ['nullable', 'exists:categories,id'],
+            'description' => ['nullable', 'string'],
+            'tags' => ['nullable', 'array'],
+            'license' => ['nullable', 'string'],
+            'nsfw' => ['nullable', 'boolean'],
+        ]);
+
+        $updates = [];
+        foreach (['title', 'category_id', 'description', 'tags', 'license', 'nsfw'] as $field) {
+            if (array_key_exists($field, $validated)) {
+                $updates[$field] = $validated[$field];
+            }
+        }
+
+        $dirty = [];
+        foreach ($updates as $field => $value) {
+            $current = $upload->{$field} ?? null;
+
+            if ($field === 'tags') {
+                $current = $current ? json_decode((string) $current, true) : null;
+            }
+
+            if ($field === 'nsfw') {
+                $current = is_null($current) ? null : (bool) $current;
+                $value = is_null($value) ? null : (bool) $value;
+            }
+
+            if ($current !== $value) {
+                $dirty[$field] = $value;
+            }
+        }
+
+        if (array_key_exists('tags', $dirty)) {
+            $dirty['tags'] = json_encode($dirty['tags']);
+        }
+
+        if (! empty($dirty)) {
+            $dirty['updated_at'] = now();
+            DB::table('uploads')->where('id', $id)->update($dirty);
+            $upload = DB::table('uploads')->where('id', $id)->first();
+        }
+
+        return response()->json([
+            'success' => true,
+            'updated_at' => (string) ($upload->updated_at ?? now()->toDateTimeString()),
+        ], Response::HTTP_OK);
+    }
+
+    public function processingStatus(string $id, Request $request)
+    {
+        $user = $request->user();
+
+        $upload = DB::table('uploads')->where('id', $id)->first();
+        if (! $upload) {
+            return response()->json(['message' => 'Upload not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        if ((int) $upload->user_id !== (int) $user->id) {
+            return response()->json(['message' => 'Forbidden.'], Response::HTTP_FORBIDDEN);
+        }
+
+        $status = (string) ($upload->status ?? 'draft');
+        $isScanned = (bool) ($upload->is_scanned ?? false);
+        $previewReady = ! empty($upload->preview_path);
+        $hasTags = (bool) ($upload->has_tags ?? false);
+        $processingState = (string) ($upload->processing_state ?? 'pending_scan');
+
+        return response()->json([
+            'id' => (string) $upload->id,
+            'status' => $status,
+            'is_scanned' => $isScanned,
+            'preview_ready' => $previewReady,
+            'has_tags' => $hasTags,
+            'processing_state' => $processingState,
+        ], Response::HTTP_OK);
+    }
+
+    public function publish(string $id, Request $request, PublishService $publishService)
+    {
+        $user = $request->user();
+
+        try {
+            $upload = $publishService->publish($id, $user);
+
+            return response()->json([
+                'success' => true,
+                'upload_id' => (string) $upload->id,
+                'status' => (string) $upload->status,
+                'published_at' => optional($upload->published_at)->toISOString(),
+                'final_path' => (string) $upload->final_path,
+            ], Response::HTTP_OK);
+        } catch (UploadOwnershipException $e) {
+            return response()->json(['message' => $e->getMessage()], Response::HTTP_FORBIDDEN);
+        } catch (UploadNotFoundException $e) {
+            return response()->json(['message' => $e->getMessage()], Response::HTTP_NOT_FOUND);
+        } catch (UploadPublishValidationException $e) {
+            return response()->json(['message' => $e->getMessage()], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+}