Docs
Documentation
Every page here is a file of the repository, rendered when the site is built, so it says what the code in the same release does. What is not written yet says so.
Start here
What Ekwo OS is, and one command from a free Supabase project to a first invoice.
Ekwo OS, in one page
Ekwo OS is free and open source data infrastructure for accounting, finance and tax, under AGPL-3.0: a schema, the rules of each country as data, and tools, for businesses and…
Start with Claude: try Ekwo on your own books
Already using Claude? A free Supabase project, one command, the MCP server connected in Claude Desktop or Claude Code — then your own books taken over, questioned and a VAT return…
For an AI assistant helping somebody use Ekwo OS
What an AI assistant needs to set Ekwo OS up for somebody and keep their books: where to read, the commands and the tools, and what it must never do.
Install Ekwo OS on your own Supabase project
From a free Supabase account to a first invoice: one command applies the schema, seeds the country rules and creates the first company — then the four settings no installer can…
Keep the books
The command line, the MCP server an assistant connects to, the TypeScript client and the format libraries.
The command line: ekwo
Every command of ekwo: what it answers, its exit codes, signing in as yourself, keeping books, modules, moving a company, the doctor, and the flags.
The MCP server: an assistant at the books
The Model Context Protocol server for Ekwo OS. It lets an AI assistant work on the books in your own Postgres: read the ledger, raise an invoice, post it, match a payment, pull…
The TypeScript client: @ekwo-ai/core
TypeScript row types and a typed client for the Ekwo OS accounting schema.
Format libraries
One npm package per file format, organised by format and never by country. Factur-X is French and German, UBL is universal, camt.053 is European: a format is not a country. Which…
Countries
A country is a pack of files, not code. How one is written, translated and checked.
Country packs
A country is data. Everything Belgium or France adds to Ekwo — a chart of accounts, journals, VAT codes, the accounts each of them posts to, the boxes of the periodic return — is…
Languages
Accounting is done in a language. A Belgian company keeps its books in French, in Dutch or in German; its accountant reads the chart of accounts in one of them, and the National…
Beyond the first countries
A country is data, not code. A module of code per country breaks at every major version, and one product per market splits the users. Ekwo ships one core and one versioned pack…
Running a business on it
Filing a declaration, a firm and its clients, sharing a document, moving a company, and the modules.
The life of a declaration
A VAT return is not a report. A report is asked for and answers; a declaration leaves the building, an administration keeps a copy, money follows it, and six months later somebody…
An accounting firm and its clients
An accounting firm, a fiduciary, a bookkeeper with thirty customers, a group that keeps the books of its three subsidiaries: somebody who keeps several companies that are not all…
Sharing a document
A company sends an invoice and the customer wants to look at it: what it says, what is still owed on it, what the law put at its foot. Everything needed to answer already exists…
The archive of one company
A firm keeps the books of N companies in one installation, and each of them belongs to somebody. export_company() writes one company out, whole, in a format that needs nothing of…
Modules
The socle is public: companies, accounts, taxes, entries, documents, the reports. What is built beside it lives here, one folder and one schema per module.
Reference
Every table and function, the mapping to the standards, and every design decision with its reason.
Schema
The reference half of this document is generated from the migrations, so it cannot drift from what the database actually holds. Regenerate it with node…
Mapping: Ekwo, EN 16931 and the FEC
Each Ekwo column that has a counterpart in a standard, lined up against it. It lets an integrator write a connector in a day instead of reading the schema and the standards in…
Decisions, and the reason for each
Why Ekwo OS is shaped the way it is: one record per decision, each with its context, the rule it sets and what follows from it, so that a contributor can argue with the reason…
- One installation belongs to one customer
- The surface is closed, not merely empty
- The schema grants its own rights
- A permission is a capability; a role is a preset
- A guard answers true or false, and reads as the schema
- A machine key is a caller narrower than a person
- An invitation names an address, not a user id
- Documents and entries are two joined layers
- Accounts have types and are resolved by role
- Amounts are positive; totals are derived
- An amount is rounded at the decimals of its currency
- A number is drawn at posting, from the country's pattern
- Locks live in the database, and everything raises
- A posted entry is immutable, in an open period too
- A posted document is frozen
- A correction is one gesture
- An append-only audit trail surrounds the ledger
- Reports read the ledger and know no country
- A tax posting carries the account and the box
- One tax engine, several kinds of tax
- Cash-basis VAT waits; exchange differences are realised
- A price that holds its tax is converted per group
- Declaration boxes are data, with no expression language
- A tax follows the territory of the parties
- A country is a pack of data, compiled into SQL
- Ekwo maintains a pack; only an accountant reviews one
- The sources of a pack are a register, not a bibliography
- A pack upgrade is never silent
- A golden year is the contract of a pack
- A country has charts, and a financial statement is data
- Opening and closing are parameters, not code
- The audit file carries opening balances, never posted
- What a country requires on a document is data
- A label is data, and a declared language is a promise
- The chart stays whole; the working list is derived
- Filing cadence is data, counted in months
- A filed declaration is frozen and superseded, not edited
- A deadline is a rule of the country; null is an answer
- A deposit is an event, written from the frozen figures
- A portfolio is what the caller may read
- A company has a profile; its first year is a parameter
- A document is shared by a link that is the whole secret
- A company leaves with its books
- A product is a catalogue entry in the core, not stock
- A counterparty is recognised from learned patterns
- Settling applies identification, offers resemblance
- A bank statement is imported once
- Format libraries are MIT, one package per format
- A statement reader reports and never corrects
- An invoice file is written from the books
- A module has its own schema and posts through a function
- The installer needs only Node and the customer's project
- The MCP server acts as the user
- The command line answers one document and an exit code
- The command line acts as a signed-in person
- The command line computes no amount
- Two install paths make one installation
- ekwo doctor compares against a generated inventory
- A release has a tag, a schema version and a schema floor
- Under load, the plan is the assertion, not the clock
- AGPL core, MIT formats, an operational paid line
- A machine key reaches the API, and is on its own company
Contributing
How a pull request gets in, how a module is written, how the books are tested at volume, how a release is cut.
Contributing to Ekwo OS
Thank you for being here. This file is short and every line of it is a rule that has cost somebody a day.
Writing a module
A module is a Postgres schema beside the socle. assets holds fixed assets and their depreciation; budgets holds a plan and compares it to the ledger. The socle stays in public and…
Books at volume
What is known about how the schema behaves when there is something in it, how it is known, and what is still a guess.
How a release is cut
A release of Ekwo OS is one tag carrying the migrations, the country packs and the npm packages together. There is no "down": a database that has run a migration cannot be walked…
About Ekwo
Why it is being built, what it does not promise, and where to report a flaw.
Why we are building Ekwo
Every business on earth keeps books. The books say whether it is alive, whether it can pay its people next month, whether it can afford to try something. For most small…
What Ekwo is, and what it is not
Ekwo OS is open source data infrastructure: a database schema, rules written as data, format libraries and tools, for businesses and for the accountants who work with them. It is…
Reporting a flaw
Ekwo OS holds books. A flaw here is not a crash, it is a company reading another company's ledger, or an entry that posts without a trace. Please report it, and please report it…
No article matches.