Flipper is a local-first resale intelligence and operations tool for evaluating opportunities, tracking acquired inventory, reconciling marketplace activity, and measuring realized results. Its current analyzer began with exported secondhand-computer listings. The generalized core now powers a read-only eBay discovery workspace while preserving explicit unknown economics.

Find the flip → Understand the economics → Acquire it → Track inventory
             → Sell it → Reconcile costs → Measure what actually happened

What Flipper does

• Analyzes user-provided JSON listing exports with deterministic parsing, valuation, and scoring.
• Creates durable Q-number inventory records from explicit acquisitions.
• Tracks lifecycle, attachments, valuations, sales, costs, and reconciliation in local SQLite.
• Reads eBay seller listings, orders, and Finances data through authorized APIs without marketplace writes.
• Researches live eBay and user-entered multi-source opportunities, including local-trip economics, in an ephemeral Deals workspace.
• Explicitly saves durable, historical research snapshots without turning estimates into accounting.
• Presents local operational reports in a server-rendered web dashboard.

Flipper is not a marketplace crawler, a complete accounting system, or an eBay listing manager.

Quick start

Python 3.13 or newer is recommended.

python -m venv .venv
python -m pip install -r requirements.txt
python main.py

See the getting-started guide for platform-specific activation, configuration, feed structure, and optional integrations.

Web app

uvicorn web.app:app --reload

Open http://127.0.0.1:8000. The dashboard uses local data. Deals can search eBay through its read-only Browse API or analyze a manually entered opportunity without fetching its source URL.

Documentation

The source documentation lives in docs/. Build it locally with:

python -m pip install -r requirements-dev.txt
mkdocs serve

GitHub Pages is enabled with GitHub Actions as its source. The documentation from this branch will be published at https://quangshuynh.github.io/flipper/ only after merge and a successful deployment workflow.

Local-first principles

The inventory database is authoritative. Runtime databases, attachments, credentials, tokens, buyer details, and raw marketplace responses do not belong in Git. Optional AI, Discord, market-data, and eBay integrations are separable from deterministic local workflows.

Development

python -m pytest
python -m ruff check .
python -m ruff format --check .
mkdocs build --strict

See architecture, testing and migrations, and the repository's AGENTS.md before changing persistent or marketplace behavior.

License

MIT. See LICENSE.