Itemly – Receipt Tracker

Capture receipts privately, review every detail, and store your data locally.

Itemly is a mobile-first, self-hosted web app for structured purchase data. Receipt images and data stay on your own computer by default. You can enter receipts manually, use a free copy-and-paste workflow with a regular ChatGPT chat, or optionally configure an OpenAI-compatible API provider.

An experimental Android package is now being developed for phone-local use without a running computer. It is not yet a verified release; see Android prototype before installing or relying on it.

Android now includes Daten & Sicherung for user-initiated full export/restore and a separate Android installable update APK workflow for durable-signed updates. Signing setup and device acceptance are required; do not alternate durable update APKs with disposable PR artifacts. Android and webserver backups currently use different formats.

Why Itemly?

Many receipt apps require an account, cloud storage, or a paid AI service. Itemly takes a different approach:

• Local first: A SQLite database and original images live in a local data directory.
• No recurring AI cost required: Manual entry and ChatGPT JSON import need no API key.
• Review before saving: Extracted details remain unverified until you check them.
• Transparent totals: Printed values are preserved; discrepancies are shown instead of silently corrected.
• Replaceable integrations: Extraction, file storage, and persistence are separate adapters.

What v0.1.0 includes

• Camera and gallery selection with preview and explicit consent before external processing
• Validated JSON import from a regular ChatGPT chat
• A fully manual workflow without AI access
• Editing of merchant, item, payment, and total details during review and after saving
• Item creation, editing, and removal within an existing receipt
• Receipt trash and restoration without losing original images or extraction evidence
• Uncertainty markers for extracted items and fields
• Arithmetic checks for line items, discounts, taxes, deposits, and fees
• Drafts and atomic, idempotent saves of balanced purchases
• Local history with search and detail views
• Single-receipt export, portable export with the original image, and full backup
• Installable PWA with light and dark themes

Quick start

Requirements:

• Node.js 24 or newer
• pnpm 11.24.0

pnpm install
pnpm dev

The development services are then available at:

• Web app: http://localhost:5173
• API: http://localhost:8787

To test on a phone connected to the same Wi-Fi network, use the network URL printed by the development server, for example http://192.168.1.10:5173.

Production use

pnpm build
pnpm start

The complete app is then served at http://localhost:8787.

Itemly v0.1.0 has no user accounts or access control. Run the server only on a private computer or trusted home network unless you add suitable access protection. Do not expose it directly to the public internet.

Experimental Android build

The Android project is in android/. It bundles the React UI and routes receipt capture, manual entry, ChatGPT JSON import, saves, history, and detail views to app-private storage rather than the PC API. After installing Android Studio and its SDK, run pnpm android:sync, open the project with pnpm android:open, and deploy a debug build to a device. The Android prototype guide lists the required real-device tests and current limitations. User-initiated Android backup export and restoration are implemented, but acceptance on a physical device is still pending. Existing receipts in the PC database are not automatically copied to the phone, and migration from webserver backups to Android is not implemented. The backup formats remain separate; do not treat the prototype as the only copy of important receipts.

Capture receipts without an API key

1. Select ChatGPT-JSON importieren in Itemly.
2. Copy the provided prompt template.
3. Send the template and receipt image in a regular ChatGPT chat.
4. Paste the returned JSON into Itemly.
5. Review every value before saving.

This workflow does not use an AI API inside Itemly. Uploading the image to ChatGPT is a separate, deliberate user action. Common copy-and-paste artifacts are repaired, but the data is still fully validated and never automatically marked as reviewed.

Optional API configuration

Copy .env.example to .env and configure it as needed:

OPENAI_API_KEY=
OPENAI_MODEL=gpt-4.1-mini
OPENAI_BASE_URL=https://api.openai.com/v1

The key stays on the server and is never sent to the browser. A receipt image is sent to the configured provider only after an explicit notice. Without a key, manual entry and ChatGPT JSON import remain available.

Local data and backups

By default, Itemly uses ./data:

• receipts.sqlite – relational SQLite database
• receipts/ – content-addressed original images

The entire directory and .env are excluded from Git. Download a full backup from the purchase overview or through GET /api/backup.

To restore a backup:

pnpm restore <backup.json> <empty-destination-directory>

Then point DATA_DIR to the destination directory, start Itemly, and inspect at least one purchase and its image.

Quality checks

pnpm check
pnpm build

Tests cover schema validation, arithmetic, discounts, taxes, fees, uncertainties, duplicate detection, idempotency, transactions, backups, and extraction failures. The same checks run on pushes and pull requests in GitHub Actions.

Rendered React interaction tests also cover receipt review and money-field editing. These DOM tests are distinct from browser layout checks and physical Android acceptance; see testing and verification.

Architecture and project information

• Architecture
• Privacy and data flow
• Security policy
• Contributing
• Changelog
• v0.2.0 roadmap and v0.3.0 roadmap

Planned improvements

• Clear details for each uncertain field
• Editing previously saved purchases
• A more convenient editor for fees, deposits, and discounts
• CSV reports and statistics
• Optional, replaceable backup destinations

License

The source code is available under the MIT License © 2026 Chasan Moustafa.