# Concepts – MAD invoiceMCP
This document explains the core concepts behind MAD invoiceMCP: what kind of workflow it targets, how invoices are stored, and why the project deliberately avoids a traditional SQL database.
It is meant as background reading. If you only need to run the server, start with `README.md` and `docs/getting-started-docker.md`.
---
## 1. Single-company scope
MAD invoiceMCP is intentionally designed for **one company in one repository**.
* One repository contains the code *and* the invoice data directory.
* One invoice store (by default `.mad_invoice/`).
* No built‑in concept of tenants, projects, or multiple companies.
This matches the intended use case:
* a freelancer or small business owner issuing invoices for a single legal entity
* running the server locally (desktop or small server) rather than as a shared SaaS
If you need features such as multiple tenants, access control for many users, or a central accounting backend shared by many companies, this project is intentionally too small and opinionated.
---
## 2. Storage model
Invoices live in a simple, project‑local directory tree. By default, the root is `.mad_invoice/` under the repository root or wherever `MAD_INVOICE_ROOT` points.
```text
.mad_invoice/
invoices/
<invoice-id>.json
index.json
build/
<invoice-id>/
invoice.tex
invoice.pdf
```
* `invoices/<invoice-id>.json`
* one JSON file per invoice
* full `Invoice` payload, as defined in `bridge/backends/invoices_models.py`
* `index.json`
* a lightweight index of invoices for fast listing and sorting
* regenerated by backend helpers whenever invoices change
* `build/<invoice-id>/`
* LaTeX and PDF artefacts for that invoice
* safe to delete; they will be recreated on demand
The **JSON files are the source of truth**. PDFs and LaTeX are derived artefacts.
The storage helpers in `bridge/backends/invoices_storage.py` handle:
* finding and creating the root directory
* reading and writing invoice JSON files
* maintaining `index.json`
* creating per‑invoice build directories
Consumers (MCP tools, web handlers) are expected to go through these helpers rather than touching files directly.
---
## 3. Why JSON instead of SQL
MAD invoiceMCP uses JSON files on disk instead of a SQL database for several reasons:
1. **Simple setup**
* No separate database server to install, configure, and maintain.
* No schema migrations or migration tools.
* A working Python runtime and a writable directory are enough.
2. **Human-readable data**
* Invoice JSON files can be opened in any text editor.
* If an LLM or user makes a mistake in a draft, it is easy to inspect and fix the data directly.
* There is no opaque binary storage layer that requires specialised tools just to see what is going on.
3. **Good fit for the scale and model**
* The `Invoice` structure is explicitly modelled with Pydantic.
* The expected number of invoices for a single small business does not require complex querying or heavy indexing.
* A thin JSON+index layer is enough to support the MCP tools and the web UI.
Finalised invoices should not be edited for bookkeeping reasons, but the transparent storage model is very helpful during development and when working with LLM tools that generate invoice drafts.
If you need ad‑hoc queries across millions of invoices, cross‑company reporting, or complex joins with other datasets, a traditional database‑backed solution will likely be a better fit.
---
## 4. LaTeX and TeX Live requirements
Invoices are rendered to PDF through a LaTeX template. The project assumes a **recent TeX Live installation** and uses LaTeX packages that may not behave correctly on older distributions.
In particular:
* TeX Live 2024 or newer is recommended and is what the Docker image is built with.
* Some older TeX Live releases (for example, the TeX Live 2022 packages shipped with Debian 12) can produce broken page numbering and related issues.
For this reason, there are two recommended ways to satisfy the LaTeX requirement:
1. **Use the Docker image** (simplest)
* The image includes a known‑good TeX Live installation.
* You do not need LaTeX on the host at all.
2. **Install a recent TeX Live on the host**
* If you prefer a pure local install, use an up‑to‑date TeX Live rather than the older distribution packages.
If rendering fails with LaTeX errors, check your TeX Live version and consider switching to the Docker path.
---
## 5. Invoice lifecycle
Invoices follow a simple lifecycle with two main states plus a separate payment status field.
### 5.1 Draft vs final
Each invoice has a `status` field:
* `"draft"`
* fully editable
* can be created, updated, and deleted
* `"final"`
* immutable
* cannot be changed back to draft
* can still be rendered to PDF and read via MCP tools
The typical workflow is:
1. Create a draft invoice (via MCP tools or the web UI).
2. Review and correct the draft until it is ready.
3. Mark the invoice as final by setting `status="final"`.
4. Render and send the PDF to the customer.
Backends enforce that final invoices are not silently mutated.
### 5.2 Payment status
In addition to `status`, each invoice has a `payment_status` field:
* `"open"`
* `"paid"`
* `"overdue"`
* `"cancelled"`
This is independent of the draft/final lifecycle:
* A draft invoice can be `open` or `cancelled`.
* A final invoice can move from `open` to `paid` or `overdue` over time.
The `update_invoice_status` tool is responsible for changing `payment_status` and, when appropriate, moving an invoice from `draft` to `final`.
---
## 6. Language and locale handling
MAD invoiceMCP supports German and English invoices via a `language` field on the `Invoice` model and a set of language‑aware helpers.
Key points:
* `language` is currently `"de"` or `"en"`.
* Labels and boilerplate text (e.g. small‑business note for §19 UStG) are localised based on the invoice language.
* Date formatting can follow either an ISO style (`YYYY-MM-DD`) or a locale‑style format, controlled by `date_style`.
* Currency formatting and contact line layout are adjusted to match the chosen language where applicable.
The goal is to keep the data model small while still producing readable invoices for both German and English customers.
