The IRS Open-Sourced Its Tax Filing Engine, and the Interesting Part Isn't the Tax Forms
You've probably heard that the IRS built its own free tax filing service. What you might not know is that they published the source code—including the engine that interprets the tax code—and it's sitting on GitHub right now. It's called Direct File, and even if you never touch a 1040 in your life, there's something in here worth understanding.
What It Does
Direct File is the service that lets taxpayers file their federal return for free, directly with the IRS, through a plain-language interview that works as well on a phone as on a desktop. It's available in English and Spanish, and it's designed for accessibility across a range of abilities and access needs. The core idea: take the Internal Revenue Code and turn it into questions whose answers taxpayers should already know, without needing outside instructions.
Under the hood, the interesting piece is the Fact Graph—a declarative, XML-based knowledge graph designed to reason about incomplete information, like a partially finished tax return. It's written in Scala, runs on the JVM on the backend, and gets transpiled via Scala.js so it runs on the client too. The README is explicit that the Fact Graph isn't domain-specific, which makes it interesting well beyond taxes. Answers from the interview get translated into standard tax forms and transmitted to the IRS's Modernized e-File API. There's also a State API that hands federal return data—both standard MeF XML and an enriched JSON format—to third-party tools for state and local filing, so taxpayers don't re-enter everything. The questions and logic were developed in close collaboration with the IRS Office of Chief Counsel, and the repo includes test cases and scenarios that may be useful to anyone building products that need to interpret US tax law as of Tax Year 2024.
Why It's Cool
-
The Fact Graph is the real prize. A declarative graph that can reason about incomplete data is a genuinely useful pattern. The README pitches it as a reference for business rules engine implementations and as potentially useful to revenue agencies—but any system that has to make decisions from partial information (eligibility checks, benefits screening, compliance workflows) faces the same problem.
-
The same logic runs on both ends. Because the Fact Graph is transpiled with Scala.js, the reasoning engine works on the server and in the browser. That's a clean architecture decision, not a marketing bullet.
-
The tax logic itself is documented and tested. The questions, logic, and associated scenarios came out of collaboration with the Office of Chief Counsel. Even if you're not building a tax product, seeing how a government codifies statutory language into testable rules is instructive.
-
The State API solves a real annoyance. Filing federal is only half the job; the enriched JSON format exists specifically because state agencies said certain data elements would streamline their side of things. That's a thoughtful bit of interop design.
-
It's honest about what's missing. The README states plainly that code and data considered PII, Federal Tax Information, Sensitive But Unclassified, or developed for National Security Systems is exempt, and that some functionality has been removed or rewritten as a result. You won't get a complete system, but you'll know that going in.
How to Try It
First, set expectations: the repository has been archived and is no longer maintained. The code is there for historical reference and may contain unpatched or unknown vulnerabilities—the README says explicitly not to use it in production.
With that in mind:
- Head to the repo at github.com/irs-public/direct-file.
- Read
ONBOARDING.md—the README points there if you want to jump into running Direct File locally. - Skim the Fact Graph code if you're interested in the rules engine, and the test cases and scenarios if you want to see how tax logic gets expressed.
- Treat everything as a reference implementation, not a dependency.
Final Thoughts
This isn't a library you'll npm install and ship. It's an archived snapshot of a government service, with portions deliberately withheld, and it comes with an explicit warning against production use. The audience is narrower than most open source releases: developers building tax or benefits products, people designing business rules engines, and anyone curious about how a large public-facing service gets architected in Scala. If you fall into one of those groups, the Fact Graph alone is worth an afternoon. If you don't, it's still a rare look at how the government writes software—and that's not something you get to read very often.