3 files changed, 66 insertions, 10 deletions

diff --git a/include/questions.h b/include/questions.h
index 75bc751..95ce286 100644
--- a/include/questions.h
+++ b/include/questions.h
@@ -2,19 +2,19 @@
 #include <stddef.h>
 
 typedef struct {
-  char **general;
-  char **major;
-  size_t general_count;
-  size_t major_count;
+        char** general;
+        char** major;
+        size_t general_count;
+        size_t major_count;
 } QuestionSet;
 
 /**
  * Load questions from file.
  * Returns EXIT_SUCCESS or EXIT_FAILURE.
  */
-int load_questions(const char *filename, QuestionSet *qs);
+int load_questions(const char* filename, QuestionSet* qs);
 
 /**
  * Free all allocated memory in QuestionSet.
  */
-void free_questions(QuestionSet *qs);
+void free_questions(QuestionSet* qs);
diff --git a/include/quiz.h b/include/quiz.h
new file mode 100644
index 0000000..db69367
--- /dev/null
+++ b/include/quiz.h
@@ -0,0 +1,34 @@
+//
+// Created by philw on 01/03/2026.
+//
+
+#pragma once
+
+#include "../include/questions.h"
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+
+#define PERCENT_MULTIPLIER 100.0
+#define SCORE_FORMAT "Score: %zu/%zu (%.1f%%)\n"
+
+// ------------------------
+// Quiz state
+// ------------------------
+typedef struct {
+        QuestionSet questions;
+        FILE* csv;
+        unsigned int seed;
+        size_t total_answered;
+        size_t total_correct;
+        int time_limit;
+} QuizSession;
+
+// ------------------------
+// Quiz functions
+// ------------------------
+bool initialize_quiz_session(QuizSession* session);
+bool quiz_iteration(QuizSession* session);
+void print_score(size_t correct, size_t total);
+void print_final_score(const QuizSession* session);
+void cleanup_session(QuizSession* session);
diff --git a/include/utils.h b/include/utils.h
index 74c0ca1..08895c0 100644
--- a/include/utils.h
+++ b/include/utils.h
@@ -1,8 +1,30 @@
 #pragma once
+
+#include <stdbool.h>
 #include <stddef.h>
 
+/** Print a horizontal separator line */
 void print_line(void);
-void wait_enter(const char *msg);
-char ask_yes_no(const char *msg);
-void now_str(char *buf, size_t size);
-size_t rand_index(size_t max);
+
+/** Pause until the user presses ENTER */
+void wait_for_enter(const char* prompt);
+
+/** Ask a yes/no question and return boolean */
+bool ask_yes_no(const char* prompt);
+
+/**
+ * Get the current timestamp for recording when a question was answered
+ *
+ * @param answer_time_buffer Buffer to store the formatted timestamp
+ * @param buffer_capacity Size of the buffer in bytes
+ */
+void get_answer_timestamp(char* answer_time_buffer, size_t buffer_capacity);
+
+/**
+ * Get a random question index in the quiz (thread-safe)
+ *
+ * @param seed Pointer to an unsigned int seed (per-thread)
+ * @param total_questions Number of questions in the current quiz session
+ * @return Random index in the range [0, total_questions-1]
+ */
+size_t get_random_question_index(unsigned int* seed, size_t total_questions);