TaxHacker Documentation

Technical Documentation: vas3k/TaxHacker

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

[!NOTE]
☝️ I'm currently looking for a job! Particularly interested in companies in Berlin or remote positions in Germany. Here's my CV and Linkedin profile. Thank you 🙏

TaxHacker is a self-hosted accounting app designed for freelancers, indie-hackers, and small businesses who want to save time and automate expense and income tracking using the power of modern AI.

Upload photos of receipts, invoices, or PDFs, and TaxHacker will automatically recognize and extract all the important data you need for accounting: product names, amounts, items, dates, merchants, taxes, and save it into a structured Excel-like database. You can even create custom fields with your own AI prompts to extract any specific information you need.

The app features automatic currency conversion (including crypto!) based on historical exchange rates from the transaction date. With built-in filtering, multi-project support, import/export capabilities, and custom categories, TaxHacker simplifies reporting and makes tax filing a bit easier.

🎥 Watch demo video

[!IMPORTANT]

This project is still in early development. Use at your own risk! Star us to get notified about new features and bugfixes ⭐️

✨ Features Copy Chapter

`1` Analyze photos and invoices with AI Copy Section

Snap a photo of any receipt or upload an invoice PDF, and TaxHacker will automatically recognize, extract, categorize, and store all the information in a structured database.

• Upload and organize your docs: Store multiple documents in "unsorted" until you're ready to process them manually or with AI assistance
• AI data extraction: Use AI to automatically pull key information like dates, amounts, vendors, and line items
• Auto-categorization: Transactions are automatically sorted into relevant categories based on their content
• Item splitting: Extract individual items from invoices and split them into separate transactions when needed
• Structured storage: Everything gets saved in an organized database for easy filtering and retrieval
• Choose your LLM: You can use OpenAI, Google Gemini, or Mistral or even your local LLM (in the self-hosted version). Only you're responsible for the quality and privacy of your data.

TaxHacker works with a wide variety of documents, including store receipts, restaurant bills, invoices, bank statements, letters, even handwritten receipts. It handles any language and any currency with ease.

`2` Multi-currency support with automatic conversion (even crypto!) Copy Section

TaxHacker automatically detects currencies in your documents and converts them to your base currency using historical exchange rates.

• Foreight currency detection: Automatically identify the currency used in any document
• Historical rates: Get conversion rates from the actual transaction date
• All-world coverage: Support for 170+ world currencies and 14 popular cryptocurrencies (BTC, ETH, LTC, DOT, and more)
• Flexible input: Manual entry is always available when you need more control

`3` Use your own LLM: Ollama, LM Studio, vLLM, LocalAI etc Copy Section

It's compatible with your local LLM OpenAI-compatible API endpoint. Just make sure that your local model is good in OCR tasks, results are not guaranteed :)

`4` Organize your transactions using fully customizable categories, projects and fields Copy Section

Adapt TaxHacker to your unique needs with unlimited customization options. Create custom fields, projects, and categories that better suit your specific needs, idustry standards or country.

• Custom categories and projecst: Create your own categories and projects to group your transactions in any convenient way
• Custom fields: You can create unlimited number of custom fields to extraxt more information from your invoices (it's like creating extra columns in Excel)
• Full-text search: Search through the actual content of recognized documents
• Advanced filtering: Find exactly what you need with search and filter options
• AI-powered extraction: Write your own prompts to extract any custom information from documents
• Bulk operations: Process multiple documents or transactions at once

`5` Customize any LLM prompt. Even system ones Copy Section

Take full control of how TaxHacker's AI processes your documents. Write custom AI prompts for fields, categories, and projects, or modify the built-in ones to match your specific needs.

• Customizable system prompts: Modify the general prompt template in settings to suit your business
• Field or project-specific prompts: Create custom extraction rules for your industry-specific documents
• Full control: Adjust field extraction priorities and naming conventions to match your workflow
• Industry optimization: Fine-tune the AI to understand your specific type of business documents
• Full transparency: Every aspect of the AI extraction process is under your control and can be changed right in settings

TaxHacker is 100% adaptable and tunable to your unique requirements — whether you need to extract emails, addresses, project codes, or any other custom information from your documents.

`6` Flexible data filtering and export Copy Section

Once your documents are processed, easily view, filter, and export your complete transaction history exactly how you need it.

• Advanced filtering: Filter by date ranges, categories, projects, amounts, and any custom fields
• Flexible exports: Export filtered transactions to CSV with all attached documents included
• Tax-ready reports: Generate comprehensive reports for your accountant or tax advisor
• Data portability: Download complete data archives to migrate to other services—your data stays yours

`7` Self-hosted mode for data privacy Copy Section

Keep complete control over your financial data with local storage and self-hosting options. TaxHacker respects your privacy and gives you full ownership of your information.

• Home server ready: Host on your own infrastructure for maximum privacy and control
• Docker native: Simple setup with provided Docker containers and compose files
• Data ownership: Your financial documents never leaves your control
• No vendor lock-in: Export everything and migrate whenever you want
• Transparent operations: Full access to source code and complete operational transparency

🛳 Deployment and Self-hosting Copy Chapter

TaxHacker can be easily self-hosted on your own infrastructure for complete control over your data and application environment. We provide a Docker image and Docker Compose setup that makes deployment simple:

curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml

docker compose up

The Docker Compose setup includes:

• TaxHacker application container
• PostgreSQL 17+ database (or connect to your existing database)
• Automatic database migrations on startup
• Volume mounts for persistent data storage
• Production-ready configuration
• no-new-privileges security option on all containers

New Docker images are automatically built and published with every release. You can use specific version tags (e.g., v1.0.0) or latest for the most recent version.

For advanced setups, you can customize the Docker Compose configuration to fit your infrastructure. The default configuration uses the pre-built image from GitHub Container Registry, but you can also build locally using the provided Dockerfile.

Example custom configuration:

services:
  app:
    image: ghcr.io/vas3k/taxhacker:latest
    ports:
      - "7331:7331"
    environment:
      - SELF_HOSTED_MODE=true
      - UPLOAD_PATH=/app/data/uploads
      - DATABASE_URL=postgresql://postgres:postgres@localhost:5432/taxhacker
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Environment Variables Copy Section

Configure TaxHacker for your specific needs with these environment variables:

💡 Need internet access with authentication? See docs/self-hosted-public-access.md for a workaround (yes, it's cursed).

⌨️ Local Development Copy Chapter

We use:

• Next.js 15+ for the frontend and API
• Prisma for database models and migrations
• PostgreSQL as the database (PostgreSQL 17+ recommended)
• Ghostscript and GraphicsMagick for PDF processing (install on macOS via brew install gs graphicsmagick)

Set up your local development environment:

# Clone the repository
git clone https://github.com/vas3k/TaxHacker.git
cd TaxHacker

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env

# Edit .env with your configuration
# Make sure to set DATABASE_URL to your PostgreSQL connection string
# Example: postgresql://user@localhost:5432/taxhacker

# Initialize the database
npx prisma generate && npx prisma migrate dev

# Start the development server
npm run dev

Visit http://localhost:7331 to see your local TaxHacker instance in action.

For a production build, instead of npm run dev use the following commands:

# Build the application
npm run build

# Start the production server
npm run start

🤝 Contributing Copy Chapter

No AI-slop PRs. Please open a new Issue and discuss the details with maintainers before sending new changes.

❤️ Support the Project Copy Chapter

If TaxHacker has helped you save time or manage your finances better, consider supporting its development! Your donations help us maintain the project, add new features, and keep it free and open source. Every contribution helps ensure we can keep improving and maintaining this tool for the community: https://vas3k.com/donate/

📄 License Copy Chapter

TaxHacker is licensed under the MIT License.

Overview (`app/(app)/apps/email/README.md`) Copy Section

Email Server Monitor

This app allows you to connect to email servers and automatically monitor incoming emails for file attachments that can be processed by TaxHacker.

🔧 **Setup** Copy Chapter

1. Add Email Server Copy Section

1. Go to Apps → Email Server Monitor
2. Click "Add Server"
3. Choose your email provider (Gmail, Outlook, etc.)
4. Enter your email and app password
5. Choose a sync frequency (default: Hourly — options range from every 15 minutes to daily)
6. Set allowed file extensions (default: .pdf, .jpg, .jpeg, .png)

2. Email Provider Settings Copy Section

Gmail

• Host: imap.gmail.com
• Port: 993 (SSL)
• Note: You need to use an App Password, not your regular password
• Setup: Go to Google Account → Security → 2-Step Verification → App Passwords

Outlook/Hotmail

• Host: outlook.office365.com
• Port: 993 (SSL)
• Note: You may need to enable IMAP in Outlook settings

Apple iCloud

• Host: imap.mail.me.com
• Port: 993 (SSL)
• Note: You need to use an App-Specific Password

Other Providers

• Choose "Custom IMAP" and enter your provider's IMAP settings

⚙️ **How It Works** Copy Chapter

Automatic Sync Copy Section

• Cron Job: A heartbeat fires every 5 minutes, but each server is only synced once its per-server Sync frequency (set in the UI, 15 min – daily) has elapsed (the app throttles; a manual "Sync Now" bypasses it). The 5-minute heartbeat is the resolution floor — the per-mailbox frequency is the real cadence.
• File Processing: Only downloads attachments with allowed extensions
• Duplication Prevention: Tracks highest processed IMAP UID per server; mail is fetched read-only and never marked as read
• Status Updates: Updates server status and last sync time

Manual Sync Copy Section

• "Sync Now" Button: Trigger immediate sync from the UI
• API Endpoint: POST /api/email/sync for programmatic access
• Independent Script: npm run email:sync can be run manually

🐳 **Docker Setup** Copy Chapter

Scheduled tasks (including email sync) run in a shared cron container:

# docker-compose.yml
cron:
  image: ghcr.io/vas3k/taxhacker:latest
  volumes:
    - ./data:/app/data
    - ./etc/crontab:/mnt/crontab:ro
  environment:
    - DATABASE_URL=postgresql://...
    # Optional override. If unset, the container reads the persisted secret from ./data/.better_auth_secret.
    - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET:-}
  command: ["docker-cron-entrypoint.sh"]

Cron Configuration Copy Section

File: etc/crontab

# Cron jobs source /etc/cron.env (written at container startup).
*/5 * * * * set -a; . /etc/cron.env; cd /app && npm run email:sync >> /var/log/cron.log 2>&1

Env propagation: cron strips the environment, so the container's startup script dumps the
needed vars to /etc/cron.env and each job sources it. In self-hosted Docker, if
BETTER_AUTH_SECRET is unset, TaxHacker generates and persists one in ./data/.better_auth_secret
so the app and cron containers still share the same key.

📊 **Data Storage** Copy Chapter

Email Servers Copy Section

• Stored in appData table with app = 'email'
• Each user can have multiple email servers
• Settings include sync interval, file extensions, credentials

Downloaded Files Copy Section

• Saved to UPLOAD_PATH directory
• Created as File records in database
• Metadata includes email details (subject, sender, date)
• Source marked as 'email' for tracking

Sync Status Copy Section

• lastSyncedAt: When server was last checked
• lastProcessedUid: Highest IMAP UID processed per server (prevents duplicates; mail is never marked as read)
• status: connected, error, pending, paused

🔧 **Commands** Copy Chapter

# Manual sync (run once)
npm run email:sync

# View logs
docker logs taxhacker_cron

# Check installed crontab
docker exec taxhacker_cron crontab -l

🚨 **Troubleshooting** Copy Chapter

Authentication Issues Copy Section

• Gmail: Make sure you're using an App Password, not your regular password
• Outlook: Enable IMAP access in settings
• 2FA: Most providers require app-specific passwords when 2FA is enabled

Connection Issues Copy Section

• Check firewall settings for IMAP ports (usually 993 or 143)
• Verify server settings match your provider's documentation
• Test connection using "Test Connection" button

No Emails Found Copy Section

• Check if the sync frequency has elapsed since the last sync
• Verify the mailbox has new messages (above the last processed UID) carrying attachments — fetch is read-only and does not depend on unread status
• Check allowed file extensions match your attachments
• Review logs: docker logs taxhacker_cron

Performance Copy Section

• Default sync frequency is Hourly — pick a shorter one (down to every 15 min) in the UI if needed
• Large attachments may take time to download
• Monitor storage usage for attachment files

📝 **Logs** Copy Chapter

Email sync logs are available:

• Container logs: docker logs taxhacker_cron
• Cron log: /var/log/cron.log inside container
• Manual sync: Output shown in terminal when running npm run email:sync

🔒 **Security** Copy Chapter

• Passwords: Stored encrypted at rest (AES-256-GCM), with the key derived from the BETTER_AUTH_SECRET environment variable. Decrypted only at sync/connection-test time.
  • ⚠️ Rotating BETTER_AUTH_SECRET invalidates stored mailbox passwords. After changing it, re-enter each server's password (the server shows a decryption error until you do).
• IMAP SSL: Enabled by default for all preset providers
• Access Control: Each user can only access their own email servers
• App Passwords: Recommended for all providers supporting them

Migrate 0.3 0.5 (`docs/migrate-0.3-0.5.md`) Copy Section

How to migrate data from v0.3 to v0.5

In v0.5 we changed the database from SQLite to Postgres. Because of this, it was not possible to seamlessly migrate data from one database to another and you will have to do it yourself.

Don't worry, even if you already upgraded — your data is not lost!

Here's how to migrate properly:

Step 1: Update your docker-compose to v0.3.0 Copy Chapter

services:
  app:
    image: ghcr.io/vas3k/taxhacker:v0.3.0
    ports:
      - "7331:7331"

// everything else stays the same

Step 2: Restart your app and make a backup Copy Chapter

docker compose down
docker compose up -d

Go to your app -> Settings -> Backups -> Download Data Archive

Save .zip archive on your machine.

Step 3: Upgrade your TaxHacker instance Copy Chapter

Update your docker compose to latest version again.

services:
  app:
    image: ghcr.io/vas3k/taxhacker:latest
    ports:
      - "7331:7331"

// everything else stays the same

Restart again.

Step 4: Upload your data to the new instance Copy Chapter

Open your app -> Settings -> Backups -> Restore from a backup

Upload your zip archive and click restore. After couple of seconds it must show you import stats.

If import fails with an error about file size, go to next.config.ts and change bodySizeLimit: "256mb" to something bigger.

Self Hosted Public Access (`docs/self-hosted-public-access.md`) Copy Section

Self-Hosted Public Access

⚠️ Warning: This is a workaround ("hack") for exposing self-hosted instances to the internet.
This approach has security implications and should be used with caution. For production deployments, consider implementing proper authentication with reverse proxy or using the official cloud version.

Overview Copy Chapter

By default, TaxHacker's self-hosted mode (SELF_HOSTED_MODE=true) disables the built-in authentication system, assuming the instance runs on a trusted local network or behind a reverse proxy with its own authentication.

However, if you want to expose your self-hosted instance to the internet and still use TaxHacker's built-in login system, you can use this workaround.

How It Works Copy Chapter

The approach involves:

1. Running TaxHacker with SELF_HOSTED_MODE=false (cloud mode)
2. Manually creating a user via direct database access
3. Retrieving the OTP (one-time password) from the database
4. Using that OTP to sign in

Setup Instructions Copy Chapter

1. Configure Environment Variables Copy Section

Run with these environment variables:

SELF_HOSTED_MODE=false
DISABLE_SIGNUP=true
BASE_URL=<URL you'll use to access TaxHacker>

2. Create a User Directly in the Database Copy Section

Create your user directly in the database (replace email as needed):

docker exec -it postgres psql -U postgres -d taxhacker -c "INSERT INTO users (id, email, name, membership_plan, is_email_verified, updated_at) VALUES ('6f5b4f8e-6f7a-4c3d-9b8b-7f2d2d61a9c3','[email protected]','Owner','unlimited', true, now());"

3. Sign In with OTP from Database Copy Section

Open your instance in the browser, click Sign In, and enter your email address.

Fetch the latest OTP from the database and use it to sign in:

docker exec -it postgres psql -U postgres -d taxhacker -c "SELECT value FROM verification ORDER BY created_at DESC LIMIT 1;"

4. Seed the Database Copy Section

Because we skipped the normal route, database seeding won't happen automatically. Open <YOUR_URL>/settings/backups and click [Reset fields, currencies and categories]

--- METRICS ---

• Files Extracted: 4
• Estimated Token Budget: ~5199 tokens
• Canonical Reference: https://codewiki.google/github.com/vas3k/TaxHacker