In a rare but powerful move, the U.S. government has open-sourced one of its most impactful digital public services: Direct File, a platform that allows taxpayers to file their federal returns electronically—completely free of charge and without third-party intermediaries.
At a glance, Direct File might seem like just another government web form. But beneath the surface lies a thoughtfully engineered system that’s not just about taxes—it’s a case study in modern government software, scalable infrastructure, and user-first design.
Let’s break it down.
🧾 What is Direct File?
Direct File is a web-based, interview-style application that guides users through the federal tax filing process. It works seamlessly across devices—mobile, desktop, tablet—and is available in both English and Spanish.
Built to accommodate taxpayers with a wide range of needs, it translates the complexity of IRS tax code into plain-language questions. On the backend, it connects with the IRS’s Modernized e-File (MeF) system via API to handle real-time tax return submissions.
🧠 The Tech Stack: Government Goes Modern
The project reflects a significant leap forward in how federal systems are built and deployed.
- Fact Graph: At the heart of Direct File is a “Fact Graph”—an XML-based knowledge graph that smartly handles incomplete or evolving user information during the filing process.
- Programming Stack:
- Scala for the logic and backend (running on the JVM)
- Transpiled to JavaScript for client-side execution
- React frontend in the df-client directory
- Containerized for Speed: Docker is used for seamless local deployment.
- This spins up the backend (port 8080) and Postgres DB (port 5432).
- Modular Architecture:
- fact-graph-scala: Core tax logic
- js-factgraph-scala: Frontend port
- backend: Auth, session management
- submit: MeF submission engine
- status: Monitors submission acknowledgments
- state-api: Bridges federal and state systems
- email-service: Handles user notifications
🤝 Built by Public Servants, Not Contractors Alone
Unlike many large-scale federal tech initiatives, Direct File was created in-house at the IRS, in partnership with:
- U.S. Digital Service (USDS)
- General Services Administration (GSA)
- Contractors like TrussWorks, Coforma, and ATI
This hybrid structure ensured agile execution while maintaining strong public stewardship.
🔒 Security Without Obscurity
Despite being open source, Direct File excludes any code that touches:
- Personally Identifiable Information (PII)
- Federal Tax Information (FTI)
- Sensitive But Unclassified (SBU) data
- National Security Systems (NSS) code
This reflects a disciplined balance between transparency and trust—one that more government software projects should emulate.
📜 Legal Framework
Direct File is anchored in a suite of progressive digital policies:
- Source Code Harmonization And Reuse in IT Act of 2024
- Federal Source Code Policy
- Digital Government Strategy
- E-Government Act of 2002
- Clinger-Cohen Act of 1996
Together, these policies mandate that custom-developed government software should be shared and reused, not siloed.
💡 Why This Matters
Direct File represents a milestone for civic tech, open government, and digital service delivery:
✅ 1. Open Source, Real Impact
It’s not often we see real, working government platforms open to inspection and reuse. This invites contributions from civic technologists and helps other governments learn from U.S. innovation.
🧩 2. Designing for Complexity
Converting complex tax logic into user-friendly language—using a structured knowledge graph—is a pattern applicable well beyond taxes (think healthcare, benefits, or housing).
🛠️ 3. Engineering Innovation
The Fact Graph and modular backend architecture reflect best practices in modern backend design—resilient, flexible, and portable.
🔐 4. Trust and Privacy by Design
The selective code release shows how governments can be open while still securing sensitive systems.
🌐 5. Interoperability with State Systems
The state-api integration is especially forward-thinking. It could pave the way for smoother federal–state collaboration in everything from benefits to compliance.
🚀 Getting Started with the Code
Want to explore it locally? You’ll need:
- Java
- Scala
- Maven
- SBT
- Coursier
- Docker
Then: 1. Clone the repo
2. Run:
docker compose up -d --build
3. Navigate to /direct-file/df-client
4. Run:
Frontend runs at http://localhost:3000
Final Thoughts
Direct File shows that government software doesn’t have to be clunky, slow, or hidden. With the right talent and commitment, it can be modern, secure, and open.
This project is not just about taxes—it’s about showing the public sector what’s possible when we build with purpose and publish with pride.
📎 Explore the repo (once public): github.com/irs-directfile
📩 Want to build something similar? Contact me