CodeQuest

hint
expedition complete
challenge passed-2
expedition report
challenge-passed
challenge
journal
walkthrough
main page
correct answer
developer desk
repository map

Inspiration

We both come from the world of large enterprise systems: 15 years of code trapped in different rooms—a monolith, SOA, microservices, and even a little Visual Basic hiding in the basement.

We have seen new engineers struggle to understand systems like this firsthand. The challenge is not simply finding documentation. Years of documentation become scattered across wikis, diagrams, tickets, and people’s heads, while the live system continues changing every day. Documentation updates are often sacrificed for delivery.

There is also a human problem. New engineers are trying to make a good impression, especially during probation, so they may not admit how lost they feel. Managers ask, “How is onboarding going?” and usually hear, “Fine,” without knowing what the newcomer actually understands.

AI coding assistants help when someone asks the right question—but newcomers often do not know what they do not know.

Our team combines experience in enterprise software, architecture, engineering leadership, and gaming. That led us to ask: what if learning a codebase felt less like wandering through folders and more like exploring a world?

That question became CodeQuest.

What it does

CodeQuest turns a public code repository into an interactive learning adventure.

The player provides a GitHub repository URL. CodeQuest analyses its structure and relationships, then transforms its architectural domains into districts on an explorable map. Routes between districts represent meaningful dependencies and learning prerequisites.

In every district, the player meets a domain guide—an NPC who explains what that part of the system owns, how it interacts with other components, and why it matters. The explanation is connected to evidence from the real repository rather than being a generic AI summary.

The player then completes activities such as:

Reconstructing the correct sequence of a request or business flow
Following an execution path through several modules
Finding evidence that supports a technical statement
Answering questions about component responsibilities
Identifying the safest change surface for a new requirement

Help is always available. Progressive hints can point the player towards the right responsibility, reveal a focused dependency path, or replay the relevant explanation. Getting stuck does not end the experience—it changes how CodeQuest teaches the concept.

As players progress, they earn XP, unlock new districts, collect knowledge artifacts, and receive playful developer rewards such as a rubber duck, Friday pizza, or cool headphones. Their discoveries, attempts, hints, and completed missions are recorded in a Field Journal.

At the end, CodeQuest generates an Expedition Report showing which areas were explored, what the player understood independently, where support helped, and which topics may need further attention. The report gives the newcomer a record of their progress and can provide their manager or mentor with a more meaningful onboarding conversation.

How we built it

CodeQuest is a full-stack application built with Next.js, React, and TypeScript, with Tailwind CSS powering the interface.

When a user submits a repository, a restricted server-side pipeline downloads its public GitHub archive in read-only mode. It filters unsupported, generated, oversized, or potentially sensitive files and creates a bounded representation of the repository. Imported code is never installed or executed.

CodeQuest then builds a validated source graph showing relationships between the selected files. The architecture supports a deterministic static-import provider and a locked, server-side Graphify adapter.

The graph describes how the repository is structured, but a dependency graph alone is not a learning journey. GPT-5.6, accessed through the OpenAI Responses API, transforms the validated graph and repository digest into architectural districts, guides, walkthroughs, activities, hints, rewards, and progression.

The model returns Structured Outputs validated with Zod. We do not treat generated text as source evidence: every referenced path and line range is checked against the repository, and the displayed excerpts are reconstructed by the server. Invalid output receives one targeted repair attempt and then fails safely.

Progress is stored locally in the browser, so the MVP does not require accounts or a database. We used Vitest, React Testing Library, and Playwright for unit, integration, and end-to-end testing. Codex helped us convert the product concept into an implementation plan, build the application, create tests, investigate problems, and document the project.

CodeQuest was built by a 2-person team: Kseniia Korostelova and Denys Kniaziev.

We worked as a cross-functional pair throughout the project—from shaping the concept and narrowing the MVP to making architectural decisions, designing the experience, testing the result, and preparing the submission. Denys challenged the product requirements from an architect’s perspective, while Kseniia challenged the implementation through the eyes of an engineering leader, manager, and end user. This constant exchange helped us balance technical feasibility, learning value, security, and fun.

Challenges we faced

Our first challenge was scope. The original vision included a much larger RPG experience, battles, more character mechanics, and even challenges involving code changes. For a hackathon MVP, that would have diluted the core value. We removed those elements and focused on one complete loop: explore, learn, practise, receive support, demonstrate understanding, and progress.

The second challenge was trust. An AI-generated explanation can sound completely convincing while referring to an invented or incorrect part of the repository. We addressed this by separating AI judgment from deterministic validation: the model designs the learning journey, while the application verifies its evidence.

The third challenge was making CodeQuest feel like a game rather than a conventional learning dashboard wearing an XP badge. Our first interface was functional, but it was not fun. We redesigned it as a Living Technical Atlas, made architectural domains into places, introduced guides and exploration, and separated meaningful knowledge artifacts from playful cosmetic rewards.

Finally, we needed the experience to remain demonstrable without depending on a live API key or network call. We created a complete credential-free sample journey that uses the same campaign contract as live generation.

Accomplishments we are proud of

We built a complete end-to-end experience: repository ingestion, architectural map generation, NPC-guided learning, interactive activities, unlimited hints, XP, artifacts, rewards, a Field Journal, and an Expedition Report.

Early feedback validated both sides of the product. Andrii, a software engineer and gamer, liked the idea of making onboarding more enjoyable and immediately suggested collectible developer artifacts such as a coffee mug. Vlad, a team lead, valued the final report because it could reveal where a newcomer progressed easily and where they struggled. He also wanted managers to be able to define priority areas—feedback that directly influenced our next-step roadmap.

What we learned

We learned that a repository graph is not automatically a curriculum. Architecture extraction tells us what is connected; a learning experience must still decide what matters, what order makes sense, what evidence to show, and how to verify understanding.

We also learned that effective AI-generated education needs more than a summary. The useful unit is a claim connected to real evidence, followed by an activity that tests the learner’s mental model and a next step that responds to the result.

Most importantly, gamification should reinforce learning rather than distract from it. XP and rewards create momentum, but the real progression comes from understanding the system. Hints should not punish the learner—they should make invisible difficulties visible and help both the newcomer and their mentor understand what support works.

What's next

Our next step is to introduce separate newcomer and manager experiences.

Managers will be able to define onboarding priorities, starting levels, and the parts of the system that matter most for a particular role. They will also receive a dedicated, neutral view of the Expedition Report.

Newcomers will be able to personalise the visual theme and character of their adventure. We also want to expand language and repository support, introduce private-repository access with enterprise-grade permissions, and create longer learning journeys that evolve as the codebase changes.

Our ambition is simple: no engineer should have to explore an unfamiliar system alone or pretend that onboarding is going “fine.”

Adventure Awaits in Every Line.