How to Get Started with TaxHacker for Tax Calculation: Complete Setup Guide

Deploy TaxHacker locally using Docker Compose to automatically extract receipt data with AI and generate tax-ready CSV exports.

TaxHacker is a self-hosted AI-powered accounting application built with Next.js 15+, Prisma, and PostgreSQL. It enables automated extraction of financial data from receipts and invoices using configurable LLM providers, storing structured transaction data for tax filing purposes. This guide covers the complete installation and configuration process based on the source code in vas3k/TaxHacker.

Prerequisites and Architecture

TaxHacker requires Docker and Docker Compose for the recommended deployment path. The application architecture consists of a Next.js frontend and API routes (app/page.tsx), a Prisma ORM layer for database management, and PostgreSQL for persistent storage of transactions, files, and user settings.

The system supports multiple AI providers for document processing, configured in lib/llm-providers.ts, including OpenAI, Google Gemini, Mistral, and any OpenAI-compatible endpoint. File uploads are handled via lib/uploads.ts and stored in the path defined by the UPLOAD_PATH environment variable.

Installation and Configuration

Clone the Repository

Start by cloning the TaxHacker repository to your local machine:

git clone https://github.com/vas3k/TaxHacker.git
cd TaxHacker

Configure Environment Variables

Copy the example environment file and edit the required variables:

cp .env.example .env

Open .env and configure the following critical settings:

• Set a strong authentication secret: Define BETTER_AUTH_SECRET with at least 16 characters to secure user sessions.
• Configure the database: Use DATABASE_URL="postgres://postgres:postgres@postgres:5432/taxhacker" for the Docker Compose setup, or point to your existing PostgreSQL instance.
• Add AI provider API keys: Include at least one of OPENAI_API_KEY, GOOGLE_API_KEY, or MISTRAL_API_KEY to enable receipt extraction.
• Enable self-hosted mode: Set SELF_HOSTED_MODE=true to disable public signup and enable automatic admin login.

The central configuration logic resides in lib/config.ts, which validates these environment variables at runtime and toggles features like self-hosted authentication.

Running the Application

Execute the Docker Compose stack to start both the application and PostgreSQL database:

docker compose up -d

This command launches two containers as defined in docker-compose.yml: the Next.js application and the PostgreSQL service. The app container automatically runs Prisma migrations on startup (prisma migrate dev) to initialize the database schema defined in prisma/schema.prisma.

For local development without Docker, install dependencies and run the database migrations manually:

npm install
npx prisma generate && npx prisma migrate dev
npm run dev

Navigate to http://localhost:7331 to access the UI. With SELF_HOSTED_MODE enabled, the system automatically logs you in as the first admin user.

Processing Receipts and Invoices

Upload and AI Extraction

To begin tax calculation preparation, click the Upload button in the interface and drag-and-drop an image or PDF receipt. The backend stores files in the ./data/uploads directory (configurable via UPLOAD_PATH) and processes them through the selected LLM provider.

The extraction pipeline, implemented in the document processing layer, automatically identifies key financial fields including name, merchant, total, currencyCode, and issuedAt. These fields map to the Transaction model in models/transactions.ts, which splits standard fields from user-defined custom fields before persisting to PostgreSQL.

Programmatic Transaction Creation

You can also create transactions via the REST API for bulk import scenarios:

const createTransaction = async (data: TransactionData) => {
  const resp = await fetch('/api/transactions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: "Office Supplies",
      merchant: "Staples",
      total: 129.99,
      currencyCode: "USD",
      issuedAt: new Date().toISOString(),
      files: ["file-id-123"]
    }),
  });
  if (!resp.ok) throw new Error('Failed to create');
  return await resp.json();
};

The server-side implementation delegates to the createTransaction function in models/transactions.ts, which handles the Prisma database insertion and links uploaded files to transaction records.

Exporting Data for Tax Filing

Once transactions are captured, use the Export button to download CSV or Excel files containing all selected columns, custom fields, and original document attachment links. The export logic in lib/export_and_import.ts respects your filtering criteria and includes multi-currency conversion data essential for accurate tax calculation.

Summary

• TaxHacker is a self-hosted Next.js application that uses AI to extract financial data from receipts for tax preparation.
• Deployment requires Docker Compose, PostgreSQL, and at least one LLM provider API key configured in .env.
• Key files: lib/config.ts manages environment settings, lib/llm-providers.ts configures AI backends, and models/transactions.ts handles data persistence.
• Self-hosted mode (SELF_HOSTED_MODE=true) enables automatic login and disables public registration.
• Data export produces CSV files ready for tax filing, preserving original document links and custom metadata.

Frequently Asked Questions

Do I need to use Docker to run TaxHacker?

No, Docker is optional but recommended. You can run the application locally by executing npm install, running npx prisma migrate dev to initialize the database, and starting the dev server with npm run dev. However, Docker Compose provides a one-click deployment with automatic database migrations and consistent environment variables.

Which AI providers does TaxHacker support for receipt extraction?

TaxHacker supports OpenAI, Google Gemini, Mistral, and any OpenAI-compatible API endpoint. The provider selection and configuration are managed in lib/llm-providers.ts, allowing you to choose the service that matches your privacy requirements and API key availability.

What happens to my uploaded files and data in self-hosted mode?

In self-hosted mode, all data remains on your local infrastructure. Files are stored in the path defined by UPLOAD_PATH (default ./data/uploads), and transaction data resides in your PostgreSQL database. This architecture ensures complete data privacy since no information is sent to third-party servers beyond the LLM API calls for text extraction.

How do I customize the data fields for my specific tax requirements?

TaxHacker supports custom field definitions through the fields table managed by models/fields.ts. You can add custom fields via the UI, which will then be accepted by the transaction creation API alongside standard fields like total and currencyCode. These custom fields appear in CSV exports and can be filtered in the transactions table.

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