refactors, comments, documentation

1 files changed, 131 insertions, 0 deletions

diff --git a/docs/STORAGE.rst b/docs/STORAGE.rst
new file mode 100644
index 0000000..29ad037
--- /dev/null
+++ b/docs/STORAGE.rst
@@ -0,0 +1,131 @@
+.. _storage:
+
+================================
+OpenBooks - file and data format
+================================
+
+Your administration is stored in a single **.openbooks** file.  
+This is a zip file with the following format:  
+
+::
+
+    administration.openbooks/
+    ├── administration.xml
+    ├── invoices/
+    │   ├── invoice_0000000001.xml
+    │   ├── invoice_0000000002.xml
+    ├── documents/
+    │   ├── invoice_1.pdf
+    │   ├── invoice_2.pdf
+    │   ├── receipt_3.png
+
+**administration.xml** contains all company settings and data. This includes company info, projects, contacts, vat rates and cost centers.
+
+**invoices/** Contains all incomming and outgoing invoices, stored in Peppol BIS 3.0 format.
+
+**documents/** Contains all documents from which invoices have been generated.
+
+Data structures
+===============
+
+Administration
+--------------
+
+- info — Contact information, stored as **Contact**
+- next id — Id reserved for new data entry
+- path — File path to save to
+- program version — Version of data format
+- country — Country code (used for tax reports)
+- contacts **list** — List of contacts
+- projects **list** — List of projects
+- invoices **list** — List of invoices
+- tax brackets **list** — List of available tax brackets
+- AI service — Which AI service to use
+- AI key — API key for selected AI service
+- email service — Which email service to use
+- email key — API key for selected email service
+
+Contact
+-------
+
+- id **auto** — reference id **C/[id]**
+- name **required** — Full name of individual or company name
+- address line 1 **required** — Address
+- address line 2 **required** — Zip, place
+- country **required** — Country
+- type **required** — Contact type, **business** or **consumer**
+- tax number — Tax identification number
+- business number — Business number
+- email — Email address
+- Phone number — Phone number
+- bank account — Bank account number (to display on outgoing invoices)
+
+Invoice (`docs <https://accountancyeurope.eu/wp-content/uploads/2025/04/250423-VAT-and-the-Digital-Age-Factsheet-Accountancy-Europe.pdf>`_)
+-------------------------------------------------------------------------------------------------------------------------------------------
+
+- id **auto** — reference id **I/[id]**
+- sequential number **auto** — Generated sequential invoice number
+- customer **required** — Customer contact information, stored as reference **C/[id]**
+- supplier **required** — Supplier contact information, stored as reference **C/[id]**
+- issue at **required** — Date when invoice was issued
+- delivered at **required** — Date when goods or services were delivered
+- expires at **required** — Date when invoice expires
+- document **required** — Document associated with invoice, stored as filename
+- billing items **required** **list** — List of billed items
+- project — Project, stored as reference **P/[id]**
+- cost center id — Cost center, stored as reference **E/[id]** (incoming invoices only)
+- total **required** — Total amount billed
+- tax **required** — Total tax billed
+- net **required** — Total amount excl. tax
+- status **required** — Payment status **paid** **expired** **cancelled** **refunded**, **corrected**
+- shipping address line 1 **required** — Address
+- shipping address line 2 **required** — Zip, place
+- country **required** — Country
+- currency **required** — Currency used for billing
+- keep until **required** — Date until invoice needs to be stored legally
+- payment on account date — If advance payment received and differs from invoice date (Ireland only)
+- tax representative — If supplier uses tax representative in another Member State (Belgium only)
+- corrected sequential number — For corrective invoices, the sequential number that identifies the original invoice to be corrected
+
+Billing item
+------------
+
+- id **auto** — reference id **B/[id]**
+- invoice **auto** — reference to invoice **I/[id]**
+- description **required** — Description of billed item
+- tax bracket **required** — Tax bracket (e.g. 0%, 21%, exempt, reversed)
+- tax section **required** — Tax section (e.g. 1a up to 4b in The Netherlands)
+- amount **required** — Amount of items, or a percentage
+- amount is percentage **required** — Amount of items, or a percentage
+- net per item **required** — Is amount a percentage
+- net **required** — Total amount excl. tax
+- discount **required** — Total discount
+- tax **required** — Total tax billed
+- is intra-community **required** — If applicable, note like “intra-Community supply of goods”
+- is triangulation **required** — For EU triangulation: note scheme and buyer liable
+- currency **required** — Currency used for billing
+- internal code — Article or service code
+
+Project
+-------
+
+- id **auto** — reference id **P/[id]**
+- description **required** — Description of project
+- start date **required** — Project started at date
+- status **required** — Status of project **running** **paused** **cancelled**
+- end date — Project cancelled at date
+
+Cost center
+-----------
+
+- id **auto** — reference id **E/[id]**
+- code **required** — Internal code of cost center
+- description **required** — Description of cost center
+
+Tax bracket
+-----------
+
+- id **auto** — reference id **T/[id]**
+- country code **required** — 2 letter country code
+- description **required** — Description of tax bracket
+- rate **required** — Tax rate %