Ruby on Rails 8 + React E-Learning: Clean Architecture Implementation, Repository Pattern, Use Cases & Typed Frontend Services (PR #1 Breakdown)

class UseCaseResult
  attr_reader :data, :error, :errors, :status

  def initialize(success:, data: nil, error: nil, errors: nil, status: :ok)
    @success = success
    @data = data
    @error = error
    @errors = errors
    @status = status
  end

  def success?
    @success
  end

  def failure?
    !@success
  end

  def self.success(data = nil, status: :ok)
    new(success: true, data: data, status: status)
  end

  def self.failure(error, status: :bad_request, errors: nil)
    new(success: false, error: error, errors: errors, status: status)
  end
end

class BaseRepository
  attr_reader :model_class

  def initialize(model_class)
    @model_class = model_class
  end

  def all
    model_class.all
  end

  def find(id)
    model_class.find(id)
  end

  def find_by(conditions)
    model_class.find_by(conditions)
  end

  def create!(attributes)
    model_class.create!(attributes)
  end

  def update!(id, attributes)
    record = find(id)
    record.update!(attributes)
    record
  end

  def delete!(id)
    record = find(id)
    record.destroy!
  end

  def count
    model_class.count
  end
end

class UserRepository < BaseRepository
  def initialize
    super(User)
  end

  def find_by_email(email)
    model_class.find_by(email: email)
  end

  def find_admin
    model_class.find_by(role: 'ROLE_ADMIN')
  end
end

module Auth
  class AuthenticateUser
    def initialize(user_repo: UserRepository.new)
      @user_repo = user_repo
    end

    def call(email:, password:)
      user = @user_repo.find_by_email(email&.strip&.downcase)

      return UseCaseResult.failure("Invalid email or password", status: :unauthorized) unless user
      return UseCaseResult.failure("Account is inactive", status: :forbidden) unless user.active
      return UseCaseResult.failure("Invalid email or password", status: :unauthorized) unless user.authenticate(password)

      token = JsonWebToken.encode(user_id: user.id)

      UseCaseResult.success({
        accessToken: token,
        refreshToken: token,
        tokenType: "Bearer",
        userId: user.id,
        name: user.name,
        email: user.email,
        roles: [user.role],
        active: user.active,
        impersonatedBy: user.impersonated_by_id,
        token: token
      })
    end
  end
end

module Exams
  class StartExamAttempt
    def initialize(
      exam_repo: ExaminationRepository.new,
      attempt_repo: ExamAttemptRepository.new
    )
      @exam_repo = exam_repo
      @attempt_repo = attempt_repo
    end

    def call(exam_id:, student:)
      return UseCaseResult.failure("Student record not found", status: :forbidden) unless student

      exam = @exam_repo.find(exam_id)
      attempt = @attempt_repo.find_or_initialize_for(exam, student)

      # Handle fresh attempt or permitted retries
      if attempt.new_record? || (exam.allow_retry && attempt.status == 'completed')
        attempt.status = 'in_progress'
        attempt.started_at = Time.current
        attempt.remaining_seconds = exam.duration_minutes * 60
        attempt.violations_count = 0
        attempt.save!
      end

      # Shuffling logic isolated from Controller
      questions = exam.questions.order(:id).to_a
      questions = questions.shuffle if exam.shuffle_questions

      existing_answers = ExamAnswer.where(exam_attempt: attempt).index_by(&:question_id)

      questions_payload = questions.map do |q|
        options = q.options || []
        options = options.shuffle if exam.shuffle_options
        {
          id: q.id,
          examinationId: q.examination_id,
          questionText: q.question_text,
          questionType: q.question_type,
          options: options,
          points: q.points,
          difficulty: q.difficulty,
          studentAnswer: existing_answers[q.id]&.student_answer,
          imagePath: q.image_path,
          audioPath: q.audio_path
        }
      end

      # Calculate exact remaining timer based on wall-clock started_at
      elapsed = (Time.current - attempt.started_at).to_i
      remaining = [exam.duration_minutes * 60 - elapsed, 0].max

      response_data = {
        attemptId: attempt.id,
        examId: exam.id,
        examTitle: exam.title,
        durationMinutes: exam.duration_minutes,
        remainingSeconds: remaining,
        startedAt: attempt.started_at.iso8601,
        totalQuestions: questions.size,
        questions: questions_payload
      }

      UseCaseResult.success(response_data)
    rescue ActiveRecord::RecordNotFound => e
      UseCaseResult.failure(e.message, status: :not_found)
    end
  end
end

module Exams
  class SubmitExamAttempt
    def initialize(attempt_repo: ExamAttemptRepository.new)
      @attempt_repo = attempt_repo
    end

    def call(attempt_id:)
      attempt = @attempt_repo.find(attempt_id)
      exam = attempt.examination

      return UseCaseResult.failure("Exam attempt already finished") if attempt.status == 'completed'

      answers = attempt.exam_answers.includes(:question)
      total_points = exam.questions.sum(:points)
      total_earned = 0.0
      has_ungraded_essay = false

      answers.each do |ans|
        q = ans.question
        next unless q

        if q.question_type == 'multiple_choice'
          is_correct = ans.student_answer.to_s.strip.upcase == q.correct_answer.to_s.strip.upcase
          points = is_correct ? q.points : 0.0
          ans.update!(is_correct: is_correct, points_awarded: points, graded_at: Time.current)
          total_earned += points
        elsif q.question_type == 'essay'
          if ans.points_awarded.present?
            total_earned += ans.points_awarded
          else
            has_ungraded_essay = true
          end
        end
      end

      score_pct = total_points > 0 ? (total_earned / total_points * 100.0).round(2) : 0.0
      passed = score_pct >= exam.passing_score
      final_status = has_ungraded_essay ? 'needs_grading' : 'completed'

      attempt.update!(
        score: score_pct,
        passed: passed,
        status: final_status,
        finished_at: Time.current
      )

      UseCaseResult.success({
        score: score_pct,
        passed: passed,
        status: final_status,
        totalQuestions: exam.questions.count,
        answeredCount: answers.count
      })
    end
  end
end

def handle_result(result, message: "Success")
  if result.success?
    json_response(data: result.data, message: message, status: result.status)
  else
    render_error(result.error, status: result.status, errors: result.errors)
  end
end

module Api
  module V1
    class ExamRunnerController < BaseController
      def start
        require_student!
        return if performed?

        result = start_exam_attempt_use_case.call(
          exam_id: params[:id],
          student: current_user.student
        )
        handle_result(result)
      end

      def answer
        require_student!
        return if performed?

        result = save_exam_answer_use_case.call(
          attempt_id: params[:attempt_id],
          question_id: params[:questionId],
          answer: params[:answer]
        )
        handle_result(result, message: "Answer saved")
      end

      def submit
        require_student!
        return if performed?

        result = submit_exam_attempt_use_case.call(attempt_id: params[:attempt_id])
        handle_result(result, message: "Exam submitted successfully")
      end

      private

      def start_exam_attempt_use_case
        @start_exam_attempt_use_case ||= Exams::StartExamAttempt.new
      end

      def save_exam_answer_use_case
        @save_exam_answer_use_case ||= Exams::SaveExamAnswer.new
      end

      def submit_exam_attempt_use_case
        @submit_exam_attempt_use_case ||= Exams::SubmitExamAttempt.new
      end
    end
  end
end

import api from '../api/client';
import type { ApiResponse, Exam, ExamMonitorItem, ExamStartResponse, Question } from '../types';

export const examService = {
  async getAll(): Promise<Exam[]> {
    const res = await api.get<ApiResponse<Exam[]>>('/exams');
    return res.data.data;
  },

  async getById(id: number): Promise<Exam> {
    const res = await api.get<ApiResponse<Exam>>(`/exams/${id}`);
    return res.data.data;
  },

  // CBT Exam Runner
  async startExam(examId: number): Promise<ExamStartResponse> {
    const res = await api.post<ApiResponse<ExamStartResponse>>(`/exams/${examId}/start`);
    return res.data.data;
  },

  async saveAnswer(attemptId: number, questionId: number, answer: string): Promise<void> {
    await api.post(`/exams/attempts/${attemptId}/answer`, { questionId, answer });
  },

  async recordViolation(attemptId: number): Promise<{ violations: number }> {
    const res = await api.post<ApiResponse<{ violations: number }>>(`/exams/attempts/${attemptId}/violation`);
    return res.data.data;
  },

  async submitExam(attemptId: number): Promise<{
    score: number;
    passed: boolean;
    status: string;
    totalQuestions: number;
    answeredCount: number;
  }> {
    const res = await api.post<ApiResponse<{
      score: number;
      passed: boolean;
      status: string;
      totalQuestions: number;
      answeredCount: number;
    }>>(`/exams/attempts/${attemptId}/submit`);
    return res.data.data;
  },

  async getMonitorData(examId: number): Promise<ExamMonitorItem[]> {
    const res = await api.get<ApiResponse<ExamMonitorItem[]>>(`/exams/${examId}/monitor`);
    return res.data.data;
  },
};

// BEFORE: Direct Axios calls scattered in useEffect
const res = await api.post(`/exams/${examId}/start`);
setExamData(res.data.data);

// AFTER: Clean, typed service call
const examData = await examService.startExam(Number(examId));
setExamData(examData);

require 'rails_helper'

RSpec.describe Auth::AuthenticateUser do
  let(:use_case) { described_class.new }
  let!(:user) { User.create!(name: 'Teacher One', email: '[email protected]', password: 'password123', role: 'ROLE_TEACHER') }

  describe '#call' do
    it 'returns success with token payload on valid credentials' do
      result = use_case.call(email: '[email protected]', password: 'password123')

      expect(result).to be_success
      expect(result.data[:accessToken]).to be_present
      expect(result.data[:userId]).to eq(user.id)
      expect(result.data[:roles]).to include('ROLE_TEACHER')
    end

    it 'returns unauthorized failure on incorrect password' do
      result = use_case.call(email: '[email protected]', password: 'wrongpassword')

      expect(result).to be_failure
      expect(result.status).to eq(:unauthorized)
      expect(result.error).to eq("Invalid email or password")
    end
  end
end

RSpec.configure do |config|
  config.use_transactional_fixtures = true
  config.infer_spec_type_from_file_location!
  config.filter_rails_from_backtrace!

  config.before(:suite) do
    DatabaseCleaner.clean_with(:truncation)
  end
end