DEV Community

Road Ready
Road Ready

Posted on

A Michigan CDL study app that shows its work

#pwa #webdev #javascript #testing

A Michigan-specific CDL study app where every one of 200 flashcards cites the exact page of the official manual it came from — and a test suite that refuses to ship a card without one.

Michigan CDL study resources vary widely in whether they identify a source for an answer. When a study prompt looks questionable, it should be possible to check it against the manual the state publishes — not simply memorize it because an app presented it.

That's the problem Road Ready is meant to solve. It is intentionally Michigan-only, and it makes the source for every answer visible. When an answer surprises you, you can check the exact state-manual passage instead of treating the app as the authority.

So I built the opposite. Road Ready is a Michigan-only CDL study app where every card carries a visible citation — manual section and PDF page — with a link that opens the official manual at exactly that page, before you even reveal the answer.

The rule: no citation, no card

The entire design comes from one constraint I set up front:

A fact, threshold, or procedure does not ship unless it's verified in the 2024 Michigan CDL Manual, and the card must display exactly where.

That sounds like a content policy. It's actually an architecture decision, because I enforced it in code rather than in discipline. Every card in the deck is data, and every card's source is mandatory:

{
  id: 'mi-wet-road',
  category: 'Driving safely',
  question: 'How should speed change on a wet road?',
  answer: 'Reduce speed by about one-third so you can stop in the same distance as on dry pavement.',
  source: {
    title: "'2024 Michigan Commercial Driver's License Manual',"
    section: '§2.6.2 — Matching speed to the road surface',
    pdfPage: 44,
    url: 'https://www.michigan.gov/sos/-/media/Project/Websites/sos/Resources/Forms-and-publications/CDL-Manual/cdlmanual.pdf?rev=08825e477ff24e4eb37707a159d4ff6d&hash=52E0C04A82CEBF44B410CAFF07EBCA4B#page=44',
  },
}
Enter fullscreen mode Exit fullscreen mode

Then the test suite makes it impossible to break the rule. This test runs on every build:

test('every flashcard cites the official Michigan CDL manual and a specific PDF page', () => {
  for (const card of CARDS) {
    assert.equal(card.source.title, '2024 Michigan Commercial Driver's License Manual');
    assert.ok(card.source.section.startsWith('§'));
    assert.ok(Number.isInteger(card.source.pdfPage) && card.source.pdfPage > 0);
    assert.equal(card.source.url, `${MICHIGAN_CDL_MANUAL}#page=${card.source.pdfPage}`);
  }
});
Enter fullscreen mode Exit fullscreen mode

If a card loses its section, its page, or its link, the build fails. Citations aren't a nice-to-have someone remembered to add — they're a test-enforced invariant.

The audit trail

I didn't want "trust me, I checked" to be the standard either, so the expanded deck went through a documented content audit. Each of the 140 audit records maps a card to its manual section, PDF page, and a short evidence excerpt — and that audit is itself under test:

test('each expanded-deck addition has a durable evidence audit record', async () => {
  const audit = JSON.parse(await readFile(new URL('../content-audit-2026-07-28.json', import.meta.url), 'utf8'));
  assert.equal(audit.cards.length, 140);
  for (const record of audit.cards) {
    const card = byId.get(record.id);
    assert.ok(card, `${record.id} is missing from the deck`);
    assert.equal(record.section, card.source.section);
    assert.equal(record.pdfPage, card.source.pdfPage);
    assert.ok(record.evidence.length > 0 && record.evidence.length <= 280);
  }
});
Enter fullscreen mode Exit fullscreen mode

The audit JSON ships in the repo. Anyone can diff a card against the passage it claims to come from.

Why citations change how you study

Here's the part I didn't fully anticipate: the citation isn't just a correctness guarantee, it's a better study mechanic.

When a card surprises you — say, "reduce speed by roughly one-third on a wet road" — a normal app asks you to just accept it. Road Ready lets you tap the source and read the actual paragraph it came from, in context, in the same document the Michigan Secretary of State draws exam questions from. A fact you were about to blindly memorize becomes a passage you've actually read. That sticks differently.

It also inverts the trust model. I'm not asking you to believe my answers are right. I'm showing you exactly where to check, and betting the whole app that the citation holds up. If you ever find a card that doesn't match the page it cites, that's a bug — and it's reportable, because there's a concrete claim to check.

The build is deliberately boring

No framework, no backend, no accounts. It's a static PWA:

  • Zero dependencies. Hand-rolled HTML/CSS/ES modules. The total JS is smaller than a single image.
  • Offline-first via a service worker; installable to the home screen like a native app.
  • Spaced repetition in ~15 lines. An "again" rating resets a card to a 10-minute interval; "got it" walks it up a [1, 3, 7, 14, 30]-day ladder: 
if (rating === 'again') {
  schedules[cardId] = { dueAt: now + (10 * 60 * 1000), repetitions: 0 };
} else {
  const repetitions = current.repetitions + 1;
  const intervalDays = [1, 3, 7, 14, 30][Math.min(repetitions - 1, 4)];
  schedules[cardId] = { dueAt: now + (intervalDays * 86400000), repetitions };
}
Enter fullscreen mode Exit fullscreen mode
  • Progress in localStorage — no account or backend required; study history stays in the browser.

The whole thing deploys as a static site. The most expensive part of the project was reading the manual, not writing the code.

What's next

It currently includes 200 cards across 10 Michigan CDL subjects: general knowledge, driving safely, air brakes, combination vehicles, cargo & inspection, tanker, hazmat, passenger, school bus, and doubles/triples. The Michigan-first structure means another state's deck would need to be built against that state's current manual with its own audit, rather than blending sources into a generic question bank.

If you or someone you know is going for a Michigan CDL, it's free, it's at cdl-flashcards.vercel.app, and it'll work offline in the DMV parking lot. And if a card doesn't match the page it cites — tell me. That's the point.

Road Ready is a free, independent study aid. All content is original study prompts paraphrased from and cited to the 2024 Michigan Commercial Driver's License Manual (Michigan Secretary of State).

Top comments (0)