US IRS free online tax filing open source repo

The United States Internal Revenue Service published the source code repository for Direct File, an interview-based web application that allows taxpayers to electronically file federal tax returns directly with the government for free. According to github.com's report, the public archive contains the core service codebase, interview logic, and reasoning engine deployed for Tax Year 2024. The software was engineered by in-house agency technologists alongside private contractors to eliminate third-party filing costs.

This technical report covers the system architecture, the underlying reasoning engine, cross-agency development partners, and statutory open-source mandates governing the release. Software engineers, civic technologists, and revenue specialists can examine the codebase to understand how federal tax statutes translate into functional client-server applications. The project demonstrates how federal agencies build responsive web services across desktop and mobile devices without requiring citizens to interpret tax publications.

01Plain language interviews and legal logic

Direct File processes tax filings by converting Title 26 of the United States Code into plain-language interview questions that filers answer directly. The IRS Office of Chief Counsel collaborated with technical teams to construct questions that individuals can complete using standard personal records without external publications. This legal partnership generated extensive test scenarios and validation fixtures calibrated to federal tax law for Tax Year 2024.

After a taxpayer completes the interview, the software translates those answers into standard tax forms and schedules. The system then transmits the formatted filing to the Modernized e-File application programming interface, the standard IRS channel available for authorized public transmissions. This processing pipeline ensures accurate document generation while insulating users from complex tax schedules.

The user interface supports both English and Spanish across smartphones, tablets, laptops, and desktop computers. Designers built the responsive interface to serve filers with diverse aptitudes, attitudes, and accessibility requirements. The published question logic and verification cases provide a concrete baseline for civic applications interpreting United States tax statutes.

02Fact Graph architecture and Scala engine

At the center of Direct File is the Fact Graph, a declarative, XML-based knowledge graph data structure built to evaluate incomplete information. The engine reasons through partially completed returns to determine what legal inputs remain necessary before a return can be submitted. This data structure allows the system to recalculate tax liabilities dynamically as taxpayers provide additional details.

Engineers wrote the Fact Graph in the Scala programming language to leverage its type safety and functional characteristics. On server backends, the engine runs on the Java Virtual Machine to process return data and manage execution state. The team also transpiled the Scala codebase using Scala.js, allowing the exact same reasoning logic to run client-side in the browser.

Because the Fact Graph operates as a non-domain-specific knowledge graph, its application extends beyond federal tax processing. External revenue agencies and software architects can study the design as a production reference for general business rules engines. The implementation demonstrates how declarative rules can evaluate complex dependency graphs across both client and server runtimes.

03State API integration and data transfer

While Direct File handles federal tax submissions, United States taxpayers must also satisfy distinct state and local tax obligations. To prevent redundant data entry, Direct File enables filers to optionally transfer their completed federal information to third-party state filing tools. This optional import workflow bridges the administrative divide between federal and municipal revenue departments.

The integration relies on a dedicated State API that packages and transfers tax records in two concurrent representations. The endpoint transmits standard Modernized e-File XML alongside an enriched JSON structure containing supplementary data elements requested by state agencies. These enriched elements help participating state tax departments streamline the localized filing experience.

This dual-format data transfer eliminates the need for taxpayers to reenter duplicate personal and wage data into state tax portals. By supplying standardized API payloads, the architecture fosters intergovernmental cooperation while preserving taxpayer choice in selecting state software tools. The mechanism illustrates how federal digital platforms can interoperate with municipal systems without requiring a single centralized tax platform.

04Cross-agency teams and contractor support

An in-house engineering team within the Internal Revenue Service managed the primary development of the Direct File platform. Rather than delegating complete execution to an external vendor, the IRS coordinated a blended, cross-agency engineering initiative. The effort received dedicated operational support from both the United States Digital Service and the General Services Administration.

Commercial technical contractors worked embedded alongside government technologists to provide engineering and product delivery capacity. Specialized vendor teams from TrussWorks, Coforma, and ATI contributed software development and design expertise throughout the project lifecycle. This collaborative model combined private engineering practices with agency civil servants and statutory tax counsel.

Historical background detailing the development milestones and operational rollout is documented in IRS Publication 5969 and official agency portals. The blended structure enabled the agency to maintain direct technical ownership of core components while rapidly scaling technical staff. This deployment framework offers a practical blueprint for future in-house civic software engineering across federal departments.

05Repository archival and public code exemptions

The GitHub repository is officially archived and no longer receives active maintenance or software updates from government developers. The IRS noted that the archived code is provided strictly for historical reference and may contain unpatched security vulnerabilities. Consequently, the agency advised that the codebase should not be deployed in operational production environments.

Federal disclosure policies required engineers to redact sensitive operational components prior to public publication. The repository omits Personally Identifiable Information, Federal Tax Information, and Sensitive But Unclassified records.

Additionally, code developed for National Security Systems under 40 U.S.C. Section 11103 was excluded or rewritten to maintain security standards.

The public code release aligns with federal open-source legislation, led by the SHARE Act of 2024, Public Law 118-187. The initiative also satisfies OMB Memorandum M-16-21, FAR Part 27, FITARA mandates from 2014, the E-Government Act of 2002, and the Clinger-Cohen Act of 1996. These statutes require federal agencies to publish custom-developed software to maximize transparency and encourage interagency code reuse.