Core concepts

A short tour of the ideas that make IrisBooks make sense. Once these click, both the CLI and the web app feel obvious.

Files are your books

There is no hidden database. A book is a folder on disk, and the files in it are your accounting records. You can read them, edit them, diff them, back them up, and hand them to your accountant with any tool you already use. IrisBooks (the CLI and the web app) are just two lenses onto that folder.

One book = one business. A sole proprietor with a side business keeps two books; that’s normal.

your-book/
├── config/
│   ├── book.yaml                 # identity, region, fiscal year, currency
│   ├── chart-of-accounts.yaml    # your accounts
│   └── rules.yaml                # optional categorization hints
├── raw/                          # source documents (CSVs, PDFs, receipts)
├── journals/<fy>/<mm>/           # one Markdown file per entry
├── assets/YYYY/                  # fixed assets (for depreciation)
├── notes/                        # working notes, todos, decisions, parse caches
└── compiled/                     # AI-generated reports (regeneratable)

The full layout is in the Book file-format reference.

Journals — your transactions

Every transaction is one journal entry, stored as a Markdown file with a YAML header at journals/<fy>/<mm>/YYYY-MM-DD-<payee>-NN.md (fiscal year, then the date’s calendar month — for a calendar-year book that’s just the date’s own digits). It’s double-entry: the debits and the credits must balance.

---
date: 2026-05-04
payee: EXAMPLE.COM
status: draft
lines:
  - account: 資産:売掛金
    debit: 89790
  - account: 資産:事業主貸
    debit: 10210
  - account: 収益:売上
    credit: 100000
---

May invoice for the EXAMPLE.COM redesign engagement.

The text below the --- is free-form: write why the transaction happened. The filename is the entry’s permanent identity — it stays put even as the entry’s status changes.

Accounts — the chart of accounts

Your accounts live in config/chart-of-accounts.yaml, each with a hierarchical path (資産:普通預金, 費用:消耗品費) and a type (asset / liability / equity / income / expense). Journals reference accounts by path. The “normal side” of an account (whether debits increase it) is derived from its type — you don’t declare it.

You can give accounts aliases so journals can reference them in another language or a shorter name. Don’t invent account paths inside a journal — add the account to the chart first (or ask your AI to propose it in notes/open-questions.md).

Status — the lifecycle of an entry

Every journal carries a status:

This is the single most important rule to remember: iris balance, the P&L, and the balance sheet include only posted entries. A draft entry will not show up in your trial balance until someone promotes it. Promote with iris post or by editing the field.

(You’ll also see a closed status — that’s any entry whose date falls in a sealed fiscal year. It’s derived, never stored in the file: the web app, iris search, and the remote connector all display it, and reopening the year makes the stored status visible again. The web app additionally shows an incomplete marker for drafts that aren’t ready.)

Reports are computed, never stored

IrisBooks never stores a “balance sheet file”. Reports are derived from your posted journals every time you ask:

• Trial balance (試算表) — iris balance or iris report tb
• Profit & loss (損益計算書) — iris report pl
• Balance sheet (貸借対照表) — iris report bs
• General ledger (元帳) for one account — iris report ledger --account …

Because they’re computed, they’re always consistent with the underlying entries. The web app renders the same reports graphically and can export each to CSV.

Raw documents and cross-references

Anything under raw/ — bank CSVs, receipt photos, PDF invoices — is the evidence behind your entries. A journal points at its source via an attachments entry, and you can walk that link in both directions:

• From a journal, see which documents it cites.
• From a document, see which journals cite it (iris show <path>, or the “Cited by” panel in the web app’s Raw documents browser).

This two-way cross-reference is one of the three things Japan’s 優良電子帳簿 status requires — see Japan tax & compliance.

Sync — the three ways to work

The same book can live in three arrangements. You don’t choose a “mode”; you just use more or fewer of the features:

• Offline. Files only, no server, no account. You validate and report locally. Maximum privacy, zero network.
• Files + Cloud. Your local files plus a cloud mirror (sign in with iris api login). You edit locally and run iris sync to push and pull. The web app, multi-device access, collaboration, and timestamped history all live on the cloud side.
• Cloud-only (typical for accountants). No local folder — you work entirely in the web app against the server.

Sync is explicit: nothing uploads until you (or your AI) run iris sync, iris post, or click Sync in the app. There is no background watcher silently shipping your files. An owner syncing from their laptop and an accountant working in the web app meet at the same server book.

Seals — closing a year, visibly

At year-end you seal a fiscal year: the server marks the period as closed — by whom, and when — and locks it. A sealed year refuses every write, on every surface: iris post refuses locally, sync pushes are rejected by the server, and the web app and remote connector refuse edits too. Its entries display as closed everywhere.

To amend a sealed year you reopen it with iris reopen: the seal is unlocked (writes are accepted again) and every edit made while reopened is permanently flagged as a post-seal edit in the audit trail — so a closed year that was later touched can never look untouched. When you’re done, re-seal; the new seal supersedes the old one in the audit chain. Sealing also builds a downloadable archive snapshot of the year — your files stay in the working tree untouched. See Year-end close.

The durable history (correction/deletion record)

With cloud sync, the server keeps an append-only log of every change to every file — who changed it, when, and what it was before. This is the 訂正・削除の履歴 (“record of corrections and deletions”) that Japanese law requires for 優良電子帳簿. View it with iris api history or in the web app’s Activity timeline and per-journal History panel.

Local git history does not count for this — only the server-side record is auditor-trustable, which is why the durable history lives on the cloud side.

The two lenses, side by side

They are not either/or — most owners use both: the CLI + AI to enter data fast, the web app to review, report, and collaborate.

Next: Bookkeeping with the CLI and your own LLM or Using the web app.