Wayfare
Inspiration
There is no shortage of free educational content online. For almost any topic, learners can find videos, articles, tutorials, and reference material within seconds.
The problem is that these resources are usually unstructured.
A learner may open several tabs, watch part of a video, read half an article, and still have no clear answer to three important questions:
- What should I learn first?
- What should I study next?
- Did I actually understand what I just studied?
Most search engines provide links but do not provide progression. Traditional learning platforms provide progression, but only for courses that someone has already created manually.
We built Wayfare to bridge that gap.
Wayfare turns any learning topic into a structured transit-map route made from freely available resources. Each station represents a learning objective, and the next station remains locked until the learner passes a comprehension check.
The central idea is simple:
Free content is abundant. Verified progress is not.
What Wayfare does
A learner enters a topic such as:
- Photosynthesis
- Linear algebra
- Bicycle road safety
- Sourdough bread
- Ohm’s law
Wayfare then:
- Checks whether the topic is safe and appropriate.
- Generates a five-station learning route from beginner to advanced.
- Finds free videos, articles, and interactive resources for each station.
- Displays the route as a transit map with locked, active, and completed stations.
- Gives the learner a short comprehension quiz.
- Unlocks the next station when the learner passes.
- Diagnoses likely misconceptions when the learner fails.
- Provides a simpler explanation and an easier resource.
- Generates a different retry quiz.
- Opens the next learning tier when the route is completed.
The system verifies knowledge rather than attendance. A learner is not rewarded merely for opening a resource or waiting for a timer. They must demonstrate that they understand the station’s learning objectives.
How we built it
Wayfare was built with:
- Laravel 12 for the backend
- Livewire 4 for server-driven interactivity
- Alpine.js for lightweight client-side behavior
- Tailwind CSS for the interface
- SQLite for anonymous learner progress and cached data
- Groq-compatible language models for route generation, quizzes, safety classification, and remediation
- Tavily and Serper adapters for educational-resource discovery
- YouTube metadata enrichment for video titles, thumbnails, and durations
The application uses a provider-adapter architecture rather than directly coupling the product to one AI or search provider. If the primary provider fails, the application can move to another provider, exact cached data, or committed offline fixtures.
Two-stage route generation
The route is rendered in two stages.
First, Wayfare generates the five station titles and immediately displays the transit-map skeleton. Resource searches then run in parallel and fill the station cards afterward.
This prevents the learner from staring at a spinner while several external services respond.
Server-side quiz verification
Quiz answers are never trusted from the browser.
The browser receives only:
- Question identifiers
- Question text
- Shuffled answer options
Correct answers and explanations remain on the server. When the learner submits an answer, the server recomputes the result.
This prevents someone from changing a score in browser state or inspecting the page source to find the answer key.
Reliable progression
Experience points, station completion, and unlocking are handled transactionally.
A unique database constraint ensures that the same station cannot award completion XP twice. Even if two submissions arrive nearly simultaneously, the learner receives the reward only once.
All routes, stations, quizzes, attempts, and share cards are also resolved through the current learner’s ownership relationship. Requests for another learner’s data return a generic not-found response.
Anonymous by design
Wayfare does not require an account, email address, or password.
Each learner receives an anonymous identity stored through a signed first-party cookie. This allows progress to persist without collecting unnecessary personal information.
Design
The visual identity is based on a public-transit map.
A learning route is shown as a line containing five stations:
- Completed stations are filled.
- The current station is highlighted.
- Future stations remain visible but locked.
- Completing a tier creates an interchange into the next route.
We chose this metaphor because it communicates progression immediately. A learner can see where they are, where they have been, and what comes next.
We deliberately avoided presenting the experience as a conventional course dashboard or a list of generated links. The map is part of the product logic, not merely decoration.
Challenges we faced
Building reliable parallel search
One of the most important bugs was discovered through testing.
The original pooled-search implementation used the wrong object type when naming parallel HTTP requests. Every live search request threw a type error, but a broad exception handler silently converted the failure into an empty result.
Because Wayfare had working fixtures and fallbacks, the application still appeared to function correctly. With real API keys, however, every live search would have silently degraded to offline data.
We corrected the pool implementation and changed the error handling so unexpected search failures are logged instead of becoming indistinguishable from a legitimate “no results” response.
This demonstrated why graceful fallback must not become silent failure.
Preventing identity leakage
Another issue involved anonymous identity memoisation.
The identity service was container-scoped, which appeared safe during normal testing. However, under a long-running worker or any environment that reused the dependency container, a learner identity could potentially remain memoised across requests.
We changed the memoisation to be keyed to the active request object, preventing one request’s learner identity from carrying into another.
Protecting the answer key
Livewire makes server-driven interfaces convenient, but public component state can be inspected by the browser.
We therefore had to design the quiz flow so that correct answer indexes never entered Livewire’s public state. We also added a repository-level integrity scan that fails if correct_index appears anywhere inside client-facing resources.
Working without external services
The complete learning loop had to remain testable even when every API key was blank.
We created deterministic fixtures for the full photosynthesis route, including:
- Tier-one and tier-two route blueprints
- Search results
- Eight quiz questions per station
- Separate quiz forms
- Remediation content
This allowed us to test the full experience without relying on network availability, rate limits, or third-party service uptime.
What we learned
The largest lesson was that fallback systems can hide serious defects.
A fallback is useful only when the system can clearly distinguish:
[ \text{Expected provider failure} \neq \text{Programming error} ]
If both conditions silently return the same empty result, the application may appear reliable while its primary feature is completely broken.
We also learned that AI-generated educational content needs more than prompt engineering. Reliability depends on an entire chain of controls:
- Strict output schemas
- Server-side validation
- Explicit ownership checks
- Deterministic cache keys
- Retry isolation
- Provider timeouts
- Idempotent mutations
- Offline fixtures
- Automated integrity scans
The language model is only one component. The surrounding system determines whether the result is safe and dependable.
Accomplishments
The final application includes:
- A complete topic-to-route learning loop
- Safety classification and topic redirection
- Five-station progressive learning routes
- Parallel resource discovery
- Transit-map navigation
- Server-verified quizzes
- Separate initial and retry quiz forms
- Misconception diagnosis and remediation
- XP, levels, and station unlocking
- Multi-tier route generation
- Anonymous persistent progress
- Shareable route cards
- Provider fallback and offline fixtures
- Ownership enforcement across learner data
- Automated security and repository-integrity checks
The test suite contains 226 passing tests with 693 assertions.
A dedicated smoke command drives the complete flow through:
[ \text{topic} \rightarrow \text{safety gate} \rightarrow \text{route} \rightarrow \text{resources} \rightarrow \text{failed quiz} \rightarrow \text{remediation} \rightarrow \text{retry} \rightarrow \text{route completion} ]
The command then rolls back its changes, allowing it to be run repeatedly without corrupting learner progress.
What is next
The next step is expanding the reviewed offline fixture library across more academic, technical, creative, and practical topics.
Longer-term improvements include:
- A learner-facing question-reporting system
- Human review of generated routes
- Spaced-repetition quizzes after 7 and 30 days
- Signed and verifiable completion records
- Institutional dashboards for schools and training programmes
- Offline-first support for low-bandwidth environments
The goal is not to replace teachers, courses, or educational creators.
Wayfare provides the missing layer between free educational content and demonstrated learning:
A clear route, a meaningful checkpoint, and visible progress.
Built With
- education
Log in or sign up for Devpost to join the conversation.