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

> Contribute to TaxHacker an open-source AI accountant. Submit pull requests for features, bug fixes, AI prompts, and docs. Welcome to the Next.js, Prisma, PostgreSQL project.

- Repository: [Vasily Zubarev/TaxHacker](https://github.com/vas3k/TaxHacker)
- Tags: how-to-guide
- Published: 2026-04-01

---

**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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/lib/auth.ts) to support JWT-based sessions and email-OTP login flows. The central database client is exported from [`lib/db.ts`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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:

```typescript
// 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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/lib/auth.ts)** — Configures `better-auth` with email OTP, JWT sessions, and self-hosted mode settings.
- **[`lib/db.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/db.ts)** — Exports the singleton Prisma client instance used throughout the application.
- **[`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts)** — Wraps OpenAI, Google Gemini, and Mistral API clients with LangChain abstractions.
- **[`ai/prompt.ts`](https://github.com/vas3k/TaxHacker/blob/main/ai/prompt.ts)** — Stores the default system prompts sent to LLMs during document extraction.
- **[`app/page.tsx`](https://github.com/vas3k/TaxHacker/blob/main/app/page.tsx)** — The main landing page component demonstrating server-side rendering patterns.
- **`Dockerfile`** and **[`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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`](https://github.com/vas3k/TaxHacker/blob/main/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.