A white-label platform that does the FMCSA compliance chasing

The problem

Every FMCSA-regulated trucking company has to keep a qualification file on every driver. It includes:

• the application
• a motor vehicle record (MVR) from every state the driver was licensed in
• safety performance history and the road test
• entry-level training and annual reviews
• a current medical certificate
• a complete drug and alcohol testing history

A single missing item is a violation.

Most carriers manage this with document lockers that send expiry alerts. The software flags that something is due, but the safety manager still has to chase the driver, book the physical, order the test and file the paperwork. Gaps usually surface when an investigator finds them, not before.

The rules are also changing. Medical certification is moving to electronic posting on state driving records, states are coming online at different times, and temporary FMCSA waivers apply in between. A static checklist can’t keep up.

The providers I built this for already sell drug testing and file management to carriers. They wanted to offer their clients a modern portal under their own brand, without building one themselves.

How I scoped it

I wrote the specification before any code. It ran to nine design documents covering the product, the regulations, the data model and security, plus an eight-stage build plan. Every stage had a written “done when” test.

The key decision was what had to be real at launch and what could run against stand-ins:

• Fully real: the driver file and driver outreach.
• Real workflows, mocked vendors: medical scheduling and drug testing. Medical examiners have no booking API, and no testing-administrator contract had been signed yet. Connecting a real vendor means writing one adapter, not redesigning anything.

I wrote down what V1 would not do (hours of service, vehicle maintenance, fuel tax and registration, intrastate rule variants) so the scope couldn’t creep. I also flagged a legal review of the rule catalog as required before the first paying customer.

The client set the scope by area, and I turned it into rules. The provider group named the parts of FMCSA driver compliance it wanted the portal to manage: driver qualification files, drug and alcohol testing, Clearinghouse reporting, physicals and the rest. My job was to turn those broad areas into a precise rule catalog and specification.

What I built

A rule engine that reads the regulations as data. Every requirement lives in a versioned catalog with:

• its CFR citation and effective date
• who it applies to
• how many are required (for example, one MVR per state licensed in the past three years)
• how its due date is calculated

The engine is deterministic: the same driver, rules and date always produce the same answer. When a fact is missing, it marks the item Unknown and routes it to a person. It never assumes a driver is compliant.

Obligations that never disappear. Each requirement becomes a dated obligation, stamped with the version of the rules that created it.

• Nothing is ever deleted. An item that stops applying is marked Not Applicable, so the history holds up in an audit.
• Waivers need a named approver.
• A nightly sweep touches only the drivers with something due.
• When the rules change, a backfill job re-checks every driver.

Records an auditor can trust.

• Documents are immutable and fingerprinted with SHA-256, with a chain showing what replaced what.
• Audit and event logs are append-only.
• Driver consent is its own record, and the system won’t order an MVR or drug test without it.

Outreach that does the chasing.

• Drivers get text reminders on a schedule that respects quiet hours in their own time zone, honors STOP requests, and never sends the same reminder twice in a day. Time-critical tests override quiet hours.
• Every text carries a signed, expiring link to a driver portal. There’s no password to forget, and drivers sign consent forms right there.

Medical and drug-testing workflows.

• A resolver handles the medical-certificate transition state by state, including waiver windows.
• Physicals move through a scheduling workflow that re-pulls the driving record afterward and escalates at day 30.
• The random drug-test draw can be re-run from its stored seed and roster to reproduce exactly the same selection, which proves it wasn’t tampered with.
• A manager releases selections to drivers, and results arrive only after medical review.
• After a positive or refused test, each step requires a named person and a note: removal from duty, the Clearinghouse report and the substance abuse professional (SAP) referral.

A dashboard built around the safety manager’s day. It opens on everything due in the next 45 days. It also has driver detail, waivers, and an audit export that lists gaps explicitly instead of hiding them.

1. People

   • Safety managersDashboard: everything due in 45 days
   • DriversText message → token-gated portal, no password
   HTTPS · signed, expiring links
2. App

   • Next.js appSafety-manager dashboard and driver portal
   REST API
3. Services

   • Rails APIObligations, notifications, scheduling, testing, random pool
   • Rule engineVersioned catalog with CFR citations
   Row-level security per tenant
4. Data & vendors

   • PostgreSQLAppend-only audit and event logs
   • Vendor adaptersSMS, MVR, medical directory, drug testing

Tenant isolation is enforced in the database. Each provider and carrier sees only its own data. PostgreSQL row-level security enforces it in the database itself, not just in application code. No client data is used in development: every test driver and record is invented.

How I built it: I wrote the specification, the rule catalog and the architecture myself, then built against them one tested stage at a time.

Result

• Covers the driver qualification file (49 CFR Part 391), medical certification, and drug and alcohol testing (Parts 382 and 40)
• 383 automated tests passing: 288 unit and rule-engine tests, plus 95 security and integration tests
• Handed off to the provider group, which is taking it to market and maintaining it with its own development team
• Next phase requested: the provider group asked for an AI layer that completes compliance tasks on its own, such as calling a driver to schedule a drug test

What’s next: production staff sign-in, scheduled background jobs, a PDF auditor pack, live vendor integrations, and the AI task layer.

Lessons

Keep the spec and the code in lockstep. The spec said a changed due-date rule should create a new obligation. The code updated the date in place and relied on the audit log instead. Both approaches work, but an auditor or a new engineer should find one answer, not two. Now a design decision and its doc update land in the same commit.

Test with a realistic fleet from day one. Obligation IDs were unique only within a single driver, until a multi-driver test exposed collisions. Test data shaped like a real fleet would have caught that sooner.