How CodeCityApp is designed to teach

Beginners often get stuck between reading code and writing it on their own. CodeCityApp's learning design is built on published research about how people learn, so every scaffold has a reason to be there. Learning to code is the goal; the game serves it.

Our logic model

  1. Inputs: A curriculum of coding cities and districts, concept lessons in a prerequisite graph, ARIA the AI mentor, automated graders, and a teacher dashboard.
  2. Activities: A short lesson before each new concept; a graduated hint ladder with feedback that never gives away the answer; an optional "arrange the lines" scaffold after a failed attempt; "explain it back" prompts; a city-building game layer.
  3. Outputs: Lessons completed, challenges passed, scaffolds solved and followed by an unaided pass, explanations written, and progress teachers can see.
  4. Outcomes: Short term, fewer learners give up after a failed attempt and more can explain why their code works. Long term, learners write working code without scaffolds and keep coming back on their own.

Five research-based design decisions

1. Explain it back

After a learner passes with help, ARIA asks what fixed it.

Why: Putting an idea in your own words deepens understanding.

Chi, M. T. H., de Leeuw, N., Chiu, M.-H., & LaVancher, C. (1994). Eliciting self-explanations improves understanding. Cognitive Science, 18(3), 439–477.

2. Arrange the lines

After a failed attempt, learners can rebuild the solution by ordering shuffled lines, then write it themselves.

Why: Ordering code teaches structure faster than writing from scratch, with similar learning.

Ericson, B. J., Margulieux, L. E., & Rick, J. (2017). Solving Parsons problems versus fixing and writing code. Proceedings of the 17th Koli Calling International Conference on Computing Education Research, 20–29.

Hou, X., Ericson, B. J., & Wang, X. (2023). Understanding the effects of using Parsons problems to scaffold code writing for students with varying CS self-efficacy levels. Proceedings of the 23rd Koli Calling International Conference on Computing Education Research. https://doi.org/10.1145/3631802.3631832

3. A lesson before every new concept

A short story lesson shows the idea, has you complete it, then sends you into the challenge.

Why: Beginners learn more from a worked example followed by practice than from solving problems cold.

Atkinson, R. K., Derry, S. J., Renkl, A., & Wortham, D. (2000). Learning from examples: Instructional principles from the worked examples research. Review of Educational Research, 70(2), 181–214.

4. Hints that teach, not tell

ARIA's hints come in levels, and feedback never contains the answer.

Why: Feedback is one of the strongest influences on learning, and too much help undermines it as much as too little.

Hattie, J., & Timperley, H. (2007). The power of feedback. Review of Educational Research, 77(1), 81–112. https://doi.org/10.3102/003465430298487

Koedinger, K. R., & Aleven, V. (2007). Exploring the assistance dilemma in experiments with cognitive tutors. Educational Psychology Review, 19, 239–264.

5. A city you build by learning

Every challenge you pass adds a building to your city, with weekly challenges and leagues.

Why: Well-designed gamification has a positive effect on learning, and competition paired with collaboration helps.

Sailer, M., & Homner, L. (2020). The gamification of learning: A meta-analysis. Educational Psychology Review, 32, 77–112. https://doi.org/10.1007/s10648-019-09498-w

Our study

We are running a qualitative study with learners and educators in our current pilots to understand how these design decisions work in practice. Results are expected in early 2027 and will be published here.

Privacy

How we protect learner data