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)
• +score × 10 XP — for each quiz attempt
• +100 XP bonus — for the first quiz completion on a topic

Sequential unlock: completing a topic's quiz sets TopicProgress.quizCompleted = true, which unlocks the next topic in global order sequence. This logic lives in HomeViewModel and is unaffected by category groupings.

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. Global unlock order follows the numeric sequence below.