invoice/docs/user-guide.md

Invoice App — User Guide

Getting started

The app is a single web page that must be served from a web server. It cannot be opened directly as a file in your browser because it needs to load its configuration from a separate file (config.yml), and browsers block that kind of request from plain file:// URLs.

To run it locally, open a terminal, go to the app/ folder, and start a simple server with one of these commands:

npx serve app

or

cd app && python -m http.server

Then open the address shown in your terminal (usually http://localhost:3000 or http://localhost:8000) in your browser.

Your details (From)

The top-left card is labelled From. Fill in your name or business name, address lines, country, phone, email, and VAT / Tax ID. Everything you type here is saved automatically to your browser's local storage, so it will still be there the next time you open the app. You only need to fill this in once.

Invoice details

The top-right card is labelled Invoice Details. It contains four fields:

• Invoice date — a date picker that defaults to today. Change it if you are backdating or forward-dating the invoice.
• Invoice currency — a dropdown of the currencies configured for your account. Choose the currency you want to invoice in.
• Project code — either pick a code from the dropdown (the list depends on which client you have selected under Charge to, or falls back to the general project code list) or choose Other to type a free-text code. Your last-used choice is saved.
• Invoice no. — a free-text field for your invoice number. You can type anything you like. After you generate an invoice, the number is automatically incremented the next time the app loads — so if your last invoice was INV-007, the next session will start with INV-008. You can always edit it manually before generating.

Charge to (recipient)

The top-right card of the second column is labelled Charge to. Use the dropdown at the top to choose who you are billing.

• A predefined client — all address and contact fields fill in automatically and become read-only. The project code list in Invoice Details also updates to show only the codes linked to that client.
• Other — all fields become editable so you can type a one-off recipient.
• — Select — — the default state; all fields are locked and empty. The invoice cannot be generated meaningfully until you have either chosen a client or selected Other and filled in the details.

Payment

The bottom-left card is labelled Payment.

• Payment terms — enter the number of days the client has to pay. The Pay by date is calculated automatically from the invoice date.
• Bank account fields — these fields (account holder, account number / IBAN, bank / BIC, bank address, and payment reference) are only visible when you have selected Other under Charge to. For predefined clients, payment instructions are managed through the configuration and appear on the invoice automatically.

Invoice lines

The large card below the four top cards holds your invoice lines.

To start, click + Add new line. Each line works as follows:

1. Description — choose a predefined service from the dropdown, or choose Other to type a custom description. Until you make a selection, the quantity, unit of measure, and unit price fields are all locked.
2. Predefined service — the unit of measure (e.g. Hour, Day, Each) fills in automatically from the configuration and cannot be changed on that line. The unit price fills in with the configured default but you can edit it. Enter the quantity.
3. Other — all fields are editable. Choose a unit of measure from the dropdown, then enter quantity and unit price.

To remove a line, click the × button on the right. To start fresh, click Reset invoice lines (top right of the card); you will be asked to confirm before anything is cleared.

All line data is saved to local storage as you type and restored when you reopen the app. If you want to clear saved lines without generating an invoice, use the Reset button.

Foreign currency on a line

Each line has a Foreign currency toggle (No / Yes).

Set it to Yes if the client is billed in a currency that differs from your invoice currency. When you do:

• The Unit Price field locks — it is calculated for you and cannot be edited directly.
• Three new fields appear:
  • Currency code — select the foreign currency (e.g. USD).
  • Exchange rate — enter the rate in the form X foreign = 1 local. For example, if your invoice currency is THB and the rate is 0.028 USD per THB, enter 0.028. This means 0.028 USD equals 1 THB, so the app divides the foreign price by this number to get the local amount.
  • Price per item — enter the price in the foreign currency.
• A read-only line total in the foreign currency is displayed for your reference.
• The Unit Price (in your invoice currency) is calculated as: price per item ÷ exchange rate.

Tax

Below the invoice lines is the Totals section. Click + Add new tax to add a tax row. For each tax row:

• Enter either a percentage (e.g. 20 for 20%) or a fixed amount.
• Choose the tax type label: VAT, GST, Sales Tax, Withholding Tax, or Other Tax.

You can add as many tax rows as you need — for example, a VAT row and a Withholding Tax row on the same invoice.

The Paid field lets you record any amount already received. The To Pay total is calculated as: Subtotal + all tax rows − Paid.

Generating and downloading the invoice

When everything looks right, click the Generate Invoice button at the bottom of the page. A preview overlay opens showing your formatted invoice.

• Review it carefully before downloading.
• Click Download PDF to save the invoice as a PDF file using your browser's default download location.
• Click Close to go back and make changes. You can generate as many times as you like before downloading.

The PDF always renders in the default language regardless of which language you have selected in the interface.

Invoice number and auto-increment

The invoice number is saved to local storage each time you make a change. After you click Generate Invoice, the app marks that an invoice was generated. The next time you load the page, the trailing number in the invoice number is automatically incremented — for example, 2026-001 becomes 2026-002, or INV007 becomes INV008. Leading zeros are preserved.

If you need to override the number — for instance to skip a number or correct a mistake — simply edit the Invoice no. field before generating.

Language and zoom

A small bar at the top of the page contains two controls:

• A− / A+ — decrease or increase the text size. The zoom level is saved between sessions.
• Language dropdown — visible only if more than one language is configured. Switching language changes all the form labels immediately. Note that the PDF is always generated in the default language.