---
title: Accounting processes · full scope
persona: accountant
category: Technical documentation
version: 1.0.0
updated: 2026-09-17
---

# Accounting processes · full scope

This document describes **everything MyFinAI books**, process by process: what triggers it, what
journal entry it writes, what it controls and what evidence it leaves. It's the reference for your
accountant or CPA when they ask "and how exactly does this get recorded?".

**How to read it.** Each process appears as *trigger → journal entry → control*. The account codes
shown are the ones from the **generic business chart** (1000 Bank, 1100 AR, 2000 AP…); the system
does **not** work off fixed codes: it resolves each account **by name** in that workspace's chart, so
a Colombian PUC chart (Decreto 2650 de 1993) uses 1105/1305/2205/2408 and the entry is the same.
Where a mandatory account is missing (withholding, sales tax, exchange difference), the system
**creates it with its name and its legal basis** rather than losing the record.

---

## 1 · The five principles

1. **Exact double entry.** Every entry is born with both sides and is validated before it touches
   the ledger: ΣDebits = ΣCredits, computed in decimal (never floating point). An entry that doesn't
   balance is rejected; there is no "we'll balance it later".
2. **The ledger is the source.** The statements — income statement, balance sheet, cash flow — are
   not assembled on the side: they derive from the ledger. If a number shows on a dashboard, you can
   open it down to the entry behind it.
3. **One workspace, one ledger.** Each company and each household is a workspace with its own
   ledger, isolated in the database row by row (RLS). The business ledger and the household ledger
   never mix, even when the same person signs in.
4. **Each ledger in its own currency.** A workspace keeps its books in its functional currency:
   dollars in Puerto Rico and the United States, pesos in Colombia. A document in another currency
   converts at the official rate **of the document's date** and keeps the original amount, the rate
   and the date.
5. **The AI proposes; a human moves the money.** The agents read, classify, reconcile, compute and
   prepare. No money-moving tool is ever exposed to an agent: payment, collection, tax remittance
   and close are confirmed by a human with sufficient role.

### How a document reaches the ledger

Nothing posts itself. The automatic sweep that runs every six hours **only reads** (it raises alerts,
links identities and understands movements); it never writes an entry. When you press **↻ Post to
the ledger**, the system runs the processes **in dependency order** inside a single transaction:
transactions → invoices → deferred recognition → inventory receipts → bills → collections →
payments → equity → properties → cost of goods sold → payroll. If anything fails to balance,
nothing lands.

**Idempotency.** Each entry is stamped with the type and id of the document that produced it
(`bill`, `invoice`, `bill_payment`, `pay_run`, `depreciation`…), so reprocessing a document can never
book it twice. **Single-shot** entries — loan, lease, tax remittance, manual journal, period accrual
— are recorded every time you confirm them: to correct one you reverse it from the ledger (it stays,
flagged as reversed, never deleted).

---

## 2 · Chart of accounts and opening the books

| Step | What it does |
|---|---|
| **Template** | When the workspace is created the chart is provisioned: **business** (generic), **household**, or **PUC** for a Colombian business (Decreto 2650 de 1993). The choice comes from the workspace's jurisdiction, not from a hand-typed string. |
| **Resolution by name** | The engine looks up "accounts payable", "sales tax", "withholding at source", "exchange difference"… by name, with each country's variants. That's why the same code works on a PR chart and on a PUC. |
| **Cited auto-creation** | If a mandatory account is missing it is created with its name and its law: withholdings payable (2340 in PR, Sec. 1062.03), withholding at source / VAT withholding / local trade withholding (2365/2367/2368 in Colombia), VAT payable (2408), exchange difference (421020 / 530525 in PUC). |
| **Opening balances** | Opening balances enter as one balanced entry against **Opening balance equity (3900)**. It is the only entry allowed to "invent" equity, and it is flagged as the opening. |

---

## 3 · Revenue cycle (what comes in)

### 3.1 Customer invoice
**Trigger:** you issue the invoice (manually, from a subscription, from billed hours, or from the
timesheet reader).

| | Account | Amount |
|---|---|---|
| DR | 1100 Accounts receivable | total (base + tax) |
| CR | 4000/4050/4100 Revenue (each line's account) | base |
| CR | 2300 Sales tax payable (IVU/VAT) | tax on the lines |

**Controls:** a **draft invoice recognizes no revenue**; per-line tax is split out of revenue and if
the chart has no sales-tax account one is created (tax is never "dissolved" into revenue); the header
total is reconciled against its lines.

### 3.2 Deferred revenue (annual plans)
An annual invoice recognizes **deferred revenue** and releases it per period on its recognition
schedule: DR deferred revenue / CR revenue for the month. That's the ASC 606 treatment for what you
billed up front.

### 3.3 Customer collection
**Trigger:** you record the collection (or reconciliation brings it from the bank, or the receipts
mailbox reads it).

| | Account | Amount |
|---|---|---|
| DR | 1000 Bank / deposit account | net received |
| DR | 1355 Tax credits and withholdings suffered (asset) | withholding your client applied |
| DR | Processing-fee expense | gateway fee |
| CR | 1100 Accounts receivable | invoice gross |

**Controls:** withholding suffered is **never lost**: it stays as a tax asset in your favor (1355 in
the PUC); the gross settles the receivable even though less money hits the bank; the matching bank
movement is created (idempotent) so Transactions and the ledger tell the same story; the **collection
voucher** PDF is generated with the workspace's legal name.

### 3.4 Collections
The collections agent prioritizes what's overdue by aging, proposes the reminders and records every
attempt. Bad debt is written off as such (the invoice is not deleted).

---

## 4 · Purchase and payment cycle (what goes out)

### 4.1 Vendor bill
**Trigger:** you upload the vendor bill, it arrives at the `invoicing@` mailbox, you import it from
the DIAN document report, or you capture it by hand. The reader handles PDF, image, Word, Excel, CSV
or the email body, identifies the vendor or consultant **as a single entity** and proposes the
expense account.

| | Account | Amount |
|---|---|---|
| DR | Expense account (lines, or the document's account) | base |
| DR | 2408 Deductible VAT (Colombia) | VAT on the purchase |
| CR | 2000 Accounts payable | total |

If the bill is tied to a **purchase order** whose goods were already received, the entry relieves
**Goods received not invoiced (GRNI 2150)** instead of recognizing the expense again.

**Controls:** a bill **with no expense account is not posted** (the system doesn't guess); the
original document is stored and viewable; duplicates are caught by party + number or amount + date +
party; a draft recognizes nothing; in a currency other than the book currency it converts at the
exact rate of its date.

### 4.2 Purchase order, receiving and 3-way match
The order records what was ordered; **receiving** records what arrived (and capitalizes inventory);
the bill cannot exceed what was received — the 3-way match **blocks**, it doesn't merely warn.

### 4.3 Vendor payment
**Trigger:** a human records the payment (method, account, date and receipt) or fires it through
PayPal Payouts.

| | Account | Amount |
|---|---|---|
| DR | 2000 Accounts payable | gross |
| CR | 2340 Withholdings payable (PR) · 2365/2367/2368 (Colombia) | withholding applied |
| DR | Processing-fee expense | payment-method fee |
| CR | 1000 Bank | net + fee |
| DR/CR | Exchange difference (gain or loss) | if the bill was in another currency |

**Controls:** withholding computes itself (the vendor's percentage, or amounts typed on the payment)
and each type goes **to its own liability**; in Colombia the vendor's single percentage is withholding
at source on the base (2365), never Puerto Rico's withholding; **dual control**: a payment above the
workspace threshold is held for approval before posting; the payment generates the **payment voucher**
PDF (with the receipt attached when it arrived at `paymentReceipt@`) and the remittance advice to the
vendor; the idempotent bank movement is created; the gross settles the payable.

### 4.4 Expense reports (T&E)
Flow: **draft → submitted → approved → paid**. Lines are editable only in draft, and submitting
requires **every** line to be classified. On approval the report **becomes a payable** in the
person's name: the reimbursement then goes out through the same door as any other payment (with its
voucher, its withholding where it applies and its bank movement) instead of a side entrance. The
reimbursement itself is its own entry: DR the liability with the person / CR bank.

Anything capitalizable becomes an **asset** instead of an expense, with the threshold expressed in
the workspace's currency. **Nobody approves their own expense**: the submitter doesn't approve,
unless the owner explicitly enables self-approval for principals; an employee never can. Reopening an
approved report **voids** its payable (or books a reversing entry on reports that predate the payable
link), and it is refused once the report is paid.

### 4.5 Petty cash and cards
Petty cash keeps its own control register with opening, replenishments, expenses, adjustments and
**counts** (book balance vs. counted); it is a control subledger and **does not post to the ledger on
its own**. Cards track charges, payments and statement dates: a charge enters as a movement with
source "card" and credits the card **liability**, and paying it from the bank is a liability transfer,
not an expense (a classic error the system avoids by design).

### 4.6 Corrections and disposals
| Process | Entry |
|---|---|
| **Recategorize** an already-posted movement | the previous entry is marked **reversed** (kept for audit) and a new one is posted |
| **Bad debt** | DR bad-debt expense / CR accounts receivable |
| **Asset disposal** | DR bank (proceeds) + DR accumulated depreciation / CR asset cost, with the gain or loss on sale |
| **Period-end accrual** | DR expense for what was ordered and received / CR accrued liability, with its **automatic reversal** the next day |
| **Tax accrual (Colombia)** | DR the tax expense / CR its own liability — only for the taxes accrued by hand (local trade tax and stamp duty); VAT and withholdings arise from invoices and payments |

---

## 5 · Hours → revenue (professional services)

| Step | What it does |
|---|---|
| **Upload** | The multi-file reader handles real timesheets and remembers the person → consultant mapping. |
| **Double-count guard** | Before you confirm, it detects period totals loaded as a single day, re-uploads of the same file, and hours already loaded; the decision is human and is recorded. |
| **One rate rule** | Bill rate and cost come from a single hierarchy (entry → assignment → consultant → project); only **approved** hours can be billed. |
| **Accrual** | On approval: DR **1250 Work in progress (WIP)** / CR 4050 Hourly revenue, with each entry's share stamped on the journal. |
| **Billing** | When those hours are invoiced the accrual is relieved (DR 4050 / CR 1250) and the invoice posts its own entry — revenue is never counted twice. |
| **Consultant cost** | The consultant's bill enters as a payable and settles the hours it covers. |
| **Margin split** | Per-project compensation splits the margin (sale − costs) among participants and settles as a payable to each of them. |

---

## 6 · Payroll

The regime comes from the **workspace's jurisdiction**, not from a loose flag.

**Puerto Rico / United States.** FICA 7.65% exact on the employee side (6.2% Social Security +
1.45% Medicare), federal and state withholding as a reviewable percentage.

| | Account |
|---|---|
| DR | Payroll expense (gross) |
| CR | Payroll withholdings payable (federal, state, FICA) |
| CR | Payroll payable (net) |

**Colombia (Ley 100 de 1993 and the Labor Code).** Employee: health 4% + pension 4% + withholding at
source. Employer: health 8.5%, pension 12%, occupational-risk insurance (Decreto 1607 de 2002) and
payroll levies; statutory benefits: severance 8.33%, severance interest ≈1%, service bonus 8.33% and
vacation 4.17%. Transport allowance where it applies.

| | Account |
|---|---|
| DR | 5105 Personnel expense |
| CR | 2370 Social security payable |
| CR | 2365 Withholding at source payable |
| CR | 2610 Statutory benefits payable |
| CR | 2505 Payroll payable (net) |

Paying the **net** is its own entry (DR payroll payable / CR bank) and a human fires it. The employee
portal shows their stub with their own country's concepts (federal/state/FICA and W-2 / 499R in PR;
health, pension and withholding with the **income and withholding certificate, DIAN form 220**, in
Colombia).

---

## 7 · Inventory and operations

| Process | Entry |
|---|---|
| **Goods receipt** | DR Inventory / CR 2150 GRNI (goods received not invoiced) |
| **Cost of goods sold** | DR 5000 Cost of goods sold / CR Inventory |

On-hand is derived from the inventory movements (not from a parallel counter) and valuation is
**weighted average**, maintained by the database itself on every movement. A sale generates its
inventory movement from the invoice line (idempotent per line), and the operations module adds
multi-location, demand (velocity, ABC, days of cover), suggested replenishment, sales orders, lots
with expiry and inter-location transfers.

---

## 8 · Net worth: assets, property, loans and leases

| Process | Entry / treatment |
|---|---|
| **Capitalization** | An expense above the threshold (expressed in the workspace's currency) enters as an **asset**, not an expense. |
| **Depreciation** | Straight line with a catch-up model: each run posts exactly what's missing for accumulated depreciation to be correct as of the date (DR depreciation expense / CR accumulated depreciation), idempotent per asset. |
| **Properties** | The property subledger (rent, expenses, mortgage) is carried to the ledger, so net worth and the P&L tie to the books. |
| **Loans** | Disbursement: DR bank / CR loan payable. Payment: DR loan (principal) + DR interest expense + DR fees / CR bank. |
| **Leases** | Recognition of the right-of-use asset and its liability, and each payment split into principal and interest. |
| **Shareholder capital** | Contributions and distributions to the ledger (DR bank / CR equity; DR distributions / CR bank), only after the opening entry so history isn't double-counted. |

---

## 9 · Bank, transactions and reconciliation

| Step | What it does |
|---|---|
| **Intake** | You import the statement (CSV or PDF, read by AI) or connect the bank through **Plaid** — MyFinAI never touches your credentials. |
| **Idempotency** | Every movement carries a fingerprint; re-importing the same statement duplicates nothing. |
| **Understanding** | A deterministic reader separates merchant, channel, location, cardholder and reference out of the bank descriptor, and ties it to the registered counterparty (vendor, customer, consultant, employee, household member) with its history. |
| **Categorization** | A workspace rule or an AI proposal; the human confirms. |
| **Entry** | DR/CR by the movement's direction and account, with dimensions (class, location, department) when defined. |
| **Transfers** | Movements between your own accounts are paired and posted as a transfer, not as income or expense. |
| **Bank reconciliation** | You tick what appears on the statement, record the statement balance and date, and reconcile; each account shows "reconciled through" and what's pending since. |
| **Subledger reconciliation** | A report compares receivables against open invoices, payables against open bills, inventory against its valuation and each bank against its balance, and flags any difference above one cent. |

---

## 10 · Multi-currency

- **Initial recognition:** the document is recorded in the book currency at the spot rate of its
  date — the official TRM for the Colombian peso (Banco de la República / Superintendencia
  Financiera public series) and ECB reference rates for the rest; between two non-dollar currencies
  the cross goes through the dollar. It never approximates: if the rate is missing, the document is
  flagged for review instead of being booked wrong.
- **Two guards on the rate:** a stored rate only serves a date if it is from that day or up to seven
  days earlier (otherwise the exact one is fetched — a July receipt would otherwise take June's
  rate), and each currency has a sanity band: an out-of-band reading is rejected rather than allowed
  to corrupt balances.
- **Realized exchange difference:** on payment or collection, the difference between the document's
  rate and the payment-day rate goes to exchange gain or loss (in a PUC chart, 421020 / 530525 —
  Decreto 2650 de 1993).
- **Unrealized difference:** revaluation of bank balances held in a currency other than the book
  currency is proposed in dry-run mode and posted when a human approves it.
- **Basis:** IFRS for SMEs Section 30 (par. 30.7) and Decreto 2420 de 2015 in Colombia, with tax
  articles 21-1 and 288 of the Tax Statute for the tax effect; ASC 830-20-30-1 in Puerto Rico and the
  United States.

---

## 11 · Taxes by jurisdiction

MyFinAI only shows — and only allows — what applies to the workspace. The rule is single: Colombia
is country CO **or** currency COP; empty is treated as Puerto Rico.

**Puerto Rico.** Sales & use tax (IVU) per invoice line to the sales-tax liability; services
withholding (Sec. 1062.03) on payment → 2340; municipal license and income-tax estimates from the
posted ledger; 480.6 and IVU exports; drafts of 941, 499R-1B and W-2PR from the pay runs; the **State
Insurance Fund (CFSE)** policy and payroll declaration (Ley 45 de 1935) with its August 15 deadline.

**Colombia.** VAT (19%/5%/exempt) with deductible VAT on purchases; withholding at source, VAT
withholding and local trade withholding each to its own account; a catalog of 16 taxes with code,
legal basis and PUC account; the DIAN calendar and document-report import. Electronic invoicing with
CUFE is modeled but **does not transmit** without the client's credentials and numbering resolution.

**Tax remittance.** Paying the tax or withholding to the authority is its own entry (DR the tax
liability / CR bank) and it only accepts a **tax liability** — you cannot "remit" a vendor as if it
were a tax. Every tax has its account and its law cited in the **regulatory framework** kept next to
the code (`docs/regulatory-framework.md`).

---

## 12 · Close

| Step | What it does |
|---|---|
| **Close status** | The pre-close checklist: transactions, invoices and bills still unposted as of the cutoff, the trial-balance delta, the period's result, and whether the period is already closed. |
| **Close** | Posts what's pending and **locks the period**. It refuses to close an unbalanced ledger, and warns — letting you override with judgment — when more than 5% of the period's movements are unreconciled. An entry dated on or before the lock is rejected; so is reversing an entry from a closed period. |
| **Period lock** | The lock date lives in the workspace settings and must be in the past (a future date would freeze current operations). |
| **Year-end close** | Rolls the year's result into retained earnings, with a **dry run** before posting, and moves the lock to December 31 — never backwards. |

---

## 13 · Controls and audit

- **Balance verified by the database.** On top of the engine's validation, the database holds a
  constraint that fires **at commit** and rejects any unbalanced entry, even one that arrived outside
  the engine (a bad migration, a direct insert, a new bug).
- **Hash chain.** The audit log chains each event to the previous one
  (`hash = sha256(previous_hash ‖ payload)`): altering a record breaks the chain and is detected.
  Verification reports the **linkage** (authoritative) separately from content re-hashing
  (indicative, because the database's JSON form isn't byte-reproducible). The log has UPDATE and
  DELETE **revoked** at the database level.
- **Append-only logs.** Agent actions and the identity log are never edited or deleted: a correction
  is a new event pointing at the previous one.
- **Dual control.** Payments above the workspace threshold wait for a second human's approval before
  posting, and what holds them is the **database itself** (a trigger marks the payment as pending on
  insert), not just the application.
- **Segregation of duties.** Nobody approves their own expense or their own reimbursement.
- **Per-workspace isolation.** Row-level security in the database, with the session bound to the
  active workspace; platform-wide aggregators are sealed when the active workspace is a demo.
- **Assurance harness.** Before every deploy a battery of read-only checks runs against real data:
  double entry per entry and globally, subledgers against the ledger, every payment with its bank
  movement and its withholding, identity uniqueness, hours with their key to the consultant, and the
  document currency with its rate. A failure **blocks the deploy**; "0 cases" is reported as empty,
  never as passed.
- **Recovery drill.** The encrypted backup is restored into a throwaway database and the invariants
  are validated (tenants ≥ 1, ΣDR − ΣCR = 0.00) before it counts as good.

---

## 14 · Statements, reports and documents

| Output | Where |
|---|---|
| **General ledger** and each entry's detail | Accounting → Ledger (clicking an entry opens its lines) |
| **Trial balance** (full chart, posted only, zero-balance accounts kept) | Accounting → Ledger (✓ balanced seal) |
| **Income statement** with period, prior comparable, 12-month trend and margins | Financials |
| **Balance sheet** and **cash flow**, the latter both **direct and indirect** (the indirect one starts from net income, adds back depreciation and the changes in receivables / inventory / payables) | Financials |
| **IFRS-format statements (Colombia)**: statement of financial position (current / non-current), statement of comprehensive income, statement of changes in equity, and notes | Financials (Colombian workspaces) |
| **P&L by dimension** (class, location, department, project, fund) and by date range | Reports |
| **Consolidated** report across group companies | Consolidation |
| **Aging**: what's overdue by bucket and the next collection step | Collections and Payables |
| **Tax**: returns, fiscal liabilities per account (with the detail per withholding subject) and estimates | Tax |
| **Subledger reconciliation** against the ledger and **FX exposure** | Reconciliations and Tax |
| **Documents**: invoice PDF, payment voucher, collection voucher, hours certification | In each module, with the workspace's legal name and logo |
| **Exports**: statements as PDF and Excel, 480.6 / IVU (PR), bank payment batch, CO tax catalog, CSV of any table | Financials, Tax and Payables |

Every table in the app carries search, filters, sorting and **totals of the filtered set**; every
tile and KPI drills down to the data behind it.

---

## 15 · The twelve agents and their boundary

**Cónclave** (orchestrates), **Lente** (reads documents), **Libro** (bookkeeping), **Espejo**
(reconciliation), **Cobro** (collections), **Mecenas** (payments), **Salario** (payroll), **Fisco**
(tax), **Caudal** (cash flow), **Guardián** (anomalies), **Norte** (plan) and **Mayor** (close and
audit).

What they **do**: read, extract, classify, match, compute, alert and prepare the action. What they
**never** do: move money, approve their own proposal, file with an authority, or alter a closed
entry. Every intervention is recorded in the action ledger with its value and the time saved.

---

## 16 · Declared limits

What MyFinAI does **not** do today, stated plainly:

- **It does not file with authorities.** It prepares drafts (941, 499R-1B, W-2PR, 480.6, IVU, CFSE
  declaration, DIAN calendar); filing is done by a person on the authority's portal.
- **It does not transmit DIAN electronic invoices.** The data model and the CUFE are ready;
  transmission needs the client's credentials and numbering resolution.
- **It is not tax or legal advice.** It computes and cites the current rule with its official source;
  your accountant or CPA validates and signs.
- **It does not move money on its own**, not even on an instruction written inside a document:
  confirmation always comes from a person in the app.
- **Colombian payroll exemption (Tax Statute art. 114-1):** CO payroll currently charges full health
  and payroll levies; the exemption for workers under 10 minimum wages needs the taxpayer type and
  the year's minimum wage declared — it's on the backlog.
- **A few secondary flows** (shareholder capital, asset disposal, bad debt, period accrual, subledger
  reconciliation) still use fixed codes from the generic chart instead of resolving the account by
  name; on a PUC chart, check the account before confirming. It is identified and queued for
  generalization.

---

## 17 · Where each process lives

| Process | Code module |
|---|---|
| Journal engine, all `post_*`, revaluation, year-end close | `app/posting.py` |
| Depreciation | `app/depreciation.py` |
| Book currency and rates | `app/fx.py` |
| Jurisdiction, calendar and tax liabilities | `app/compliance.py` |
| Colombian tax catalog | `app/co_taxes.py` |
| Document reading (bills, receipts, payment receipts, timesheets) | `app/felipe.py`, `app/ap_intake.py`, `app/expense_intake.py` |
| Hours, rates and duplicates | `app/hours_rates.py`, `app/hours_dupes.py` |
| Bank-movement counterparty | `app/txn_parse.py`, `app/txn_enrich.py` |
| Single identity for people and companies | `app/identity.py` |
| PDF vouchers and advices | `app/payments.py` |
| Assurance checks | `infra/assurance.py` |

---

For the detail of every rule cited — article, effective date and official link — see the
**regulatory framework** kept with the code (`docs/regulatory-framework.md`). For the step by step of
your role, open your manual in the [Documentation center](index.en.html).