Documentation

Technical reference for CircuitQuEEst — architecture, content model, build instructions, and the full topic list.

Overview

CircuitQuEEst is a single-activity Android application built entirely with Kotlin and Jetpack Compose. It teaches Electrical Engineering fundamentals through 42 sequential topics, each consisting of a scrollable lesson and a 7-question quiz.

• Language: 100% Kotlin
• UI: Jetpack Compose + Material 3
• Architecture: MVVM (ViewModel + Repository pattern)
• Storage: Room database (offline-first, SQLite)
• Navigation: Jetpack Navigation Compose
• Build system: Gradle Kotlin DSL + version catalog
• Min SDK: 26 (Android 8.0 Oreo)  /  Target SDK: 35

Architecture

Layer overview

Navigation

A single NavGraph.kt defines all routes using Jetpack Navigation Compose. The repository is injected at the NavGraph level and passed into ViewModel factories.

Content model

All 42 topics are defined as Kotlin singleton objects in data/content/. Each file exposes a single Topic object:

data class Topic(
    val id: String,        // e.g. "ohms_law"
    val title: String,
    val subtitle: String,
    val icon: String,      // emoji
    val order: Int,        // global sort order (1–42)
    val lesson: Lesson,
    val quiz: Quiz
)

data class Lesson(val title: String, val sections: List<LessonSection>)
data class LessonSection(val heading: String, val content: String,
                         val formula: String? = null, val keyPoint: String? = null)

data class Quiz(val title: String, val questions: List<Question>)
sealed class Question {
    data class MultipleChoice(val options: List<String>, val correctIndex: Int, ...) : Question()
    data class NumericInput(val correctAnswer: Double, val tolerance: Double, ...) : Question()
}

Categories are a pure UI concern defined in TopicCategories.kt. No Topic data class field was needed — the mapping is a separate object that the ViewModel joins at runtime.

Progress system

XP is awarded as follows:

• +50 XP — completing a lesson (first time)
• +10 XP per point above your best score — for each quiz attempt (retakes at or below your best earn nothing)
• +100 XP bonus — the first time you pass a topic's quiz

A quiz passes at 60%. Only a passing attempt sets TopicProgress.quizCompleted = true, which unlocks the next topic. Unlock order follows the categories on the quest map, top to bottom; each topic's order equals its position in that sequence. Any topic you've already started stays unlocked. The rules live in QuizScoring; the lock logic is in HomeViewModel.

Build Instructions

Requirements

• JDK 17 (Adoptium Temurin recommended)
• Android SDK — platform 35, build-tools 35.0.0
• Gradle Wrapper 8.11.1 (included in repo)
• Android Gradle Plugin 8.7.3
• Kotlin 2.0.21

Build steps

# Clone the repository
git clone https://github.com/HighviewOne/CircuitQueest.git
cd CircuitQueest

# Build debug APK
./gradlew assembleDebug

# Output location
# app/build/outputs/apk/debug/app-debug.apk (~10 MB)

If your environment variables aren't set:

JAVA_HOME=/path/to/jdk-17 \
ANDROID_HOME=/path/to/android-sdk \
./gradlew assembleDebug

Install directly to a connected device:

./gradlew installDebug

All 42 Topics

Topics are organized into 9 categories on the HomeScreen. Topics unlock in the numeric sequence below, which follows the categories top to bottom.