### Install Frontend Dependencies

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Install the frontend dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Skills Activation Example

Source: https://github.com/rey-workbench/oopedia/blob/main/AGENTS.md

Demonstrates how to activate domain-specific skills in the project, such as 'laravel-best-practices' and 'inertia-svelte-development'.

```markdown
- `laravel-best-practices` — Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.
- `inertia-svelte-development` — Develops Inertia.js v3 Svelte 5 client-side applications. Activates when creating Svelte pages, forms, or navigation; using Link, Form, useForm, useHttp, setLayoutProps, or router; working with deferred props, prefetching, optimistic updates, instant visits, or polling; or when user mentions Svelte with Inertia, Svelte pages, Svelte forms, or Svelte navigation.
- `tailwindcss-development` — Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.
```

--------------------------------

### Install PHP Dependencies

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Install the necessary PHP dependencies for the project using Composer.

```bash
composer install
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Copy the example environment file and generate an application key. Ensure to edit the .env file to configure database connection details.

```bash
cp .env.example .env
php artisan key:generate
```

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=oopedia
DB_USERNAME=root
DB_PASSWORD=
```

--------------------------------

### Run Application Servers

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Start the backend server using Artisan and the frontend development server using pnpm. This requires two separate terminal instances.

```bash
# Terminal 1: Backend
php artisan serve

# Terminal 2: Frontend
pnpm run dev
```

--------------------------------

### Run Application with Docker

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Start the application services in detached mode using Docker Compose.

```bash
docker-compose up -d
```

--------------------------------

### GET /mahasiswa/materials/{material}/questions/{sub_material?}

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves quiz questions for a specific material, utilizing adaptive state to determine the appropriate difficulty level.

```APIDOC
## GET /mahasiswa/materials/{material}/questions/{sub_material?}

### Description
Fetches quiz data for a student, resolving adaptive state to determine the target difficulty level.

### Method
GET

### Endpoint
/mahasiswa/materials/{material}/questions/{sub_material?}

### Parameters
#### Path Parameters
- **material** (int|string) - Required - The ID of the material.
- **sub_material** (string) - Optional - The ID of the sub-material.

### Response
#### Success Response (200)
- **question** (Object) - Question object with answers.
- **material** (Object) - Material information.
- **studentState** (Object) - Adaptive state of the user.
- **targetDifficulty** (string) - Target difficulty level (beginner/medium/hard).
```

--------------------------------

### Fact Gathering Service Implementation (PHP)

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Example of the FactGatheringService in PHP, responsible for collecting facts from student state, quiz answers, and configurations. It merges facts related to score, time, and learning style.

```php
// Contoh pengumpulan fakta
public function gatherFacts(
    StudentState $studentState,
    bool $isCorrect,
    bool $usedHint,
    int $score,
    int $timeSpent,
    string $difficulty,
    int $questionId,
    int $materialId,
    ?int $moduleId = null,
): array {
    $facts = [];

    // Score facts (G01-G04)
    $facts = array_merge($facts, $this->getScoreFacts($score, $isCorrect));

    // Time facts (G05-G06)
    $facts = array_merge($facts, $this->getTimeFacts($timeSpent, $difficulty));

    // Learning style facts (G07-G08)
    $facts = array_merge($facts, $this->getLearningStyleFacts($studentState));

    // ... dst
}
```

--------------------------------

### GET /mahasiswa/materials/{material}/adaptive/target-difficulty

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves the current target difficulty level for a student based on their adaptive state.

```APIDOC
## GET /mahasiswa/materials/{material}/adaptive/target-difficulty

### Description
Returns the target difficulty level for the user, resetting state if the material has changed.

### Method
GET

### Endpoint
/mahasiswa/materials/{material}/adaptive/target-difficulty

### Parameters
#### Path Parameters
- **material** (int|string) - Required - The ID of the material.

### Response
#### Success Response (200)
- **target_difficulty** (string) - The difficulty level (null, "beginner", "medium", or "hard").
```

--------------------------------

### Get Default Student State for Guest

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Returns a default StudentState object for guest users. This state includes default values for gamification, learning profile, performance metrics, and adaptive state, as guests do not have persistent gamification data.

```php
public function getStudentState(): StudentState
{
    // Return ephemeral StudentState for guest
    $state = new StudentState();
    $state->gamification_data   = StudentStateSchema::getDefaultGamification();
    $state->learning_profile    = StudentStateSchema::getDefaultLearningProfile();
    $state->performance_metrics = StudentStateSchema::getDefaultPerformanceMetrics();
    $state->adaptive_state      = StudentStateSchema::getDefaultAdaptiveState();

    return $state;
}
```

--------------------------------

### GET /admin/questions - Filter Questions

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves a list of questions, with options to filter by material, difficulty, or search by keywords.

```APIDOC
## GET /admin/questions

### Description
Retrieves a list of questions with filtering capabilities.

### Method
GET

### Endpoint
/admin/questions

### Parameters
#### Query Parameters
- **material** (string) - Optional - Filter questions by material ID.
- **difficulty** (string) - Optional - Filter questions by difficulty level. Allowed values: `beginner`, `medium`, `hard`, `final`.
- **search** (string) - Optional - Search query to find questions containing specific keywords in their text.

### Response
#### Success Response (200)
- **questions** (array) - An array of question objects matching the filter criteria.
  - Each question object contains details like `id`, `question_text`, `question_type`, `difficulty`, etc.

### Request Example
`GET /admin/questions?material=01HX...&difficulty=medium&search=inheritance`
```

--------------------------------

### User Login Authentication

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Handles user authentication via email and password. Supports guest access with a boolean flag. Frontend example shows form data structure. Response redirects based on user role.

```php
// POST /login - Autentikasi user
// app/Http/Controllers/Auth/LoginController.php

// Request untuk login user terdaftar
$request->validate([
    'email' => 'required|email',
    'password' => 'required|string',
]);

// Login sebagai Guest (tanpa akun)
$request->validate([
    'is_guest' => 'required|boolean',
]);

// Contoh penggunaan di frontend
const loginForm = {
    email: 'mahasiswa@example.com',
    password: 'password123'
};

// Response redirect berdasarkan role:
// - SuperAdmin/Dosen: redirect ke admin.dashboard
// - Mahasiswa: redirect ke mahasiswa.dashboard
// - Guest: redirect ke mahasiswa.materials.index
```

--------------------------------

### Get Target Difficulty for Adaptive Learning

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves the user's target difficulty level for a specific material. This endpoint checks the user's adaptive state and resets it if the user switches to a different material.

```php
public function getTargetDifficulty(int|string $materialId): JsonResponse
{
    $userId       = Auth::id();
    $studentState = $this->performanceService->getStudentState($userId);

    $adaptiveState = $studentState->adaptive_state ?? [];

    // Reset jika berpindah materi
    $lastMaterialId = $adaptiveState['current_material_id'] ?? null;
    if ($lastMaterialId !== null && (string) $lastMaterialId !== (string) $materialId) {
        $this->resetMaterialScopedState($studentState, $adaptiveState);
    }

    return $this->json([
        'target_difficulty' => $adaptiveState['target_difficulty'] ?? null
    ]);
}
```

```json
{
    "target_difficulty": "medium"  // null, "beginner", "medium", atau "hard"
}
```

--------------------------------

### Configure Environment

Source: https://github.com/rey-workbench/oopedia/blob/main/README.md

Prepare the environment file and generate the application key.

```bash
cp .env.example .env
php artisan key:generate
```

--------------------------------

### Migrate and Seed Database

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Run database migrations and seed the database with initial data.

```bash
php artisan migrate --seed
```

--------------------------------

### Clone Repository

Source: https://github.com/rey-workbench/oopedia/blob/main/README.md

Initial step to download the project source code from GitHub.

```bash
git clone https://github.com/rey-workbench/oopedia.git
```

--------------------------------

### Get Dashboard Index Data

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves comprehensive dashboard data, including user progress statistics across materials.

```APIDOC
## Get Dashboard Index Data

### Description
Mengambil data lengkap dashboard dengan statistik progress.

### Method
GET (Implied by service method)

### Endpoint
/dashboard/{userId} (Implied)

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user.

#### Query Parameters
- **isGuest** (boolean) - Required - Indicates if the user is a guest.

### Response
#### Success Response (200)
- **totalMaterials** (integer) - Total number of materials available.
- **totalQuestions** (integer) - Total number of questions across all materials.
- **totalCorrectQuestions** (integer) - Total number of correctly answered questions by the user.
- **allMaterials** (array) - An array of material objects, each containing:
  - **id** (integer) - Material ID.
  - **title** (string) - Material title.
  - **progress_percentage** (integer) - User's progress percentage for the material.
  - **total_questions** (integer) - Total questions in the material.
  - **completed_questions** (integer) - Number of questions completed by the user.
- **certifications** (array) - List of user's certifications.
- **recentActivities** (array) - List of recent user activities.
```

--------------------------------

### Controller Entry Point: checkAnswer Method

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

Metode ini menangani pemeriksaan jawaban siswa. Pengguna terautentikasi menggunakan Adaptive Flow Service, sementara pengguna tamu menggunakan question answer service sederhana. Pastikan MaterialService dan QuestionService diinisialisasi.

```php
public function checkAnswer(int|string $materialId, int|string $questionId, Request $request): JsonResponse
{
    $material = $this->materialService->getMaterialById((int) $materialId);
    $question = $this->questionService->getQuestionById((int) $questionId);

    $userId = $this->getUserId();
    $isGuest = $this->isGuestUser();

    if (!$isGuest) {
        // Use Adaptive Flow Service for authenticated users
        $result = $this->adaptiveQuizFlowService->processAdaptiveAttempt(
            $material,
            $question,
            $userId,
            $request->all()
        );
        return response()->json($result);
    }

    // Guest users use simple question answer service
    $result = $this->questionAnswerService->checkAnswer(...);
    return response()->json($result);
}
```

--------------------------------

### Forward Chaining Logic Overview

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

This diagram illustrates the steps involved in the forward chaining process within the AdaptiveEngineService::evaluate() method. It covers initialization, the rule evaluation loop, and fallback scenarios.

```text
┌─────────────────────────────────────────────────────────────────┐
│                    AdaptiveEngineService::evaluate()            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. INITIALIZATION                                               │
│     ├─ Initialize RuleRegistry                                   │
│     └─ Get all rules sorted by priority                         │
│                                                                  │
│  2. FORWARD CHAINING LOOP                                        │
│     ┌────────────────────────────────────────────────────────┐  │
│     │ For each rule in priority order:                       │  │
│     │   ├─ Check: rule->evaluate(facts)                     │  │
│     │   │                                                        │  │
│     │   ├─ IF TRUE:                                             │  │
│     │   │   ├─ rule->apply(state, context)                     │  │
│     │   │   ├─ Store triggered_rule                             │  │
│     │   │   └─ BREAK (first match wins)                        │  │
│     │   │                                                        │  │
│     │   └─ IF FALSE: Continue to next rule                     │  │
│     └────────────────────────────────────────────────────────┘  │
│                                                                  │
│  3. FALLBACK (no rule matched)                                  │
│     └─ Set next_action = 'NEXT_QUESTION'                        │
│                                                                  │
│  4. RETURN                                                       │
│     └─ [triggered_rule, new_state, facts]                       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

--------------------------------

### List Learning Materials

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves a list of all available learning materials, including progress tracking for each user. Handles guest access. The response structure details the format of material data.

```php
// GET /mahasiswa/materials
// app/Http/Controllers/Mahasiswa/MaterialController.php

public function index(): Response
{
    $isGuest   = $this->isGuest();
    $materials = $this->materialViewService->getMaterialsList(Auth::id(), $isGuest);

    return $this->render('Mahasiswa/Materials/Index', [
        'materials' => $materials,
        'isGuest'   => $isGuest,
    ]);
}

// Response structure:
[
    'materials' => [
        [
            'id' => '01HX...',
            'title' => 'Pengenalan OOP',
            'content' => '...',
            'module_id' => '1',
            'is_final_project' => false,
            'subMaterials' => [...],
            'questions_count' => 15,
            'progress_percentage' => 60
        ]
    ],
    'isGuest' => false
]
```

--------------------------------

### Get Dashboard Index Data

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves comprehensive dashboard data, including progress statistics for all materials. It caches the data for 5 minutes to improve performance. This function is used for both regular users and guests.

```php
public function getDashboardIndexData(string $userId, bool $isGuest): array
{
    return Cache::remember("dashboard_index_{$userId}", 300, function () use ($userId, $isGuest) {
        $allMaterials  = $this->materialRepo->getAllWithQuestions();
        $progressStats = $this->progressRepo->getUserProgressStats($userId);

        $materials = $allMaterials->map(function ($material) use ($progressStats, $isGuest) {
            $totalQuestions     = $this->calculateMaterialQuestionCounts($material, $isGuest)['total'];
            $materialProgress   = $progressStats->firstWhere('material_id', $material->id);
            $correctAnswers     = $materialProgress?->correct_answers ?? 0;
            $progressPercentage = $totalQuestions > 0
                ? round(($correctAnswers / $totalQuestions) * 100)
                : 0;

            return (object) [
                'id'                  => $material->id,
                'title'               => $material->title,
                'progress_percentage' => $progressPercentage,
                'total_questions'     => $totalQuestions,
                'completed_questions' => $correctAnswers,
            ];
        });

        $studentState   = StudentState::where('user_id', $userId)->first();
        $certifications = $studentState?->learning_profile['certifications'] ?? [];

        return [
            'totalMaterials'         => $allMaterials->count(),
            'totalQuestions'         => $this->configuredCounts['total'],
            'totalCorrectQuestions'  => $progressStats->sum('correct_answers'),
            'allMaterials'           => $materials,
            'certifications'         => $certifications,
            'recentActivities'       => $this->getRecentActivities($userId, 5),
        ];
    });
}
```

--------------------------------

### Evaluate Rules with AdaptiveEngineService

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Executes forward chaining to find and apply the first matching rule based on provided facts and state.

```php
public function evaluate(
    array $facts,
    array $currentState,
    array $context,
): array {
    $triggeredRule = null;
    $newState = $currentState;

    // Forward chaining: cari rule pertama yang terpenuhi
    foreach ($this->ruleRegistry->getAllRules() as $rule) {
        if ($rule->evaluate($facts)) {
            $triggeredRule = $rule;
            $newState = $rule->apply($newState, $context);
            break; // First match wins (priority-based)
        }
    }

    return [
        'triggered_rule' => $triggeredRule,
        'new_state' => $newState,
        'facts' => $facts,
    ];
}
```

--------------------------------

### Material Change Detection Logic

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

Logika ini mendeteksi ketika siswa beralih ke material yang berbeda dan mereset state adaptif untuk mencegah 'bleed-over' antar material. Ini juga mengatur ulang 'wrong_streak' untuk mencegah aturan krisis terpicu.

```php
$lastMaterialId = $adaptiveState['current_material_id'] ?? null;
if ($lastMaterialId !== null && (int) $lastMaterialId !== (int) $materialId) {
    $adaptiveState['target_difficulty'] = null;
    $adaptiveState['fast_track_active'] = false;
    $adaptiveState['last_rule'] = null;

    // Reset wrong_streak to prevent crisis rules firing
    $metrics['wrong_streak'] = 0;
    $studentState->save();
}
```

--------------------------------

### Detail Learning Material

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Displays the details of a specific learning material. Includes access control logic to check if the material is locked based on user progression or guest status. Redirects to the material list if locked.

```php
// GET /mahasiswa/materials/{id}
// app/Http/Controllers/Mahasiswa/MaterialController.php

public function show(string $id): RedirectResponse|Response
{
    $isGuest = $this->isGuest();
    $userId  = Auth::id();

    // Cek apakah materi terkunci
    if ($this->isMaterialLocked($id, $userId, $isGuest)) {
        return redirect()->route('mahasiswa.materials.index')
            ->with('error', 'Materi ini masih terkunci. Selesaikan materi sebelumnya!');
    }

    $data = $this->materialViewService->getMaterialDetail($id, $userId, $isGuest);
    return $this->render('Mahasiswa/Materials/Show/Index', $data);
}

// Logic pengecekan akses:
// - Guest: Hanya 50% materi pertama yang dapat diakses
// - Authenticated: Berdasarkan unlocked_modules di learning_profile
```

--------------------------------

### Clone OOPedia Repository

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Use this command to clone the OOPedia project from its GitHub repository and navigate into the project directory.

```bash
git clone https://github.com/rey-workbench/oopedia.git
cd oopedia
```

--------------------------------

### POST /admin/materials

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Creates a new material with an optional cover image.

```APIDOC
## POST /admin/materials

### Description
Membuat materi baru dengan cover image.

### Method
POST

### Endpoint
/admin/materials

### Parameters
#### Request Body
- **title** (string) - Required - The title of the material.
- **content** (string) - Required - The content of the material.
- **module_id** (integer) - Optional - The ID of the module this material belongs to.
- **cover_image** (file) - Optional - The cover image for the material (jpeg, png, jpg, gif, max 2MB).

### Request Example
```json
{
  "title": "Inheritance dalam OOP",
  "content": "<p>Inheritance adalah konsep pewarisan...</p>",
  "module_id": 2
}
```

### Response
#### Success Response (Redirect)
Redirects to the admin materials index page with a success message.
```

--------------------------------

### Create Material

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Handles the creation of a new material, including uploading a cover image. It uses a StoreMaterialRequest for validation and a MaterialCreateDTO for data transfer. The request includes validation rules for title, content, module ID, and cover image.

```php
public function store(StoreMaterialRequest $request): RedirectResponse
{
    $dto = MaterialCreateDTO::fromRequest($request, Auth::id());

    $this->materialService->createMaterial(
        $dto->toArray(),
        $request->file('cover_image'),
    );

    return redirect()->route('admin.materials.index')
        ->with('success', 'Materi berhasil ditambahkan.');
}
```

```php
[
    'title'       => 'required|string|max:255',
    'content'     => 'required|string',
    'module_id'   => 'nullable|integer',
    'cover_image' => 'nullable|image|mimes:jpeg,png,jpg,gif|max:2048',
]
```

```php
$request = [
    'title'     => 'Inheritance dalam OOP',
    'content'   => '<p>Inheritance adalah konsep pewarisan...</p>',
    'module_id' => 2,
];
```

--------------------------------

### Define Adaptive Constants

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-system.md

Configuration for difficulty-based time allocation and performance thresholds.

```php
// Allocated time per difficulty
public const ALLOCATED_TIME = [
    'beginner' => 45,  // seconds
    'medium'   => 90,
    'hard'     => 150,
    'final'    => 300,
];

// Time fast threshold (percentage)
public const TIME_FAST_THRESHOLD = 70;  // < 70% = fast
```

--------------------------------

### Implement Standard Promotion Rule

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

A rule that promotes students based on standard scores and beginner or medium difficulty levels.

```php
// IF (G03 AND G11 AND (G15 OR G16)) THEN H05
class StandardPromotion extends BaseAdaptiveRule
{
    protected string $ruleId = 'RULE_05';
    protected string $actionCode = 'H05';
    protected int $priority = 50;

    public function evaluate(array $facts): bool
    {
        return $this->hasAllFacts($facts, [
            'G03', // Score Standard
            'G11', // Hint None
        ]) && $this->hasAnyFact($facts, ['G15', 'G16']); // Beginner or Medium
    }
}
```

--------------------------------

### Process Adaptive Attempt in AdaptiveQuizFlowService

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-system.md

Orchestrates the adaptive learning flow by updating performance, calculating scores, gathering facts, and resolving the next action.

```php
public function processAdaptiveAttempt(...): array
{
    // 1. Update student performance
    $studentState = $this->performanceService->updateStudentPerformance(...);

    // 2. Calculate score
    $score = $this->performanceService->calculateScore(...);

    // 3. Calculate rewards
    $rewardResult = $this->gamificationService->calculateCorrectAnswerReward(...);

    // 4. Save progress
    $savedProgress = $this->progressRepo->saveProgress(...);

    // 5. Gather facts
    $facts = $this->factGathering->gatherFacts(...);

    // 6. Evaluate adaptive rules
    $adaptiveResult = $this->adaptiveEngine->evaluate($facts, ...);

    // 7. Apply adaptive state changes
    $adaptiveState['last_rule'] = $adaptiveResult['triggered_rule'];

    // 8. Resolve next action
    $nextActionData = $this->nextActionResolver->resolve(...);

    return [...];
}
```

--------------------------------

### Accelerated Material Promotion Rule

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

Used when a user demonstrates mastery, completes tasks quickly, has the next material unlocked, does not use hints, and is not on a final project. This promotes to the next material.

```plaintext
IF (G04 AND G05 AND G20 AND NOT G12 AND NOT G18) THEN H16
```

```plaintext
fast_track_active = true,
next_action = 'NEXT_MATERIAL'
```

--------------------------------

### Scenario 5: Syntax Recovery

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

This scenario triggers a syntax recovery action when a student shows remedial performance with a syntax error, even if they used hints. It recommends syntax practice.

```text
Student: Textual learner (G08)
Answer: 65% score (G02 - Remedial)
Difficulty: Medium (G16)
Error Type: Syntax (G09)
Hint: Yes (G12)
Question: Regular (NOT G18)

Facts gathered: [G02, G08, G09, G12, G16]

Rule Evaluation:
├─ Crisis rules → FALSE (not G01)
├─ SyntaxRecovery (P:24) → TRUE ✓
└─ STOP

Result:
├─ next_action: "STUDY_SYNTAX"
├─ recommendation: "Latihan Sintaksis"
├─ recovery_type: "syntax"
└─ message: "Sepertinya Anda butuh penguatan sintaks..."
```

--------------------------------

### Reset Material Progress

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Resets all progress for a specific learning material, allowing the user to restart. Differentiates between guest and authenticated user progress reset logic.

```php
// POST /mahasiswa/materials/{material}/reset
// app/Http/Controllers/Mahasiswa/MaterialController.php

public function reset(ResetMaterialProgressRequest $request): RedirectResponse
{
    $materialId = (string) $request->validated('material');

    if ($this->isGuest()) {
        $this->guestProgressService->resetMaterialProgress($materialId);
    } else {
        $this->materialViewService->resetMaterialProgress(Auth::id(), $materialId);
    }

    return redirect()->route('mahasiswa.materials.questions.show', ['material' => $materialId])
        ->with('success', 'Progress direset. Anda dapat mengerjakan soal kembali.');
}
```

--------------------------------

### Project Dependencies (Node.js)

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

List of project dependencies for a Node.js environment, including Svelte, Inertia.js, Tailwind CSS, Vite, ApexCharts, and Quill.

```json
"svelte": "^5.53.6",
"@inertiajs/svelte": "^2.3.17",
"tailwindcss": "^4.2.1",
"vite": "^7.3.1",
"apexcharts": "^5.8.1",
"quill": "^2.0.3"
```

--------------------------------

### Create New Question

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Handles the creation of new questions, supporting multiple types like Radio Button, Fill-in-the-Blank, and Drag-and-Drop. It includes validation to ensure exactly one correct answer for specific question types.

```php
public function store(StoreQuestionRequest $request): RedirectResponse
{
    $dto = QuestionCreateDTO::fromRequest($request, Auth::id());

    // Validasi: Radio Button dan Fill-in-the-Blank harus punya tepat 1 jawaban benar
    $correctCount = collect($dto->answers)->where('is_correct', '1')->count();
    if (in_array($dto->question_type, ['radio_button', 'fill_in_the_blank']) && $correctCount !== 1) {
        return redirect()->back()->withInput()
            ->with('error', 'Pertanyaan harus memiliki tepat satu jawaban benar.');
    }

    $this->questionService->createQuestion($dto->toArray());

    return redirect()->route('admin.questions.index', ['material' => $dto->material_id])
        ->with('success', 'Soal berhasil ditambahkan.');
}
```

```json
{
    'material_id'     => 'required|exists:materials,id',
    'sub_material_id' => 'nullable|exists:sub_materials,id',
    'question_text'   => 'required|string',
    'question_type'   => 'required|in:radio_button,fill_in_the_blank,drag_and_drop',
    'type'            => 'required|in:teori,sintaks',
    'difficulty'      => 'required|in:beginner,medium,hard,final',
    'hint'            => 'nullable|string',
    'answers'         => 'required|array|min:2',
    'answers.*.text'       => 'required|string',
    'answers.*.is_correct' => 'required|boolean',
}
```

```php
$questionData = [
    'material_id'   => '01HX...',
    'question_text' => 'Apa itu Encapsulation?',
    'question_type' => 'radio_button',
    'type'          => 'teori',
    'difficulty'    => 'beginner',
    'hint'          => 'Berkaitan dengan penyembunyian data',
    'answers'       => [
        ['text' => 'Penyembunyian implementasi detail', 'is_correct' => true],
        ['text' => 'Pewarisan kelas', 'is_correct' => false],
        ['text' => 'Polimorfisme', 'is_correct' => false],
        ['text' => 'Abstraksi', 'is_correct' => false],
    ]
];
```

--------------------------------

### Show Quiz Questions with Adaptive State

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Retrieves quiz questions for a given material, considering the user's adaptive state to determine the appropriate difficulty level. Requires material ID and optionally a sub-material ID.

```php
public function show(int|string $materialId, ?string $sub_material = null): Response|RedirectResponse
{
    $material = $this->materialService->getMaterialById((string) $materialId);

    $isGuest          = $this->isGuest();
    $userId           = $this->getUserId();
    $targetDifficulty = null;

    // Resolve adaptive state untuk menentukan target difficulty
    $studentStateData = $this->resolveStudentStateData(
        $isGuest, $userId, $materialId, $targetDifficulty
    );

    $data = $this->questionListingService->getQuizData(
        material: $material,
        difficulty: null,
        userId: $userId,
        isGuest: $isGuest,
        guestProgress: $this->getGuestProgress(),
        subMaterialId: $sub_material,
        targetDifficulty: $targetDifficulty,
    );

    return $this->render('Mahasiswa/Materials/Questions/Show/Index', array_merge($data, [
        'isGuest'      => $isGuest,
        'studentState' => $studentStateData,
    ]));
}
```

--------------------------------

### Adaptive Constants

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

Configuration constants for quiz timing and performance thresholds.

```APIDOC
## AdaptiveConstants

### Description
Configuration for time allocation per difficulty level and performance thresholds.

### Configuration
```php
public const ALLOCATED_TIME = [
    'beginner' => 45,
    'medium' => 90,
    'hard' => 150,
    'final' => 300,
];

public const TIME_FAST_THRESHOLD = 70;
```
```

--------------------------------

### Define StudentState Model

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Stores adaptive learning state data for students.

```php
class StudentState extends Model
{
    protected $fillable = [
        'user_id',
        'learning_style',      // 'visual' atau 'textual'
        'current_level',       // Level saat ini
        'xp',                  // Total XP
        'streak_days',         // Hari streak
        'unlocked_modules',    // Array module yang sudah dibuka
        'certificates',        // Array sertifikat yang diperoleh
    ];
}
```

--------------------------------

### Adaptive Rule Directory Structure

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-system.md

Visual representation of the adaptive rule organization within the application directory.

```text
app/
├── Rules/
│   └── Adaptive/
│       ├── Contracts/
│       │   └── AdaptiveRuleInterface.php
│       ├── BaseAdaptiveRule.php
│       ├── RuleRegistry.php
│       ├── Constants/
│       │   └── AdaptiveConstants.php
│       ├── Crisis/
│       │   ├── VisualCrisisIntervention.php
│       │   ├── TextualCrisisIntervention.php
│       │   ├── VisualProjectRevision.php
│       │   ├── TextualProjectRevision.php
│       │   ├── PersistentVisualSafetyNet.php
│       │   ├── PersistentTextualSafetyNet.php
│       │   ├── FinalProjectVisualPersistentFail.php
│       │   └── FinalProjectTextualPersistentFail.php
│       ├── Recovery/
│       │   ├── SyntaxRecovery.php
│       │   ├── LogicRecovery.php
│       │   └── RemedialIndependent.php
│       ├── Achievement/
│       │   ├── GoldCertificate.php
│       │   ├── SilverCertificate.php
│       │   ├── BronzeCertificate.php
│       │   └── ModuleGraduation.php
│       └── Progression/
│           ├── StandardPromotion.php
│           ├── AcceleratedJump.php
│           ├── AcceleratedMaterialPromotion.php
│           ├── CriticalBacktracking.php
│           └── MasteryMedium.php
└── Services/
    └── Adaptive/
        ├── AdaptiveQuizFlowService.php
        ├── AdaptiveEngineService.php
        └── FactGatheringService.php
```

--------------------------------

### AdaptiveConstants Configuration in PHP

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

Defines constants for quiz configuration, including allocated time per difficulty level and the time threshold for fast completion.

```php
// Waktu alokasi per tingkat kesulitan (detik)
public const ALLOCATED_TIME = [
    'beginner' => 45,
    'medium' => 90,
    'hard' => 150,
    'final' => 300,
];

// Threshold cepat (<70% = G05)
public const TIME_FAST_THRESHOLD = 70;
```

--------------------------------

### Adaptive Constants for Facts and Actions

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Defines constants for various Fact (G) and Action (H) codes used in adaptive learning systems. Includes score, time, learning style, error type, difficulty, and special facts, as well as intervention and promotion actions. Also defines allocated time in seconds for different difficulty levels.

```php
// app/Rules/Adaptive/Constants/AdaptiveConstants.php

// ==================== FACTS (G Codes) ====================
// Score Facts
const FACT_SCORE_CRITICAL = 'G01';  // Score < 40
const FACT_SCORE_REMEDIAL = 'G02';  // Score 40-69
const FACT_SCORE_STANDARD = 'G03';  // Score 70-89
const FACT_SCORE_MASTERY  = 'G04';  // Score >= 90

// Time Facts
const FACT_TIME_FAST = 'G05';  // Answer time < 70% allocated

// Learning Style Facts
const FACT_STYLE_VISUAL  = 'G06';
const FACT_STYLE_TEXTUAL = 'G07';
const FACT_STYLE_MIXED   = 'G22';

// Error Type Facts
const FACT_ERROR_SYNTAX = 'G08';
const FACT_ERROR_LOGIC  = 'G09';

// Difficulty Facts
const FACT_DIFF_BEGINNER = 'G13';
const FACT_DIFF_MEDIUM   = 'G14';
const FACT_DIFF_HARD     = 'G15';

// Special Facts
const FACT_IS_FINAL_PROJECT    = 'G16';
const FACT_PERSISTENT_FAIL     = 'G20';  // 2+ consecutive fails
const FACT_SATISFACTORY_PROGRESS = 'G21';  // >= 61% progress

// ==================== ACTIONS (H Codes) ====================
const ACTION_VISUAL_CRISIS_INTERVENTION  = 'H01';
const ACTION_TEXTUAL_CRISIS_INTERVENTION = 'H02';
const ACTION_SYNTAX_RECOVERY             = 'H03';
const ACTION_LOGIC_RECOVERY              = 'H04';
const ACTION_STANDARD_PROMOTION          = 'H05';
const ACTION_ACCELERATED_JUMP            = 'H06';  // Fast track
const ACTION_CRITICAL_BACKTRACKING       = 'H07';
const ACTION_MODULE_GRADUATION           = 'H08';
const ACTION_GOLD_CERTIFICATE            = 'H09';
const ACTION_SILVER_CERTIFICATE          = 'H10';
const ACTION_BRONZE_CERTIFICATE          = 'H11';

// ==================== TIME ALLOCATION ====================
const ALLOCATED_TIME = [
    'beginner' => 45,   // 45 seconds
    'medium'   => 90,   // 90 seconds
    'hard'     => 150,  // 150 seconds (2.5 min)
    'final'    => 300,  // 300 seconds (5 min)
];

```

--------------------------------

### Implement Visual Crisis Intervention Rule

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

A specific adaptive rule implementation that triggers when critical performance and visual learning style are detected.

```php
// IF (G01 AND G07 AND G15 AND NOT G22) THEN H01
class VisualCrisisIntervention extends BaseAdaptiveRule
{
    protected string $ruleId = 'RULE_01';
    protected string $actionCode = 'H01';
    protected int $priority = 10;

    public function evaluate(array $facts): bool
    {
        return $this->hasAllFacts($facts, [
            'G01', // Score Critical
            'G07', // Style Visual
            'G15', // Diff Beginner
        ]) && $this->notHasFact($facts, 'G22'); // Not Persistent Fail
    }

    public function apply(array $state, array $context): array
    {
        return [
            'recommendation' => 'Ulas Materi',
            'next_action' => 'STUDY_VISUAL',
            'message' => 'Performa Anda menurun. Mari ulas kembali materi...',
        ];
    }
}
```

--------------------------------

### User Authentication API

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Handles user login and authentication, including guest access.

```APIDOC
## POST /login

### Description
Endpoint for user authentication with support for guest mode for limited access without registration.

### Method
POST

### Endpoint
/login

### Parameters
#### Request Body
- **email** (string) - Required - User's email address for registered users.
- **password** (string) - Required - User's password for registered users.
- **is_guest** (boolean) - Required - Set to true to log in as a guest.

### Request Example
```json
{
  "email": "mahasiswa@example.com",
  "password": "password123"
}
```

### Response
#### Success Response (200)
Redirects to a dashboard based on user role:
- SuperAdmin/Dosen: admin.dashboard
- Mahasiswa: mahasiswa.dashboard
- Guest: mahasiswa.materials.index

#### Response Example
(Redirects, no JSON body)
```

--------------------------------

### Visual Crisis Intervention Rule

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-adaptive.md

Triggers for visual learners at the beginner level showing critical performance.

```text
IF (G01 AND G07 AND G15 AND NOT G22 AND NOT G18) THEN H01
```

--------------------------------

### PUT /admin/materials/{material}

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Updates an existing material.

```APIDOC
## PUT /admin/materials/{material}

### Description
Memperbarui materi yang sudah ada.

### Method
PUT

### Endpoint
/admin/materials/{materialId}

### Parameters
#### Path Parameters
- **materialId** (string) - Required - The ID of the material to update.

#### Request Body
- **title** (string) - Optional - The new title of the material.
- **content** (string) - Optional - The new content of the material.
- **module_id** (integer) - Optional - The new module ID for the material.
- **cover_image** (file) - Optional - The new cover image for the material.

### Response
#### Success Response (Redirect)
Redirects to the admin materials index page with a success message.
```

--------------------------------

### PHP Dependencies for OOPedia

Source: https://github.com/rey-workbench/oopedia/blob/main/main.md

Lists the essential PHP dependencies required for the OOPedia project, including Laravel framework, Inertia.js, Sanctum, Predis, and Octane.

```json
"php": "^8.2",
"laravel/framework": "^12.0",
"inertiajs/inertia-laravel": "^2.0",
"laravel/sanctum": "^4.0",
"predis/predis": "^3.4",
"laravel/octane": "^2.14"
```

--------------------------------

### Base Adaptive Rule Class Helpers in PHP

Source: https://github.com/rey-workbench/oopedia/blob/main/docs/rule-based-system.md

Provides helper methods for checking facts within the adaptive rule system. Use these to efficiently verify the presence of single, all, or any facts from a given set.

```php
// Check single fact exists
$this->hasFact($facts, 'G01');

// Check ALL facts exist (AND logic)
$this->hasAllFacts($facts, ['G01', 'G07']);

// Check ANY fact exists (OR logic)
$this->hasAnyFact($facts, ['G01', 'G02']);

// Check fact does NOT exist
$this->notHasFact($facts, 'G22');
```

--------------------------------

### Gather Facts for Adaptive Engine

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Collects facts about student performance, including score, time, learning style, errors, and difficulty. Uses student state and question details.

```php
public function gatherFacts(
    StudentState $studentState,
    bool $isCorrect,
    bool $usedHint,
    int $score,
    int $timeSpent,
    QuestionDifficulty $difficulty,
    string $questionId,
    string $materialId,
    ?string $moduleId = null,
): array {
    $facts = [
        ...$this->getScoreFacts($score, $isCorrect),      // G01-G04
        ...$this->getTimeFacts($timeSpent, $difficulty),   // G05
        ...$this->getLearningStyleFacts($studentState),    // G06-G07, G22
        ...$this->getErrorTypeFacts($studentState, $questionId, $isCorrect), // G08-G09
    ];

    if ($usedHint) {
        $facts[] = AdaptiveConstants::FACT_HINT_USED;  // G11
    }

    $facts[] = $this->getDifficultyFact($difficulty);  // G13-G15

    if ($this->isPersistentFail($studentState->user_id, $questionId)) {
        $facts[] = AdaptiveConstants::FACT_PERSISTENT_FAIL;  // G20
    }

    return array_values(array_unique($facts));
}
```

--------------------------------

### POST /mahasiswa/materials/{material}/questions/{question}/check

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Submits a quiz answer for evaluation by the rule-based adaptive engine.

```APIDOC
## POST /mahasiswa/materials/{material}/questions/{question}/check

### Description
Processes a student's answer attempt and returns evaluation results, including score, adaptive feedback, and gamification updates.

### Method
POST

### Endpoint
/mahasiswa/materials/{material}/questions/{question}/check

### Request Body
- **answer** (string) - Optional - UUID for radio button answers.
- **fill_in_the_blank_answer** (string) - Optional - Text answer for fill-in-the-blank questions.
- **drag_and_drop_answers** (array) - Optional - List of items for drag and drop questions.
- **used_hint** (boolean) - Required - Whether a hint was used.
- **time_spent** (integer) - Required - Time spent in seconds.

### Response
#### Success Response (200)
- **status** (string) - Success status.
- **score** (integer) - Earned score.
- **adaptiveResult** (Object) - Detailed adaptive engine feedback and state updates.
```

--------------------------------

### Adaptive Rule Registry Configuration

Source: https://context7.com/rey-workbench/oopedia/llms.txt

Defines a list of adaptive rules with associated priorities. Rules with lower priority values are evaluated first, and only one rule is triggered per evaluation.

```php
$ruleClasses = [
    // Priority 3 - Final Project Persistent Fail
    RuleFinalProjectVisualPersistentFail::class,
    RuleFinalProjectTextualPersistentFail::class,

    // Priority 5 - Persistent Safety Net
    RulePersistentVisualSafetyNet::class,
    RulePersistentTextualSafetyNet::class,

    // Priority 10 - Crisis Intervention
    RuleVisualCrisisIntervention::class,
    RuleTextualCrisisIntervention::class,

    // Priority 15 - Project Revision
    RuleVisualProjectRevision::class,
    RuleTextualProjectRevision::class,

    // Priority 21-23 - Certificates
    RuleGoldCertificate::class,    // Score >= 90, Hard difficulty
    RuleSilverCertificate::class,  // Score >= 70, Medium difficulty
    RuleBronzeCertificate::class,  // Score >= 50, Beginner difficulty

    // Priority 24-25 - Recovery
    RuleSyntaxRecovery::class,     // G08 (Error Syntax)
    RuleLogicRecovery::class,      // G09 (Error Logic)

    // Priority 27 - Critical Backtracking
    RuleCriticalBacktracking::class,

    // Priority 30 - Module Graduation
    RuleModuleGraduation::class,

    // Priority 35 - Mastery Medium
    RuleMasteryMedium::class,

    // Priority 36 - Accelerated Material Promotion
    RuleAcceleratedMaterialPromotion::class,

    // Priority 40 - Accelerated Jump (Fast Track)
    RuleAcceleratedJump::class,

    // Priority 48 - Remedial Independent
    RuleRemedialIndependent::class,

    // Priority 50 - Standard Promotion
    RuleStandardPromotion::class,
];

// Rule dengan priority lebih rendah dievaluasi lebih dulu
// Hanya 1 rule yang akan di-trigger per evaluasi
```