receipt-wrangler-api/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Receipt Wrangler API is a Go-based backend service for a receipt management and splitting application. It provides OCR-powered receipt scanning, AI-assisted data extraction, email integration, and multi-user support with group management capabilities.

Development Commands

Building and Running

• go build - Build the application
• go run main.go - Run the application directly
• ./set-up-dependencies.sh - Install system dependencies (tesseract, ImageMagick, Python deps)

Testing

• go test -v ./... - Run all Go tests with verbose output
• go test -coverprofile=coverage.out -covermode=atomic -v ./... - Run tests with coverage
• python3 -m unittest discover -s ./imap-client - Run Python IMAP client tests

API Client Generation

• ./generate-client.sh desktop <output-dir> - Generate TypeScript Angular client
• ./generate-client.sh mobile <output-dir> - Generate Dart Dio client

Architecture Overview

Core Structure

• main.go - Application entry point, initializes logging, config, database, and starts HTTP server
• internal/ - Core application code organized by domain
• imap-client/ - Python-based email processing client

Key Directories

• internal/handlers/ - HTTP request handlers for each API endpoint
• internal/repositories/ - Database access layer using GORM
• internal/services/ - Business logic layer
• internal/models/ - Database models and domain objects
• internal/commands/ - Command objects for API requests/responses
• internal/routers/ - Route definitions and middleware setup
• internal/wranglerasynq/ - Background job processing using Asynq
• internal/ai/ - AI client implementations (OpenAI, Gemini, Ollama)

Database

• Uses GORM ORM with support for SQLite, MySQL, and PostgreSQL
• Migrations are handled automatically on startup via repositories.MakeMigrations()
• Test databases are set up in repositories/main_test.go

Background Processing

• Uses Hibiken's Asynq library for background job processing
• Email processing, OCR, and cleanup tasks run as background jobs
• Queue configurations defined in internal/wranglerasynq/

AI Integration

• Supports multiple AI providers: OpenAI, Google Gemini, and Ollama
• AI clients implement a common interface defined in internal/ai/base_client.go
• Used for receipt data extraction and processing

Configuration

• Configuration loaded from JSON files in config/ directory
• Environment variables override config file settings
• Sample configuration in config/config.sample.json

Testing Patterns

Each package typically has:

• main_test.go - Test setup and teardown
• *_test.go - Unit tests for specific functionality
• Test utilities in internal/utils/testing.go and internal/repositories/testing.go

Tests use dependency injection patterns and mock implementations for external services.

OCR and Image Processing

• Tesseract OCR integration via otiai10/gosseract
• ImageMagick integration for image processing and format conversion
• Supports HEIC format conversion to standard image formats
• Python dependencies for additional image processing capabilities

API Documentation

• OpenAPI 3.1 specification in swagger.yml
• API serves on port 8081 by default
• All endpoints require JWT authentication except login/signup