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

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

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class GuardianSummaryController extends Controller
+{
+    public function show(Request $request, User $student): JsonResponse
+    {
+        /** @var User $guardian */
+        $guardian = $request->user();
+
+        abort_unless($guardian->students()->whereKey($student->id)->exists(), 403);
+
+        $progress = $student->lessonProgress()
+            ->with('lesson:id,title,course_id')
+            ->latest('updated_at')
+            ->limit(10)
+            ->get()
+            ->map(fn ($row): array => [
+                'lesson_id' => $row->lesson_id,
+                'lesson_title' => $row->lesson?->title,
+                'watched_percentage' => $row->watched_percentage,
+                'completed' => $row->completed_at !== null,
+                'last_active_at' => $row->updated_at->toIso8601String(),
+            ]);
+
+        $weakestConcepts = $student->conceptMastery()
+            ->with('concept:id,name')
+            ->orderBy('mastery_score')
+            ->limit(5)
+            ->get()
+            ->map(fn ($row): array => [
+                'concept' => $row->concept?->name,
+                'mastery_score' => (float) $row->mastery_score,
+            ]);
+
+        $latestReport = $student->aiReports()
+            ->where('type', 'weakness_analysis')
+            ->latest()
+            ->first();
+
+        return response()->json([
+            'student' => [
+                'id' => $student->id,
+                'name' => $student->name,
+            ],
+            'lessons_progress' => $progress,
+            'weakest_concepts' => $weakestConcepts,
+            'latest_ai_summary' => $latestReport?->summary,
+        ]);
+    }
+}

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

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

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Models\Lesson;
+use App\Models\Quiz;
+use App\Services\ProgressTrackingService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class QuizAttemptController extends Controller
+{
+    public function __construct(private readonly ProgressTrackingService $tracking) {}
+
+    public function store(Request $request, Lesson $lesson, Quiz $quiz): JsonResponse
+    {
+        abort_unless($quiz->lesson_id === $lesson->id, 404);
+
+        $validated = $request->validate([
+            'answers' => ['required', 'array', 'min:1'],
+            'answers.*.question_id' => ['required', 'integer'],
+            'answers.*.selected_option_id' => ['nullable', 'integer'],
+            'answers.*.time_spent_seconds' => ['nullable', 'integer', 'min:0', 'max:7200'],
+        ]);
+
+        $result = $this->tracking->recordQuizAttempt(
+            student: $request->user(),
+            quiz: $quiz,
+            submittedAnswers: $validated['answers'],
+        );
+
+        return response()->json($result);
+    }
+}

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

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Jobs\AnalyzeStudentPerformance;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class StudentAnalysisController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        /** @var User $student */
+        $student = $request->user();
+
+        AnalyzeStudentPerformance::dispatch($student->id);
+
+        return response()->json(['queued' => true, 'message' => 'Analysis queued.'], 202);
+    }
+}

backend/app/Http/Controllers/Controller.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace App\Http\Controllers;
+
+abstract class Controller
+{
+    //
+}

backend/app/Http/Middleware/ApiTokenAuth.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use App\Models\User;
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response;
+
+class ApiTokenAuth
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        $token = $request->bearerToken();
+
+        if ($token === null || Str::length($token) < 32) {
+            return response()->json(['message' => 'Unauthenticated.'], 401);
+        }
+
+        /** @var User|null $user */
+        $user = User::query()->where('api_token', $token)->first();
+
+        if ($user === null) {
+            return response()->json(['message' => 'Unauthenticated.'], 401);
+        }
+
+        $request->setUserResolver(fn () => $user);
+
+        return $next($request);
+    }
+}