feat: Initial commit for Saqel Platform architecture, backend, Docker, and documentation

backend/app/Http/Controllers/Api/V1/ProgressController.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Models\Lesson;
+use App\Services\ProgressTrackingService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class ProgressController extends Controller
+{
+    public function __construct(private readonly ProgressTrackingService $tracking) {}
+
+    public function heartbeat(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'lesson_id' => ['required', 'integer', 'exists:lessons,id'],
+            'position_seconds' => ['required', 'integer', 'min:0'],
+        ]);
+
+        /** @var Lesson $lesson */
+        $lesson = Lesson::query()->findOrFail($validated['lesson_id']);
+
+        $progress = $this->tracking->heartbeat(
+            student: $request->user(),
+            lesson: $lesson,
+            positionSeconds: (int) $validated['position_seconds'],
+        );
+
+        return response()->json([
+            'lesson_id' => $lesson->id,
+            'watched_percentage' => $progress->watched_percentage,
+            'last_position_seconds' => $progress->last_position_seconds,
+            'completed' => $progress->completed_at !== null,
+        ]);
+    }
+}