Direct File is a free federal tax filing service from the United States Government that allows taxpayers to electronically file their returns directly with the Internal Revenue Service.
The service addresses the complexity of tax filing by translating the Internal Revenue Code into plain language interview questions that taxpayers can answer without external guidance. It converts these answers into standard tax forms and transmits them to the IRS's Modernized e-File API. The tool is designed to work equally well on mobile and desktop devices and is available in English and Spanish. At its core, Direct File uses the Fact Graph, a declarative XML-based knowledge graph written in Scala that reasons about incomplete information. This knowledge graph runs on the backend JVM and is transpiled to JavaScript for client-side execution. The Fact Graph is domain-agnostic and may serve as a reference for other revenue agencies and business rules engine implementations. Direct File also enables taxpayers to export their federal return data to third-party tools for state and local filing through a State API that provides both standard MeF XML and enriched JSON formats.
Developers considering this codebase should understand that the repository has been archived and is no longer maintained. The code is provided for historical reference only and should not be used in production systems. It may contain unpatched or unknown vulnerabilities. However, the tax logic developed in collaboration with the IRS Office of Chief Counsel, along with associated test cases and scenarios, may be valuable for others building products that need to accurately interpret United States tax law. The Fact Graph implementation and State API design could serve as useful references for similar projects in the tax or revenue domain.
The project was developed by an in-house IRS team with support from USDS and GSA, alongside vendor partners. Development involved close collaboration with the IRS Office of Chief Counsel to ensure accurate interpretation of tax law. The codebase combines JavaScript for the frontend with Scala for the knowledge graph engine, demonstrating a cross-language approach to handling both user interaction and complex business logic. The project's scope extended to designing interoperability mechanisms with state revenue agencies through the State API.
