Overview¶

ChoiceMap transforms linear content into interactive experiences. Instead of reading a document from start to finish, users navigate through a tree of choices where each decision opens a different path.

The three components¶

The framework consists of three distinct tools, each with a specific role.

Navigator¶

This is the visualization engine, what the end user sees and uses. It loads a JSON scenario and presents it as a sequence of screens. Each screen shows text content and a series of buttons to choose from, with the ability to attach files and share links. The choice determines which screen appears next.

The Navigator includes a visual journey map that shows where the user is in the decision tree, which nodes have been visited, and which remain to explore. Users can go back, start over, or jump to a specific point in the already visited part of the map.

Scenario Editor¶

This is the tool for creating and modifying scenarios without writing JSON manually. When opening an existing scenario for editing, the editor presents a list of all nodes, allows modifying their content, adding choices, and connecting nodes to each other.

The editor includes a map view showing the scenario's tree structure, highlighting the start node, end nodes, and any "orphan" nodes (disconnected from the main flow). This view helps identify structural problems before publishing.

Theme Editor¶

This is the tool for customizing the Navigator's visual appearance. It allows modifying colors, fonts, adding logo and company name, without touching the code.

Changes are visible in real-time in a preview. Once satisfied, save the theme as a JSON file and associate it with the scenario.

Typical use cases¶

ChoiceMap adapts to different training and communication contexts.

Corporate training¶

An onboarding course can become an interactive path where new employees explore company procedures by making choices and receiving contextual feedback. Instead of reading a 50-page manual, they navigate through scenarios that simulate real situations, connecting each step to specific chapters in related documents.

Compliance training is particularly well-suited: scenarios that present ambiguous situations, ask for a decision, and show the consequences of correct or incorrect choices.

Quizzes and assessments¶

A traditional quiz presents questions in sequence. With ChoiceMap, the path changes based on answers: those who answer correctly proceed, those who make mistakes receive an explanation and can retry or are directed to a deeper learning path.

This approach transforms assessment into a learning experience: the error is not just a negative score but an opportunity to understand better.

Process documentation¶

A workflow like support ticket management can be represented as a decision tree. The operator answers questions about the situation ("Is it a technical or billing issue?", "Is the service completely down?") and is guided toward the correct procedure.

This approach allows representing complex situations, reducing errors and accelerating new staff training.

Interactive storytelling¶

Stories in "choose your own adventure" style where the reader makes choices between multiple paths. Useful for experiential training, negotiation simulations, exploration of ethical scenarios.

Technical architecture¶

ChoiceMap is built with standard web technologies: HTML, CSS, JavaScript. It uses React for the interface and Tailwind CSS for styling, both loaded from CDN. It requires no compilation or dependency installation.

Each scenario is a JSON file with a simple structure: metadata (title, author), interface label translations, and a collection of nodes. Each node has text content in Markdown and a list of choices pointing to other nodes.

Themes are also JSON files that define colors, fonts, and branding information.

The Navigator works on any modern browser and automatically adapts to desktop and mobile devices.