invoice-db

A relational database, CLI, API, React UI, and AI assistant application built with Python, SQLite, and TypeScript for managing customers and invoices.

The project emphasizes practical full-stack design: normalized relational schema design, shared service-layer business logic, command-line workflows, HTTP API endpoints, React-based UI workflows, Dockerized runtime support, natural-language invoice querying, and automated test coverage.

Features

As of v0.9.0, the project includes support for:

• Customer and invoice management
• Full CRUD operations for customers and invoices
• Invoice lifecycle/status management
• Filtering, sorting, and improved invoice queries
• Typer-based CLI with Rich terminal output
• Django REST Framework API layer
• React + TypeScript frontend UI
• Shared service layer used by both CLI and API
• Guarded natural-language invoice assistant using intent classification
• Dockerized backend runtime with persistent SQLite storage Backend and frontend test coverage with pytest, Vitest, and React Testing Library

Architecture

CLI        → services → db
API/DRF    → services → db
React UI   → API → services → db
Assistant  → router/classifier → validated intent → dispatcher → services → db
Qwen fallback → validated intent/message only

For the full folder breakdown, see invoice_db/docs/PROJECT_STRUCTURE.md.

Tech Stack

• Python 3
• SQLite 3
• Typer
• Rich
• Django REST Framework
• React
• TypeScript
• Vite
• Vitest
• React Testing Library
• Docker
• pytest
• scikit-learn
• Pydantic
• uv
• Optional: Ollama/Qwen for assistant fallback

Installation (Local)

1. Install uv

Install uv first if you do not already have it installed.

2. Clone the repository

git clone https://github.com/Erick-Allen/invoice-db.git
cd invoice-db

3. Sync the project environment

uv sync --extra dev

4. Run the CLI

uv run invoicedb --help

5. Run the API server

uv run python manage.py runserver

6. Install frontend dependencies

cd frontend
npm install

7. Run React UI

npm run dev

Installation (Docker)

Clone the repository and build the Docker image locally

git clone https://github.com/Erick-Allen/invoice-db.git
cd invoice-db
docker build -t invoicedb .

Run the Dockerized backend API

docker run --rm -p 8000:8000 -v ${PWD}/data:/data invoicedb

Interactive Shell

docker run --rm -it -v invoicedb_data:/data --entrypoint /bin/sh invoicedb

Docker and Qwen/Ollama fallback

If the Dockerized backend needs to reach Ollama running on the host machine, localhost:11434 will not work from

Use:

http://host.docker.internal:11434/api/chat

The default local fallback model is:

qwen3:0.6b

CLI Usage

Database commands

• invoicedb db init
• invoicedb db drop
• invoicedb db delete

Customer commands

• invoicedb customers create
• invoicedb customers list
• invoicedb customers get
• invoicedb customers update
• invoicedb customers delete

Invoice commands

• invoicedb invoices create
• invoicedb invoices list
• invoicedb invoices get
• invoicedb invoices count
• invoicedb invoices update
• invoicedb invoices set-status
• invoicedb invoices delete

Assistant command

• invoicedb assistant ask
• invoicedb assistant ask --use-qwen

Other

• invoicedb --version

API Endpoints

Customers

• GET /api/customers/
• POST /api/customers/
• GET /api/customers/{id}/
• PATCH /api/customers/{id}/
• DELETE /api/customers/{id}/

Invoices

• GET /api/invoices/
• POST /api/invoices/
• GET /api/invoices/{id}/
• PATCH /api/invoices/{id}/
• DELETE /api/invoices/{id}/
• PATCH /api/invoices/{id}/status/

Assistant

• POST /api/assistant/query/

Sample Data & Demo (CLI)

uv run python scripts/seed.py
uv run python scripts/demo.py

Note: seed.py seeds the regular project database, while the demo workflow uses a dedicated demo.sqlite database in the project root.

Testing

Backend tests

uv run pytest --cov=invoice_db --cov-report=term-missing

Frontend tests

cd frontend
npm run test:run

Version History

[v0.9.0]

Added

• Natural-language invoice assistant
• Intent classifier for supported invoice queries

Changed

• Updated Docker runtime from CLI-first behavior to API server behavior

[v0.8.0]

Added

• React + TypeScript frontend built with Vite
• Frontend pages for dashboard, customers, and invoices
• Customer create, edit, delete, and list workflows
• Invoice create, edit, delete, list, and status update workflows
• Frontend API client for customer and invoice endpoints
• Frontend tests with Vitest and React Testing Library

Changed

• Standardized invoice totals as integer cents across the API, service layer, and database

[v0.7.0]

Added

• Shared service layer for customers and invoices
• Django REST Framework API Layer
• Customer API endpoints
• Invoice API endpoints
• API test coverage for customer and invoice endpoints

Changed

• Updated CLI commands to use the shared service layer

[v0.6.0]

Added

• Invoice lifecycle/status logic
• Overdue invoice querying

Changed

• Improved invoice list and count querying

[v0.5.0]

Added

• Rich-based terminal output
• Packaged CLI as a global console command (invoicedb)
• Docker support
• Demo automation scripts

[v0.4.0]

Added

• Full invoice CRUD support in the CLI

[v0.3.0]

Added

• Introduced Typer-based CLI for customer and database management

[v0.2.0]

Added

• Added customer and invoice test coverage

[v0.1.0]

Added

• Initial SQLite schema and core CRUD functionality

Roadmap

[v0.10.0] (Minor)

• Add Products table

[v0.11.0] (Minor)

• Invoice line items

For the full project roadmap, see invoice_db/docs/ROADMAP.md.