Questline

Questline turns a large AI Engineering roadmap into a daily progression loop: small quests, clear time estimates, curated resources, XP, ranks, streaks, and a light RPG-inspired “System” interface. Instead of asking learners to plan an entire curriculum up front, Questline schedules the next right thing based on capacity and progress.

At a glance

• Role: Product builder and full-stack engineer across product strategy, curriculum design, scheduling logic, API, database, AI integration, and UI.
• Scope: AI Engineer track, onboarding, deterministic study scheduler, daily quest screen, roadmap map, profile/history, XP, streaks, adaptive re-pacing, quizzes, retention metrics, and serverless deployment.
• Stack: React, Vite, Tailwind, TanStack Query, Cloudflare Workers, Hono, D1, Drizzle ORM, better-auth, KV, Workflows, Workers AI, AI Gateway, Zod, TypeScript, Vitest.
• Status: MVP Phases 0–3 implemented: walking skeleton, intelligence layer, and portfolio-ready polish.
• Proof: 16-task implementation plan completed, 31 domain tests passing, typecheck passing, production build passing, and a curated AI Engineer track seeded into D1.

The problem

Learning AI Engineering is not just a content problem. There are already too many courses, playlists, and roadmaps. The harder part is turning that material into a realistic sequence that someone can actually follow while managing time, energy, and missed days.

The target learner hits a few common problems:

• Roadmaps are too large to act on. Topics like RAG, agents, evals, prompt optimization, and deployment are useful, but a big checklist does not answer “what should I do today?”
• Pacing breaks quickly. A missed day often creates an impossible backlog, which makes learners abandon the plan instead of re-entering gently.
• AI can hallucinate curriculum. Letting a model invent prerequisites, estimates, or learning paths makes the experience feel magical but unreliable.
• Motivation needs a loop. Learning apps often track completion, but they do not make the daily habit feel rewarding enough to return on day two, day seven, and day thirty.

The goal: a focused AI Engineering learning app that combines a trusted curated roadmap with an adaptive quest loop learners can actually maintain.

The solution

Questline is a daily learning companion for the AI Engineer / LLM apps niche. The curriculum is hand-curated; the scheduling math is deterministic; and AI is used only to make trusted content feel more personal and alive.

• Onboarding & placement — learners choose the AI Engineer track, enter weekly capacity, preferred study days, session length, and an optional target finish date. Placement can skip known material without changing the trusted curriculum graph.
• Deterministic quest scheduling — a pure TypeScript scheduler topologically sorts the remaining roadmap, respects prerequisites, compares effort against capacity, splits large nodes into slices, merges small items, and generates dated daily quests.
• Today screen — the main retention surface shows a single quest, time estimate, resources, micro-task checklist, completion action, and optional knowledge check.
• Adaptive re-pacing — when the learner falls behind, Questline re-plans forward from today instead of creating a punitive backlog. Missed days can become smaller catch-up quests, never extra workload as punishment.
• Roadmap and profile — learners can see the DAG as done/current/locked, plus projected finish, XP, rank, streaks, freeze tokens, and completion history.
• System theme — a toggleable dark, glowing status-window interface gives the app a stronger identity while keeping the underlying mechanics usable without the RPG skin.

Technical overview

Questline is built as a Cloudflare-native full-stack app: a React frontend and Hono API deployed through the Cloudflare Workers platform, backed by D1 and Drizzle.

Frontend — React 19 + Vite + Tailwind v4 in TypeScript, with TanStack Query for server state and React Router for app navigation. The client includes sign in, onboarding, Today, roadmap map, profile/history, theme handling, and a knowledge-check component.

API — Hono routes expose the product loop: tracks, enrollment, current user, today’s quest, quest completion, plan view, manual re-pacing, quizzes, profile, and metrics. Shared Zod schemas keep request and response contracts typed across client and server.

Data layer — Cloudflare D1 stores tracks, nodes, prerequisite edges, resources, enrollments, plans, quests, quest slices, tasks, XP ledger, streaks, metrics, and better-auth tables. Drizzle defines the schema and migrations, and a seed script emits the curated AI Engineer track into SQL.

Domain layer — scheduling, topological sorting, date handling, streaks, progression, and framing helpers live in src/domain with no Workers-specific dependencies. This keeps the core learning logic testable and protects the app from platform coupling.

AI layer — Workers AI is routed through AI Gateway when configured, giving a single path for caching, retries, fallback, and spend control. If no gateway is available, Questline falls back to deterministic templates so the core loop still works locally.

Durable learning pipeline — Cloudflare Workflows model one long-running journey per enrollment. The workflow can compute schedules, sleep until study days, generate quest framing, wait for completion events, and re-pace when a day is missed.

Key decisions

• Curated curriculum first — the AI Engineer roadmap is hand-authored and seeded as trusted data. The model may package or quiz the content, but it does not invent the curriculum.
• The LLM never does scheduling math — ordering, capacity reconciliation, slicing, merging, projected finish, and infeasible-deadline handling are all deterministic TypeScript, covered by unit tests.
• Gentle re-entry over punishment — missed days trigger forward-looking re-pacing and smaller catch-up quests, not shame, impossible backlogs, or larger penalties.
• Per-request auth on Workers — better-auth is created through a per-request factory instead of a module-level singleton, avoiding a known Workers runtime failure mode.
• Narrow beachhead — Questline deliberately starts with AI Engineer / LLM apps instead of becoming a generic “learn anything” app before the retention loop is proven.

Status

The MVP is implemented through Phase 3: scaffold, schema, curated content, authentication, scheduler, API routes, onboarding, Today, AI-assisted framing, quizzes, adaptive re-pacing, Workflows pipeline, roadmap UI, profile/history, System theme, and retention instrumentation.

Current verification is green: project-wide typecheck passes, the production build passes, and the domain layer has 31 passing Vitest tests across scheduling, topological sorting, dates, streaks, and progression.

Deferred Phase 4 work includes additional tracks, AI-generated roadmap support, Vectorize / AI Search grounding, richer recommendations, and broader marketplace features once the focused AI Engineer loop is validated.