Invoice Matcher Pro

A full-stack web application for reconciling invoice PDFs against order data (Excel/CSV). Upload order files and invoice PDFs, link them via a request ID, visually browse files, and run automated reconciliation.

Built with FastAPI (Python) + Next.js 14 (React/TypeScript) + PostgreSQL.

Quick Start

Interactive installer (recommended)

Your OS	Run this
Linux / macOS	chmod +x install.sh && ./install.sh
Windows	.\install.ps1 (PowerShell)

The installer prompts for your database details and admin credentials, then sets up everything automatically.

Manual setup

See docs/SETUP.md for detailed instructions covering Linux, macOS, and Windows.

---

Once installed

Linux / macOS:

./start_backend.sh    # Terminal 1
./start_frontend.sh   # Terminal 2

Windows (PowerShell):

# Terminal 1
cd backend
.venv\Scripts\Activate.ps1
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 2
cd frontend
npm run dev

Open http://localhost:3000 and sign in with the admin credentials you provided.

---

Prerequisites

Requirement	Version
Python	≥ 3.11
Node.js	≥ 20
npm	≥ 10
PostgreSQL	≥ 15

---

Project structure

InvoiceMatcher/
├── backend/           # Python FastAPI service
│   ├── app/
│   │   ├── api/       # Route handlers
│   │   ├── core/      # Config, logging, error handling
│   │   ├── db/        # Database session, health
│   │   ├── models/    # SQLAlchemy ORM models
│   │   └── storage/   # File storage abstraction
│   ├── alembic/       # Database migrations
│   └── scripts/       # Utility scripts (seed_admin.py)
├── frontend/          # Next.js 14+ app (App Router)
│   └── src/
│       ├── app/       # Pages and layout
│       ├── components/# Shared UI components
│       └── lib/       # API client, utilities
├── docs/              # PRD, phases, feature specs, setup guide
├── data/storage/      # Local file storage (gitignored)
├── .env.example
├── install.sh           # Interactive installer (Linux/macOS)
├── install.ps1          # Interactive installer (Windows PowerShell)
├── start_backend.sh     # Backend launcher
├── start_frontend.sh    # Frontend launcher
└── README.md

Development commands

Layer	Command	Description
Backend	uvicorn app.main:app --reload --port 8000	Dev server
Backend	ruff check .	Lint check
Backend	ruff format .	Auto-format
Backend	alembic upgrade head	Apply migrations
Backend	python scripts/seed_admin.py	Seed admin user
Frontend	npm run dev	Dev server
Frontend	npm run build	Production build
Frontend	npm run lint	Lint check
Frontend	npm run format	Auto-format

Setup documentation

Document	Contents
docs/SETUP.md	Full setup guide for Linux, macOS, Windows
docs/specs/	Phase specifications (0–3)
.env.example	All configurable environment variables

Configuration

Environment variables are documented in .env.example and docs/SETUP.md.

Key settings:

• DATABASE_URL — PostgreSQL connection string
• JWT_SECRET — Secret for JWT tokens (auto-generated by installer)
• STORAGE_LOCAL_PATH — Where uploaded files are stored on disk
• CORS_ORIGINS — Allowed frontend origins

Architecture

The application is split into three runtime components:

1. Backend API (FastAPI) — REST API on port 8000
2. Frontend (Next.js) — UI on port 3000
3. PostgreSQL — Database on port 5432

Analysis runs in a background thread with progress tracking pushed to the frontend via polling.

License

Proprietary — internal use.