# ######
# # # # #### #### ##### # ##### # # # #
# # # # # # # # # # # # # # ## ##
# # ###### # # # # # # # ###### # ## #
####### # # # ### # # ##### # # # # # #
# # # # # # # # # # # # # # # #
# # # # #### #### # # # # # # # #
Bridging the gap between abstract computer science logic and physical reality. 🔭 Augmented Reality algorithm visualizer — walk through sorting, searching & graph algorithms as interactive 3D structures in your physical space. Built with Kotlin, Jetpack Compose, ARCore/Sceneview, Node.js & MongoDB.
In traditional computer science curricula, algorithm execution is typically taught using static chalkboards, two-dimensional diagrams, or textual pseudocode. This abstract, non-tactile instructional methodology often creates a cognitive barrier for learners trying to construct mental models of dynamic, multi-dimensional structures. We built ARgorithm to tear down this barrier. Our vision was to render data structures as physical, interactive three-dimensional models positioned within the user's actual room. By enabling students to walk around, scale, step through, and physically probe dynamic data structures like a Quick Sort tree or a Dijkstra grid, we transform abstract computing concepts into an intuitive, physical experience.
ARgorithm is designed, engineered, and maintained by Team XRADIAN FUTURE in collaboration with the KRCT XR Innovation Centre, operating under the aegis of the Center for Student Affairs at K. Ramakrishnan College of Technology.
The initiative is directed and supported by our leadership team:
- Faculty Head & Executive Director: Dr. S. Saravanan
- Technical Coordinator: Dr. R. Jaiganesh
- XR Research Advisor: Mrs. R. Jasmine
The administrative and strategic operations of the XR Club are led by our student officers:
- President: NANDHINI
- Vice President: Godfrey
- Secretary: REXCIA
- Treasurer: MANASHA SHREE
The technical implementation of the ARgorithm ecosystem is built with passion by Team XRADIAN FUTURE:
- Godfrey — Lead AR Systems Architect & ARCore Engineer
- Nandini — AR Product Manager & Technical Producer
- Grish — Hybrid Developer & Native Graphics Engineer
- Rexcia — Lead AR Interaction & UI/UX Designer
- Sachin — 3D Graphics Developer & Technical Artist
- Manasha — AR Quality Assurance Lead & Technical Writer
The blueprint for the ARgorithm project was laid on May 30, 2025, when the Center for Student Affairs inaugurated the KRCT XR Innovation Centre at the Seminar Hall, located in the C-Block of K. Ramakrishnan College of Technology (KSCT/KRCT) near Samayapuram, Trichy. The inauguration took place under the motto "Empowering Minds with Augmented & Virtual Reality", led by our Executive Director and Faculty Head Dr. S. Saravanan. The ceremony was graced by Chief Guest Mr. ANUMUKONDA RAMESH (Global Engagement Manager (GEM), XTIC - Experimental Technology Innovation Centre, IIT Madras) along with several spatial computing pioneers. During this ceremony, the student officers were officially appointed: Nandhini as President, Godfrey as Vice President, Rexcia as Secretary, and Manasha Shree as Treasurer. A pivotal moment occurred during the hands-on session where the team first tested VR goggles and Google Glass hardware, playing a virtual space alien shooting mini-game. Experiencing this immersive 3D environment firsthand inspired the student officers to conceptualize a flagship education application that could make abstract coding concepts physical.
Following the inauguration, Vice President Godfrey initiated discussions with club members, technical leads of the XR Innovation Centre, and our faculty coordinators (Dr. S. Saravanan, Dr. R. Jaiganesh, and Mrs. R. Jasmine) to scope out a dedicated algorithm visualization suite. To support this effort, Dr. S. Saravanan allocated the XR Club Conference Room / Seminar Hall as a dedicated development space. For the first consecutive three months, the team used this space to research spatial tracking systems, hardware compatibility (XR, VR, MR), and initial data schemas. The developers committed to working day and night to design the core requirements.
During the summer, the team balanced development workloads with their semester projects and academic examinations. In this phase, the club focused on community outreach by conducting several introduction to VR webinars and seminars. The officers successfully mentored over 50 student members, teaching them about VR Google Lens capabilities, spatial computing history, and introductory virtual reality models.
By the autumn of 2025, the team implemented a structured project management workflow. We committed to holding five scrum meetings per month for progress tracking and feature scoping, utilizing a shared Trello Board to organize cards and Git Version Control for managing the repository. During this phase, Vice President Godfrey participated in several specialized webinars and workshops on spatial technology under the academic mentorship of Research Advisor Mrs. R. Jasmine (including XTIC webinars hosted on Zoom).
On November 28, 2025, Godfrey and his professor traveled overnight from Trichy to Chennai to attend the International XR Symposium for the Global South at the ICSR Building, IIT Madras, organized by ICSR and XTIC. Key event highlights:
- Prof. M. Manivannan (IIT Madras / XTIC PI) — XTIC's growing PSU collaborations & the need for accessible, inclusive XR for India and the Global South.
- Prof. Steven LaValle (University of Oulu, Finland) — Advocated for frugal XR: human-centric, perception-driven systems on everyday hardware instead of costly closed platforms.
- Dr. Obijiofor Aginam (UNESCO MGIEP, Chief Guest) — Ethics, empathy & agency in AI-driven education; technology must complement—not replace—human guidance.
- Meta — Live demo of Project Aria Gen 2 to accelerate human-centric AI research.
- Immersive stalls by Qualcomm, Meta & Haptics teams; hands-on access to advanced XR & spatial computing hardware.
- Panel discussions on XR in automotive design, education, industrial workflows & UX design — contextual innovation, ethical adoption & industry–academia collaboration.
- Speaker sessions spanning natural interaction design, AI-driven immersive creation, healthcare, calibration science, 6G-powered XR, IoT standards & multimodal learning.
The ICSR event organizers and members distributed IIT-XTIC souvenirs — a branded mug, volunteer ID badge, pen, and notes — to all symposium participants as tokens of appreciation. Godfrey compiled all event materials and shared them with the team back at KRCT.
The KRCT XR Club participated in a XTIC–IIT Madras CAVE Engagement Webinar conducted online with 800+ participants globally. The session was led by Dr. Alpana Dubey, Innovation Research Principal Director at Accenture Labs, on "Shaping Immersive Realities: The Transformative Impact of Generative AI and Agentic Systems." Key takeaways:
- The evolution of AI — from early chat systems to today's multimodal large language models.
- Generative AI reshaping software development: rapid prototyping, privacy-friendly local models & GitHub Copilot for productivity.
- Goal-driven software agents in XR workflows — intelligent, interactive immersive experiences.
- Live demos of AI-powered 3D avatars, immersive environments & large action models linking natural conversation with spatial interaction.
- A call to integrate XR and GenAI innovations to unlock intelligent and immersive digital futures.
On January 30, 2026, the team successfully released the first prototype version of our Augmented Reality visualizer. This iteration was built using the Unity Game Engine with C# scripting. While the prototype successfully rendered 3D sorting bars, the team recognized that Unity—being a game engine—was heavy, resource-intensive, and lacked native styling controls suitable for a fast, responsive educational client.
In February 2026, Godfrey pivoted the team's technical stack. We shifted from Unity/C# to native development inside Android Studio utilizing Kotlin and Jetpack Compose. This native architecture enabled a lightweight app footprint, smooth 60FPS UI rendering decoupled from background algorithm runs, and robust Room SQLite data persistence. On May 30, 2026—the one-year anniversary of the XR Innovation Centre's inauguration—Team XRADIAN FUTURE compiled and successfully deployed the final production-ready native ARgorithm application using Android Studio.
As of June 23, 2026, the system operates on a clean, multi-layered architecture featuring local Room DB caches, Kotlin Flow dispatchers, Google's Sceneview/Filament rendering viewport, and Node.js REST APIs synced with MongoDB Atlas.
- Spatial Drift & Anchor Consistency: Maintaining stable coordinate tracking of complex visual graphs and arrays on low-texture surfaces without physical markers.
- Frame-Rate Stabilization: Decoupling intensive procedural algorithm simulation calculations from the active 60FPS ARCore rendering pipeline to avoid visible stuttering.
- Dynamic Spatial UX: Designing touch gestures that feel intuitive when interacting with elements placed several meters away in 3D coordinate space.
- Local-Cloud Synchronization: Creating an offline-first mobile sync model that persists local learning progress and quiz submissions and securely syncs them to the cloud database when online.
- PBR Shading on Mobile GPUs: Optimizing Filament's Physically Based Rendering (PBR) engine to represent sorting elements with dynamic color states on older, hardware-constrained devices.
The ARgorithm ecosystem is built on a clean, multi-layered architecture:
- Mobile Client: A native Android application written in Kotlin, using Jetpack Compose for modular UI development and Dagger Hilt for dependency injection.
- AR Interface: Developed using Sceneview AR, an abstraction layer over Google's Filament renderer, allowing us to implement real-time shadows, reflections, and dynamic mesh modification.
- API Service: An Express.js backend running on Node.js, utilizing MongoDB Atlas for cloud persistence, providing JWT-secured RESTful routes for authentication, user profiling, leaderboard statistics, and quizzes.
- Local Caching: The mobile client implements an offline-first storage model via Room Database, tracking state updates and syncing with MongoDB.
User security is enforced via cryptographic standards. The client-server communications use TLS 1.3, and user sessions are governed by JSON Web Tokens with a 30-day expiration cycle. Local credentials on the Android client are stored securely in encrypted SharedPreferences backed by the Android Keystore System.
From a user experience standpoint, the application relies on an interactive dashboard, clean, glassmorphic layout styling, and contextual spatial banners that provide real-time code tracing and mathematical formulations matching the state of the physical 3D nodes.
Designing this system provided deep insights into real-time rendering constraints and spatial user interactions:
- Thread Decoupling is Crucial: Algorithm state generation must reside strictly on a background dispatcher (
Dispatchers.Default), feeding state arrays to the UI thread using cold Kotlin Flow streams. - Adaptive UX: The spatial UI must adapt to varying illumination levels. High-contrast shaders are necessary to preserve readability in overexposed or dimly lit rooms.
- State Alignment: Designing a unified data model between Node.js schemas and Kotlin data classes simplifies mapping entities across the entire application lifecycle.
- Dynamic Kotlin DSL Compiler: Allow advanced users to compile and visualize custom Kotlin algorithms dynamically in 3D AR space.
- Collaborative Multi-User Rooms: Shared AR visualization rooms where multiple students can observe the same algorithm instance simultaneously via local anchor synchronization.
- Automated AI Explanations: Integrating Gemini API to provide verbal explanations of sorting anomalies, pivot selections, or pathfinding routes directly within the spatial environment.
"Technology is at its best when it makes the invisible, visible. ARgorithm is our contribution to a future where learning is not just about reading code, but about walking through it, interacting with it, and understanding it as a dynamic physical structure." — Team XRADIAN FUTURE
- Executive Summary
- Technical Architecture
- Directory & Workspace Layout
- Core Modules & Deep-Dive Implementation
- Algorithm Portfolio Database & Simulation Engine
- Backend API Reference (RESTful Architecture)
- Database Schemas & Data Model Mapping
- Workflows & Execution Mechanics
- Local Setup, Configuration & Deployment
- Testing, Quality Assurance & Coverage
- Security, Privacy & Compliance Controls
- Performance & Scalability Considerations
- FAQ & Troubleshooting Matrix
- Licensing & Acknowledgments
ARgorithm is a production-ready Mixed Reality learning system designed to visualize complex computer science algorithms. The system contains three primary layers:
- Android Client Application: A native application built with Jetpack Compose, Dagger Hilt, Coroutines, Room DB, and Sceneview AR. It handles motion tracking, spatial anchoring, touch interactions, and real-time rendering.
- API Server: A Node.js and Express backend that manages user authentication, global leaderboards, learning sessions, profile tracking, and algorithm metadata.
- Database Cluster: Dual-tier storage featuring local SQLite (via Room) for offline accessibility and MongoDB Atlas for central cloud-based user metrics tracking.
- Target Audience: CS and IT students, software engineering educators, interactive visual learners.
- Key Value Proposition: Eliminates the cognitive distance of code logic by turning algorithms into interactive physical structures.
- Device Support: Compatible with Android devices supporting ARCore (MinSDK 26, targetSDK 34).
The application is structured according to clean architecture guidelines to decouple business logic from the frameworks used for presentation and storage.
graph TD
subgraph PL["Presentation Layer (Mobile App)"]
ComposeUI[Jetpack Compose HUD & Layout]
AlgoVM[AlgorithmViewModel]
ARView[AR Visualizer Viewport]
SceneNode[Sceneview Node Graph]
end
subgraph DL["Domain Layer (Mobile App)"]
GetStepsUC[GetSimulationStepsUseCase]
GetAlgoUC[GetAlgorithmsUseCase]
DomainModels[Pure Kotlin Models: VisualStep, User, Quiz]
end
subgraph DAL["Data Layer (Mobile App)"]
MainRepo[AlgorithmRepositoryImpl]
LocalRoom[Room AppDatabase]
RetrofitClient[Retrofit Remote API Service]
end
subgraph Backend Services
ExpressAPI[ExpressJS Gateway]
MongooseODM[Mongoose ODM]
AtlasDB[(MongoDB Cloud Cluster)]
end
%% Interactions
ComposeUI -->|Triggers Actions| AlgoVM
AlgoVM -->|Observes States| ComposeUI
AlgoVM -->|Fetches data via| GetStepsUC
AlgoVM -->|Fetches list via| GetAlgoUC
GetStepsUC -->|Invokes| MainRepo
GetAlgoUC -->|Invokes| MainRepo
MainRepo -->|Reads/Writes| LocalRoom
MainRepo -->|Synchronizes via Network| RetrofitClient
RetrofitClient -->|HTTP Requests| ExpressAPI
ExpressAPI -->|Executes Queries| MongooseODM
MongooseODM -->|Stores data| AtlasDB
ARView -->|Binds to| SceneNode
AlgoVM -->|Feeds Data Streams| ARView
The following sequence diagram outlines the asynchronous flow of actions when a user launches a sorting visualization:
sequenceDiagram
autonumber
actor User
participant View as Compose AR Screen
participant VM as AlgorithmViewModel
participant LocalDB as Room SQLite
participant API as Express Server
participant Engine as AlgorithmEngine (Kotlin)
participant Scene as Sceneview AR Controller
User->>View: Select Algorithm (e.g. Quick Sort)
View->>VM: loadAlgorithm(algorithmId = "quick_sort")
VM->>LocalDB: Fetch Cached Metadata
LocalDB-->>VM: Metadata Object
VM->>API: Fetch Questions & High Scores (Async)
API-->>VM: Quiz Data & Leaderboard Info
VM->>Engine: generateSteps(algorithmId, inputData)
Note over Engine: Running pivot-partitioning logic...
Engine-->>VM: List<VisualStep>
VM->>View: Emit StateFlow(steps)
View->>Scene: Initialize Node Graph (Anchored Position)
loop Every Frame (Render & Interaction Loop)
User->>View: Tap "Next Step"
View->>VM: incrementStepIndex()
VM->>View: Update stepIndex
View->>Scene: Interpolate Bar Heights (Step Index)
Scene-->>User: Perform 3D animations (Swap/Highlight Colors)
end
User->>View: Exit / Finish Session
View->>VM: completeSession(duration)
VM->>LocalDB: Save Local Session Record
VM->>API: POST /api/user/sessions
API-->>VM: HTTP 201 Created (Sync Complete)
The repository contains three primary workspaces: the Android client app (app), the backend web server (server), and the shared codebase configuration (shared).
o:/ARgorithm/
├── app/
│ ├── src/
│ │ ├── main/
│ │ │ ├── java/com/XRADIANfuture/argorithm/
│ │ │ │ ├── data/
│ │ │ │ │ ├── local/ # Room SQLite framework integration
│ │ │ │ │ │ ├── dao/ # Room DAOs (UserDao, SessionDao, BadgeDao)
│ │ │ │ │ │ ├── entities/ # Room database entity tables
│ │ │ │ │ │ │ ├── UserEntity.kt
│ │ │ │ │ │ │ ├── SessionEntity.kt
│ │ │ │ │ │ │ └── BadgeEntity.kt
│ │ │ │ │ │ └── AppDatabase.kt # Local Database definition
│ │ │ │ │ ├── remote/ # Network communication layer
│ │ │ │ │ │ ├── dto/ # Data Transfer Objects
│ │ │ │ │ │ └── NetworkService.kt
│ │ │ │ │ └── repository/ # Data persistence implementations
│ │ │ │ │ ├── AlgorithmEngine.kt # Dynamic step generator
│ │ │ │ │ ├── AlgorithmRepositoryImpl.kt
│ │ │ │ │ └── AuthRepositoryImpl.kt
│ │ │ │ ├── di/ # Dagger Hilt Modules (Database, Network, Repos)
│ │ │ │ ├── domain/ # Domain logic layer
│ │ │ │ │ ├── models/ # Business models (VisualStep, Algorithm)
│ │ │ │ │ └── usecase/ # Orchestrator use cases
│ │ │ │ └── presentation/ # ViewModels and UI Screens
│ │ │ │ ├── algorithms/ # Selection lists and filter views
│ │ │ │ ├── auth/ # Sign-in and enrollment UI
│ │ │ │ ├── leaderboard/ # Interactive XP rank boards
│ │ │ │ ├── quiz/ # Dynamic evaluation screens
│ │ │ │ └── visualizer/ # Augmented Reality interfaces
│ │ │ │ ├── ARVisualizerScreen.kt # Entry point of the AR engine
│ │ │ │ ├── ar/ # Node placement & lighting loaders
│ │ │ │ ├── code_tracer/ # Highlighted line debugger UI
│ │ │ │ ├── formula_overlay/# Analytical analysis screen
│ │ │ │ └── telemetry/ # Performance metrics and HUD
│ │ │ └── res/ # System themes, colors, and layout configurations
│ │ │ └── AndroidManifest.xml # Process setup & hardware permission requests
│ └── build.gradle.kts # App dependencies (Compose, ARCore, Filament)
├── server/ # NodeJS Express API Platform
│ ├── middleware/ # Authentication validation handlers
│ ├── models/ # Mongoose MongoDB schemas
│ │ ├── User.js
│ │ ├── Algorithm.js
│ │ ├── Quiz.js
│ │ ├── Session.js
│ │ └── Badge.js
│ ├── routes/ # Route controllers
│ │ ├── auth.js # OAuth and native sign-in pipelines
│ │ ├── algorithms.js # Retrieval and metadata engines
│ │ ├── quizzes.js # Evaluation routers and XP calculators
│ │ └── user.js # Sessions and profiling routers
│ ├── seed.js # Database bootstrapping script
│ ├── server.js # Server entrypoint file
│ └── package.json # Backend service configurations
└── settings.gradle.kts # Gradle configuration setting
The core execution engine is a decoupled, pure-logic runtime (AlgorithmEngine.kt). When an algorithm is loaded, this engine takes the current input data array and executes the specified computer science algorithm sequentially.
Rather than rendering the output immediately, the engine captures every intermediate mutation (comparison, index swap, pointer change, or edge traversal) as a sequential step called VisualStep. This list is returned to the ViewModel as a historical progression log, allowing users to move forward, backward, or auto-play through the algorithm execution sequence.
The presentation layer uses the Sceneview framework (which runs on Google's Filament PBR engine) to map the raw list of VisualStep entities into a virtual coordinate space.
- Dynamic Cube Generation: When the data array is anchored to a surface, the visualizer builds a series of
CubeNodeinstances. Each index in the data array is represented as a physical cube. The height of the cube maps to the value of the array element. - Physically Based Shading: The color states of the nodes change dynamically using physical lighting parameters:
- Inactive/Default State: Standard polished concrete texture (white/grey).
- Active Comparison State: Glowing emission material (blue).
- Pivot/Key State: High-intensity warning emission (red).
- Sorted/Final State: Metallic reflective surface (green).
- Anchor Stability: Utilizing ARCore's plane detection APIs, the system places a base anchor (
AnchorNode) on the floor or table surface. Subsequent coordinate updates are calculated relative to this anchor, preventing the 3D nodes from shifting or floating away during rapid camera movements.
// Example: Creating and configuring a custom 3D cube node in Filament space
class ArrayBarNode(
val value: Int,
context: Context,
engine: Engine
) : CubeNode(engine, size = Float3(0.08f, value * 0.05f, 0.08f)) {
init {
// Apply smooth Material instances
this.isEditable = false
this.position = Position(0f, (value * 0.05f) / 2f, 0f)
}
fun updateColorState(state: ElementState, engine: Engine) {
val color = when (state) {
ElementState.DEFAULT -> Float4(0.8f, 0.8f, 0.8f, 1.0f)
ElementState.COMPARING -> Float4(0.0f, 0.5f, 1.0f, 1.0f)
ElementState.PIVOT -> Float4(1.0f, 0.0f, 0.0f, 1.0f)
ElementState.SORTED -> Float4(0.0f, 0.8f, 0.0f, 1.0f)
}
// Material parameter binding
this.materialInstance.setParameter("baseColor", color.x, color.y, color.z, color.w)
}
}The system includes two essential components inside the visualization view:
- Code Tracer: Displays formatted, Kotlin-like pseudocode. As the user traverses the
VisualSteplog, the UI automatically highlights the specific line of code being executed. - Telemetry HUD: Displays real-time device profiling data:
- Render Frame Rate: Confirms target performance (60FPS/30FPS).
- Anchor Tracking Quality: Provides feedback on lighting conditions and tracking state (TRACKING, PAUSED, EXCESSIVE_MOTION).
- Engine Overhead: Monitors JVM garbage collection spikes and Filament node count memory.
The following matrix documents the performance characteristics and visual models of the algorithm portfolio supported by the AlgorithmEngine:
| Algorithm Identifier | Category | Time Complexity (Avg.) | Space Complexity | Visual Presentation Style |
|---|---|---|---|---|
bubble_sort |
Exchange Sorting | O(n²) | O(1) | Bouncing 3D cube swaps with vertical comparisons. |
selection_sort |
Selection Sorting | O(n²) | O(1) | Highlighting minimal elements and swapping them to front. |
quick_sort |
Divide & Conquer | O(n log n) | O(log n) | Pivoting animations where arrays partition dynamically. |
merge_sort |
Divide & Conquer | O(n log n) | O(n) | Splits 3D bars into separate rows and merges them. |
binary_search |
Logarithmic Search | O(log n) | O(1) | Subdivides array with moving Left, Right, and Mid markers. |
linear_search |
Sequential Search | O(n) | O(1) | Sequential scanning beam pointing at index values. |
dijkstra |
Graph Traversal | O(V²) | O(V) | Node networks with relaxing edges and path coloring. |
bfs |
Graph Traversal | O(V + E) | O(V) | Radial wave expanding to adjacent vertices. |
dfs |
Graph Traversal | O(V + E) | O(V) | Recursive linear branch exploring with traceback animations. |
knapsack |
Dynamic Programming | O(nW) | O(nW) | Grid matrix values updating based on inclusion formulas. |
fibonacci |
Dynamic Programming | O(n) | O(n) | Dynamic bar charts growing step-by-step from base cases. |
The partition step of Quick Sort is implemented inside AlgorithmEngine.kt as follows:
private fun runQuickSort(input: List<Int>): List<VisualStep> {
val steps = mutableListOf<VisualStep>()
val arr = input.toMutableList()
steps.add(VisualStep(arr.toList(), pivotIdx = -1, activeL = -1, activeR = -1, "Initial unsorted array: $arr"))
fun quickSortHelper(low: Int, high: Int) {
if (low < high) {
val pivot = arr[high]
steps.add(VisualStep(arr.toList(), pivotIdx = high, activeL = low, activeR = high, "Selected pivot: $pivot at index $high"))
var i = low - 1
for (j in low until high) {
steps.add(VisualStep(arr.toList(), pivotIdx = high, activeL = i.coerceAtLeast(0), activeR = j, "Comparing index $j ($arr[$j]) with pivot $pivot"))
if (arr[j] < pivot) {
i++
val temp = arr[i]
arr[i] = arr[j]
arr[j] = temp
steps.add(VisualStep(arr.toList(), pivotIdx = high, activeL = i, activeR = j, "Swapped index $j and $i"))
}
}
val temp = arr[i + 1]
arr[i + 1] = arr[high]
arr[high] = temp
val pi = i + 1
steps.add(VisualStep(arr.toList(), pivotIdx = pi, activeL = -1, activeR = -1, "Pivot placed in final position: index $pi"))
quickSortHelper(low, pi - 1)
quickSortHelper(pi + 1, high)
}
}
quickSortHelper(0, arr.size - 1)
steps.add(VisualStep(arr.toList(), pivotIdx = -1, activeL = -1, activeR = -1, "Sorting completed: $arr"))
return steps
}The Node.js Express server is deployed on Render and exposes RESTful routes for state management and user authentication.
Production API Endpoint: https://argorithm-backend.onrender.com
Creates a user profile and generates a JWT.
- Request Payload:
{ "username": "NandhiniXR", "email": "nandhini@krct.edu", "passwordHash": "SuperSecure123" } - Response Payload (HTTP 201):
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2NmNi...", "user": { "_id": "66cbeabcf123", "username": "NandhiniXR", "email": "nandhini@krct.edu", "totalXp": 0, "studyTimeMinutes": 0, "level": 1, "enrolledDomains": [] } }
Validates credentials and returns an active session token.
- Request Payload:
{ "email": "nandhini@krct.edu", "passwordHash": "SuperSecure123" } - Response Payload (HTTP 200):
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2NmNi...", "user": { "_id": "66cbeabcf123", "username": "NandhiniXR", "email": "nandhini@krct.edu", "totalXp": 120, "studyTimeMinutes": 45, "level": 2, "enrolledDomains": ["Sorting", "Graph"] } }
Retrieves current profile metadata (requires Bearer Token).
- Request Headers:
Authorization: Bearer <token> - Response Payload (HTTP 200):
{ "_id": "66cbeabcf123", "username": "NandhiniXR", "email": "nandhini@krct.edu", "totalXp": 450, "studyTimeMinutes": 120, "level": 3, "enrolledDomains": ["Sorting", "Searching"] }
Records a finished study session and updates user metrics (requires Bearer Token).
- Request Headers:
Authorization: Bearer <token> - Request Payload:
{ "durationMinutes": 30, "xpEarned": 100, "algorithmsLearned": ["quick_sort", "binary_search"], "quizzesCompleted": 1, "accuracy": 85 } - Response Payload (HTTP 201):
{ "success": true }
Retrieves the questions associated with a specified algorithm.
- Response Payload (HTTP 200):
[ { "_id": "66cc123abcde789", "algorithmId": "quick_sort", "questionText": "What is the worst-case time complexity of Quick Sort?", "options": ["O(n log n)", "O(n²)", "O(n)", "O(log n)"], "correctOptionIndex": 1, "xpValue": 20 } ]
Validates quiz responses, adds earned XP to the user profile, and checks badge awards (requires Bearer Token).
- Request Headers:
Authorization: Bearer <token> - Request Payload:
{ "algorithmId": "quick_sort", "score": 5, "totalQuestions": 5 } - Response Payload (HTTP 200):
{ "success": true, "xpAwarded": 50, "earnedBadge": { "_id": "77bc123def", "name": "Quick Sort Champion", "description": "Scored 100% on the Quick Sort analysis exam.", "imageUrl": "https://krct.edu/badges/quicksort_gold.png", "tier": "Gold", "earnedDate": "2026-06-23T12:00:00Z" } }
Retrieves all algorithm datasets.
- Response Payload (HTTP 200):
[ { "_id": "66ca123df456", "name": "Quick Sort", "description": "A highly efficient sorting algorithm using divide-and-conquer strategy.", "category": "Sorting", "timeComplexity": { "best": "O(n log n)", "average": "O(n log n)", "worst": "O(n²)" }, "spaceComplexity": "O(log n)", "difficulty": "Intermediate" } ]
Retrieves leaderboards ranked by earned user experience (XP).
- Response Payload (HTTP 200):
[ { "_id": "66cbeabcf123", "username": "NandhiniXR", "xp": 450, "badgesCount": 3, "studyTimeMinutes": 120 }, { "_id": "66cbeabcf456", "username": "GodfreyAR", "xp": 420, "badgesCount": 2, "studyTimeMinutes": 110 } ]
The system uses a unified data model between Node.js schemas and Kotlin entities. This ensures consistent data mapping across the client application, local cache, and cloud database.
// User Schema definition (server/models/User.js)
const userSchema = new mongoose.Schema({
username: { type: String, required: true, unique: true, trim: true },
email: { type: String, required: true, unique: true, lowercase: true },
passwordHash: { type: String, required: true },
totalXp: { type: Number, default: 0 },
level: { type: Number, default: 1 },
studyTimeMinutes: { type: Number, default: 0 },
enrolledDomains: [{ type: String }],
dailyGoalMinutes: { type: Number, default: 30 },
badges: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Badge' }],
createdAt: { type: Date, default: Date.now }
});
// Session Schema definition (server/models/Session.js)
const sessionSchema = new mongoose.Schema({
userId: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
durationMinutes: { type: Number, required: true },
xpEarned: { type: Number, default: 0 },
algorithmsLearned: [{ type: String }],
quizzesCompleted: { type: Number, default: 0 },
accuracy: { type: Number, default: 0 },
createdAt: { type: Date, default: Date.now }
});
// Badge Schema definition (server/models/Badge.js)
const badgeSchema = new mongoose.Schema({
name: { type: String, required: true },
description: { type: String, required: true },
imageUrl: { type: String },
tier: { type: String, enum: ['Bronze', 'Silver', 'Gold', 'Platinum'], default: 'Bronze' },
criteria: { type: String, required: true } // Criteria mapping (e.g. "complete:quick_sort")
});// Local User Cache Table (app/src/main/java/com/XRADIANfuture/argorithm/data/local/entities/UserEntity.kt)
@Entity(tableName = "users")
data class UserEntity(
@PrimaryKey val id: String,
val username: String,
val email: String,
val totalXp: Int,
val studyTimeMinutes: Int,
val level: Int,
val dailyGoalMinutes: Int
)
// Local Session Cache Table (app/src/main/java/com/XRADIANfuture/argorithm/data/local/entities/SessionEntity.kt)
@Entity(tableName = "sessions")
data class SessionEntity(
@PrimaryKey(autoGenerate = true) val localId: Long = 0,
val durationMinutes: Int,
val xpEarned: Int,
val quizzesCompleted: Int,
val accuracy: Int,
val isSynced: Boolean = false
)This workflow diagram illustrates the process from workspace camera initialization to spatial plane detection, node assembly, and real-time interactive rendering:
graph TD
A[Start Session] --> B[Initialize ARCore Session]
B --> C[Configure Camera Stream]
C --> D[Scan Environment for Planes]
D -->|Plane Detected| E[Render Plane Dots HUD]
D -->|No Plane Found| D
E --> F[User Taps Placement Area]
F --> G[AnchorNode Bound to HitResult]
G --> H[Retrieve SimulationSteps from ViewModel]
H --> I[Instantiate CubeNodes relative to AnchorNode]
I --> J[Attach Dynamic Material Instances]
J --> K[Execution Loop]
K --> L{Check Interaction State}
L -->|User Taps NextStep| M[Increment Index]
L -->|User Taps Play| N[Auto-advance Steps using Timer]
L -->|User Taps Reset| O[Set Index to Zero]
M --> P[Calculate Delta Height / Position Vector]
N --> P
O --> P
P --> Q[Interpolate Node Position via Filament Engine]
Q --> R[Update Color Shader State]
R --> S[Display Step Details on Telemetry Overlay]
S --> K
Ensure the target development environments match these platform releases:
- Android Development:
- Android Studio Jellyfish (2023.3.1+) or newer.
- Android SDK 34 (Target SDK).
- JDK 17.
- Backend Server:
- NodeJS LTS v18.16.0 or newer.
- Active MongoDB Cluster (Local community instance or cloud Atlas endpoint).
- Verify the root-level build configuration dependencies:
// build.gradle.kts (Project configuration) plugins { id("com.android.application") version "8.2.2" apply false id("org.jetbrains.kotlin.android") version "1.9.22" apply false id("com.google.dagger.hilt.android") version "2.50" apply false }
- Add dependencies to the module Gradle settings:
// app/build.gradle.kts dependencies { // ARCore & Sceneview libraries implementation("com.google.ar:core:1.42.0") implementation("io.github.sceneview:ar:1.0.8") // Jetpack Compose & Materials implementation("androidx.compose.ui:ui:1.6.2") implementation("androidx.compose.material3:material3:1.2.0") // Local SQLite Room Database implementation("androidx.room:room-runtime:2.6.1") implementation("androidx.room:room-ktx:2.6.1") kapt("androidx.room:room-compiler:2.6.1") // Dependency Injection implementation("com.google.dagger:hilt-android:2.50") kapt("com.google.dagger:hilt-compiler:2.50") }
- Configure API connectivity inside
local.properties:# Production backend URL api.baseUrl="https://argorithm-backend.onrender.com/api/" # Or for local development mapping (Android Emulator) # api.baseUrl="http://10.0.2.2:5000/api/"
- Configure the environment configuration properties in
/server/Android:PORT=5000 MONGODB_URI=mongodb+srv://admin:<password>@cluster0.argorithm.mongodb.net/ MONGODB_NAME=argorithm_prod JWT_SECRET=super_secret_cryptographic_signing_key_9988
- Install platform dependencies:
cd server npm install - Seed the DB with questions, badge criteria, and algorithm metadata:
npm run seed
- Run the local Node development cluster:
npm run dev
To configure the Express backend for production environments, use the following server blueprints:
Create a container file at /server/Dockerfile:
FROM node:18-alpine
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
# Environment properties passed dynamically at runtime
ENV PORT=5000
EXPOSE 5000
CMD [ "node", "server.js" ]Create a Docker Compose orchestrator blueprint at /server/docker-compose.yml:
version: '3.8'
services:
api:
build: .
ports:
- "5000:5000"
environment:
- PORT=5000
- MONGODB_URI=mongodb+srv://admin:${DB_PASS}@cluster0.argorithm.mongodb.net/
- MONGODB_NAME=argorithm_prod
- JWT_SECRET=${JWT_SIGNING_KEY}
restart: always
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"server {
listen 80;
server_name api.argorithm.krct.edu;
location / {
proxy_pass http://localhost:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}The codebase utilizes multiple testing suites to verify the correctness of algorithm execution, spatial node placement, and client-server synchronization.
graph LR
Unit[Unit Tests: Domain Rules] -->|Validate logic| Engine[AlgorithmEngine]
Integration[Integration Tests: Room/Retrofit] -->|Validate sync| Cache[Repository Store]
UITest[UI Compose Instrumented Tests] -->|Validate HUD states| Compose[Screens/HUD Components]
ARStability[Spatial Drift Scenarios] -->|Validate anchors| ARCore[Sceneview Render Quality]
- Unit Tests: Validate the correctness of the sorting logic in
AlgorithmEngine.kt. - Integration Tests: Verify local SQLite caching and state synchronization pipelines under offline/online transitions.
- UI Instrumented Tests: Execute rendering validation on physical or emulated devices to test coordinate scaling and gesture responses.
Run the backend Express test suite:
cd server
npm testExecute Android unit testing suites:
./gradlew testDebugUnitTestExecute Android system-level instrumented UI tests:
./gradlew connectedAndroidTestARgorithm requests system access to android.permission.CAMERA exclusively for ARCore's feature-point mapping and spatial coordinate anchoring.
- Local Execution: Camera frames are processed strictly inside volatile device memory on the local device via ARCore system service frameworks.
- Zero External Transmission: Raw image data or spatial point maps are never stored locally or transmitted to external servers. Only anonymous telemetry values (such as feature point density) are processed for coordinate alignment.
- Bcrypt Hashing: User passwords are encrypted on the database using a Work Factor (Salt Rounds) of 10. Passwords are never stored or transmitted in plain text.
- JSON Web Tokens: Server authentication routes produce HMAC-SHA256 signature tokens. These tokens contain encoded claims and are set to expire 30 days from creation.
- TLS Pinning: Mapped inside network configuration files to restrict base API routes to TLS 1.3 servers.
- Android Keystore Caching: User registration details cached for offline use are written to encrypted local memory using AES-GCM encryption keys.
AR processing requires significant device resources. ARgorithm uses several optimization strategies to maintain smooth performance:
- Garbage Collection Tuning: In standard rendering runs, generating garbage collections can cause dropped frames. To avoid memory spikes,
CubeNodeinstances are recycled across visualization steps. When values update, the visualizer adjusts the scale values of the existing mesh rather than destroying and recreating objects. - Polygon Optimization: Standard rendering elements use low-complexity polygon meshes. Lighting details are rendered using dynamic lighting maps rather than complex node polygons.
- Kotlin Coroutines Dispatching: Long-running simulations run strictly on
Dispatchers.Defaultbackground worker threads. This keeps the main thread clear to handle the 60FPS user interaction and coordinate rendering loop.
// Asynchronous simulation data processing architecture
class AlgorithmViewModel @Inject constructor(
private val getSimulationStepsUseCase: GetSimulationStepsUseCase
) : ViewModel() {
private val _stepsState = MutableStateFlow<List<VisualStep>>(emptyList())
val stepsState: StateFlow<List<VisualStep>> = _stepsState.asStateFlow()
fun loadSteps(algorithmId: String) {
viewModelScope.launch {
// Process calculations off the Main thread
val steps = withContext(Dispatchers.Default) {
getSimulationStepsUseCase(algorithmId)
}
_stepsState.value = steps
}
}
}- Connection Pooling: MongoDB connections are configured with active pool configurations (
maxPoolSize = 50) to reuse connections. - Index Execution Plans: MongoDB collections include indexed fields for optimized query speeds:
userSchema.index({ email: 1 }); userSchema.index({ totalXp: -1 }); sessionSchema.index({ userId: 1, createdAt: -1 });
| System Fault | Potential Root Cause | Resolution |
|---|---|---|
| Virtual elements float away or drift | Dynamic tracking fails due to insufficient lighting or uniform textureless surfaces (e.g. clean white tables). | Increase ambient light levels or scan a textured surface (such as a wood grain table or carpet floor). |
| App crash immediately after opening camera | Missing or outdated ARCore services on the host Android device. | Open the Google Play Store and update Google Play Services for AR to the latest version. |
| Stuttering animations when stepping through algorithms | High CPU overhead caused by processing too many nodes at once. | Lower the size of the array (n <= 15) in sandbox mode settings. |
| Offline data progress is not synced | Client network request timed out or JWT token expired. | Open the Profile dashboard when connected to the internet to trigger progress sync. If needed, sign out and sign back in to renew your token. |
| "Authentication Refused" on local deployment runs | Local API server points to localhost 127.0.0.1 instead of Android emulator mapping 10.0.2.2. |
Update the server mapping address inside the network configuration parameters or local.properties base URL settings. |
Team XRADIAN FUTURE and the XR Club extend their sincere gratitude to:
- Dr. S. Saravanan (Faculty Head, KRCT XR Innovation Centre) for providing continuous leadership and project resources.
- Dr. R. Jaiganesh & Mrs. R. Jasmine for their technical guidance, engineering reviews, and encouragement.
- The KRCT Management & Center for Student Affairs for establishing a state-of-the-art space for spatial computing research.
- Google ARCore & Filament Engineering Teams for open-sourcing the frameworks that power our spatial rendering system.
ARgorithm is released under the MIT License.