Can I Contribute to TaxHacker? A Complete Guide to the Open-Source AI Accountant

Yes, TaxHacker actively accepts contributions and welcomes pull requests for bug fixes, features, AI prompts, and documentation across its Next.js 15+, Prisma, and PostgreSQL architecture.

TaxHacker is a self-hosted AI accountant created by vas3k that automates financial document processing using modern web technologies and large language models. If you are asking "Can I contribute to the TaxHacker project?", the answer is definitively yes—the repository is open-source and actively maintained on GitHub with clear contribution guidelines. Understanding the project's stack and directory structure will position you to submit high-quality code that gets merged quickly.

Understanding TaxHacker's Architecture

TaxHacker follows a modern full-stack TypeScript architecture designed for self-hosting. The codebase separates concerns between the Next.js application layer, Prisma database abstraction, and specialized AI utilities.

Web Framework and Frontend

The application runs on Next.js 15+ with React 19, utilizing the App Router pattern where pages live in app/ and API routes are colocated with their respective folders. The frontend styling relies on TailwindCSS and Radix UI components, with components/unsorted/analyze-form.tsx handling the document upload interface. Notifications use the Sonner library for toast messages.

Database and Authentication

PostgreSQL serves as the primary datastore, accessed through Prisma (@prisma/client) with type-safe queries defined in prisma/schema.prisma. Authentication is handled by better-auth with a Prisma adapter, configured in lib/auth.ts to support JWT-based sessions and email-OTP login flows. The central database client is exported from lib/db.ts and imported across the application.

AI and File Processing

Document extraction leverages LangChain wrappers for multiple providers including OpenAI, Google Gemini, and Mistral, centralized in lib/llm-providers.ts. The system sends document images and PDFs to these LLMs, parsing structured responses into database fields. File handling utilities in lib/uploads.ts use Sharp for image thumbnails and pdf2pic for PDF preview generation.

5 High-Impact Ways to Contribute

Whether you specialize in backend API development, AI prompt engineering, or UI design, TaxHacker offers specific contribution paths that match your expertise.

Bug Fixes

Search the Issues tab for UI glitches or API errors. Typical fixes involve updating React components in the components/ directory or adjusting Prisma queries in API routes. Even minor typo corrections in transaction filters improve the user experience.

Feature Development

New functionality requires adding API routes under app/api/.../route.ts or creating React components in the components/ folder. Popular feature requests include bulk operations for transactions, enhanced export formats, and new dashboard visualizations.

AI Prompt Enhancements

The extraction logic depends on prompt templates stored in ai/prompt.ts. You can improve extraction accuracy by refining field-specific prompts or adding support for new document types. This requires testing against actual LLM outputs to maintain parsing reliability.

Documentation Improvements

The README.md contains deployment instructions, but gaps exist for advanced self-hosting scenarios and API documentation. Screenshots, troubleshooting guides, and environment variable explanations are valuable additions.

Testing and Type Safety

Add unit tests under __tests__/ using Jest, or tighten Zod schema definitions in models/*.ts to prevent runtime errors. The export_and_import module particularly lacks comprehensive test coverage.

Step-by-Step TaxHacker Contribution Workflow

Follow this exact sequence to ensure your pull request meets repository standards:

1. Fork the repository on GitHub to your personal account.
2. Clone your fork locally using git clone.
3. Create a feature branch with git checkout -b my-feature-name.
4. Install dependencies by running npm install.
5. Run database migrations with npx prisma migrate dev to set up local PostgreSQL tables.
6. Start the development server using npm run dev to verify the application loads.
7. Make your changes and verify functionality locally.
8. Run the test suite with npm test where available, ensuring no regressions.
9. Commit with clear conventional messages and push to your fork.
10. Open a Pull Request against the main branch with a detailed description.

The repository includes a dedicated "🤝 Contributing" section in the README that provides additional context on coding standards and review processes.

Practical Example: Adding a New API Endpoint

Below is a production-ready example demonstrating TaxHacker's patterns for authentication and database access. This code adds a GET /api/projects endpoint that returns projects for the authenticated user:

// File: app/api/projects/route.ts
import { NextResponse } from 'next/server'
import { auth } from '@/lib/auth'
import { prisma } from '@/lib/db'
import { headers } from 'next/headers'

export async function GET() {
  // Ensure the request is authenticated via better-auth
  const session = await auth.api.getSession({ headers: await headers() })
  if (!session?.user?.id) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  // Query Prisma for user-specific projects
  const projects = await prisma.project.findMany({
    where: { userId: session.user.id },
    orderBy: { createdAt: 'desc' },
  })

  return NextResponse.json(projects)
}

This example follows TaxHacker's architectural conventions: it uses better-auth for session validation via auth.api.getSession, accesses PostgreSQL through the centralized Prisma client in lib/db.ts, and follows Next.js 15+ App Router patterns for API route definition. You can reference similar implementations in app/api/transactions/route.ts for additional context.

Essential Files Every Contributor Should Know

Familiarize yourself with these specific files before contributing to understand the codebase structure:

• package.json — Declares runtime dependencies including Next.js 15+, Prisma, LangChain, and better-auth.
• prisma/schema.prisma — Contains database schema definitions for transactions, users, projects, and document metadata.
• lib/auth.ts — Configures better-auth with email OTP, JWT sessions, and self-hosted mode settings.
• lib/db.ts — Exports the singleton Prisma client instance used throughout the application.
• lib/llm-providers.ts — Wraps OpenAI, Google Gemini, and Mistral API clients with LangChain abstractions.
• ai/prompt.ts — Stores the default system prompts sent to LLMs during document extraction.
• app/page.tsx — The main landing page component demonstrating server-side rendering patterns.
• Dockerfile and docker-compose.yml — Containerization configs for self-hosted deployments.

Summary

• TaxHacker welcomes contributions across bug fixes, features, AI prompts, documentation, and testing.
• The stack consists of Next.js 15+, React 19, Prisma/PostgreSQL, better-auth, and LangChain-based AI processing.
• Key directories include app/ for routes, lib/ for utilities, prisma/ for schema, and ai/ for LLM prompts.
• Contribution workflow follows standard GitHub fork-and-PR practices with Prisma migrations required for database changes.
• Code standards require type-safe TypeScript, proper authentication checks via auth.api.getSession, and database access through the centralized Prisma client.

Frequently Asked Questions

Do I need machine learning experience to contribute to TaxHacker?

No, you can contribute effectively without ML expertise. While the project uses LangChain and LLMs for document extraction, most contributions involve standard TypeScript/React development in Next.js API routes or frontend components. AI prompt improvements are accessible to anyone willing to test different prompt phrasings against document samples.

What development environment is required to run TaxHacker locally?

You need Node.js (version matching package.json engines), npm, and a local PostgreSQL instance. The project uses standard Next.js 15+ tooling—run npm install, npx prisma migrate dev to initialize the database, and npm run dev to start the development server. Docker support via docker-compose.yml is also available for containerized development.

How does TaxHacker handle authentication in local development?

The project uses better-auth with email-OTP login configured in lib/auth.ts. In development, you can generate test sessions without external OAuth providers by using the email OTP flow. The auth.api.getSession method validates JWT tokens automatically, allowing you to test authenticated routes locally without production credentials.

Can I contribute to TaxHacker if I only want to improve documentation?

Yes, documentation contributions are highly valued. The README.md currently covers basic deployment, but needs expansion for troubleshooting, environment variable explanations, and advanced self-hosting configurations. Clear documentation helps grow the self-hosted user community and reduces support burden on maintainers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}