Hyper_Mapper

Hyper-Mapper: Adapting rigid curricula to the neurodivergent brain through cognitive translation.

Comment

Inspiration

Standard accessibility tools fundamentally misunderstand the neurodivergent academic experience. When a student is overwhelmed by dense, rigid curriculum, most tools simply make the font bigger, increase line spacing, or chunk paragraphs into shorter sentences. But for neurodivergent students, high working-memory demands don't just cause boredom—they trigger executive dysfunction. We realized that reformatting text is not enough; we needed to translate it.

The problem space is severe: according to Connolly, Constable & Mullally (2023, Frontiers in Psychiatry), 92.1% of students experiencing severe school distress are neurodivergent. Hyper-Mapper was inspired by the need to stop forcing neurodivergent brains to adapt to the curriculum, and instead adapt the curriculum to the brain's existing pathways using a psychological framework called "Cognitive Anchoring."

What it does

Hyper-Mapper is a cognitive translation engine. It takes complex, abstract academic concepts (like Neural Action Potentials) and maps them directly onto a student's personal hyper-fixation or "cognitive anchor" (like video game mechanics or cooking steps).

  • Cognitive Translation: The engine dynamically generates a systemic analogy, translating each scientific step into the exact mechanics of the student's chosen anchor.
  • Active Recall (Bridge Check): To ensure this is an academic tool and not just a story generator, every map concludes with a Bridge Check. This forces the student to step out of the analogy and answer a comprehension question using only the core scientific vocabulary, proving actual retention.
  • Offline Advocacy (Teacher Pass): Through the "My Learning DNA" dashboard, students can export a physical, printed Teacher Pass. This artifact clearly communicates their ideal cognitive anchors and sensory needs to educators with zero medical labels or diagnostic profiling required.

How we built it

We architected Hyper-Mapper with a focus on speed, privacy, and strict data shaping.

  • Frontend (Situation & Task): We needed a highly responsive, OS-like environment. Action: We built the application shell using TanStack Start, React, and Tailwind CSS, isolating the workspace into discrete, easily navigable views (Dashboard, Learning DNA, History).
  • Backend Translation (Task & Action): To handle the cognitive mapping, we deployed Supabase Edge Functions connected to Google's Gemini API. We enforced a rigid JSON schema instruction layer to ensure the LLM strictly adhered to the structural analogy without hallucinating unprompted text.
  • Local Pattern Intelligence (Result): To completely protect student privacy, we bypassed a traditional cloud database for user history. We engineered a local pattern engine that reads localStorage to compute history logs and preferred anchor statistics entirely client-side.

Challenges we ran into

During our core testing phase, the application suddenly began returning 503 Service Unavailable and 429 Rate Limit errors.

  • The Problem: The Gemini API's free-tier proxy layer was experiencing heavy global traffic spikes, completely halting our core generation pipeline.
  • The Technical Fix: We immediately overhauled our Supabase Edge Function to bypass the OpenAI compatibility proxy layer and routed directly to the Native Gemini REST endpoint (:generateContent). Furthermore, we engineered an asynchronous fetchWithRetry wrapper featuring exponential backoff. If the server drops a 503, our function now automatically catches it, pauses, and retries seamlessly without ever throwing an error to the frontend UI.

Accomplishments that we're proud of

We are most proud of our commitment to authentic, iterative design. We tested our prototype with an anonymous neurodivergent individual in a clinical setting.

Their immediate feedback was that while the analogies successfully bypassed executive dysfunction, standard text sizes still caused visual crowding and sensory friction. Based directly on this user session, we completely overhauled our CSS architecture midway through the hackathon. We implemented what we call Cognitive Padding—scaling our typography by 4x and enforcing massive readability margins across the entire application to completely eliminate visual strain.

What we learned

We learned the critical difference between cosmetic accessibility and structural accessibility. Throwing a "high contrast" toggle on a website does not solve cognitive load. True accessibility requires engineering systems that respect how a user's working memory operates. We also learned how to enforce strict data shapes on LLM outputs to guarantee that our educational tool remains predictable, reliable, and academically rigorous.

What's next for Hyper-Mapper

Based directly on the feedback from our clinical tester session, our immediate next step is multi-modal output. The tester expressed a strong desire for video-based outputs rather than just text cards. Version 2.0 of Hyper-Mapper will integrate an AI video generation pipeline, turning these cognitive analogies into highly visual, animated micro-lessons, further reducing the reading burden for students with dyslexia or severe ADHD.

Here is the technical architecture breakdown and the academic methodology section. Devpost judges, especially in the accessibility and medical/clinical tracks, heavily reward projects that can prove their software architecture is directly informed by peer-reviewed science.

System Architecture & Data Flow

To ensure absolute data privacy and high-availability generation, we bypassed traditional monolithic databases in favor of a decentralized, edge-computed architecture.

The Hyper-Mapper Pipeline:

[ User Interface ]  --> (React, TanStack Start, Tailwind CSS)
       │
       ├─> Client-Side Processing (FileReader for Document Parsing)
       │
       ├─> [ Local Intelligence Engine ] --> (localStorage)
       │     └─ Tracks history & computes 'Learning DNA' locally. Zero cloud tracking.
       │
       └─> [ API Layer ] --> (Supabase Edge Functions)
             │
             ├─> Asynchronous Fetch Wrapper (Exponential Backoff for 503/429 mitigation)
             │
             └─> [ Native AI Engine ] --> (Google Gemini 2.5/3.6 Flash REST API)
                   └─ Strict JSON Schema Validation & Cognitive Translation

Technical Execution Flow:

  1. Input: The user types a concept and an anchor. Our frontend sanitizes the inputs and routes them to a secure Supabase Edge Function.
  2. Translation (LLM): The Edge Function bypasses standard translation proxies, hitting the native Gemini REST endpoint to maximize availability. It injects a rigid system prompt that forces the LLM to map the academic concept to the user's anchor without hallucinating markdown or conversational filler.
  3. Validation: The Supabase function strictly validates the returned JSON shape (ensuring arrays, mapping objects, and correct indices exist) before returning a 200 OK to the frontend.
  4. Rendering & Storage: The frontend dynamically renders the UI with 'Cognitive Padding' (4x typography scaling) and logs the session purely in the browser's localStorage to compute the offline Teacher Pass.

Academic & Clinical Methodology

Hyper-Mapper is not just an LLM wrapper; it is an educational tool engineered upon established clinical and cognitive frameworks.

  • The Problem Space (Executive Dysfunction): As highlighted by Connolly, Constable & Mullally (2023, Frontiers in Psychiatry), standard educational environments frequently trigger severe distress in neurodivergent students (accounting for 92.1% of severe school distress cases). This distress is fundamentally driven by overwhelming working-memory demands and executive dysfunction.
  • Cognitive Load Theory (Sweller, 1988): Standard accessibility tools increase extraneous cognitive load by forcing students to decode complex, unfamiliar academic language, even if the text is physically larger. Hyper-Mapper directly reduces intrinsic cognitive load by translating new information into a system the student already understands perfectly.
  • Schema Activation Theory: By utilizing "Cognitive Anchors" (a student's personal hyper-fixation), our engine instantly activates a highly developed, pre-existing cognitive schema. Instead of building new neural pathways from scratch, the student securely attaches the new academic concept to the robust, existing architecture of their hyper-fixation.

Built With

Share this project:

Updates