---
title: How Balsa works
summary: A financial system you can talk to without asking it to do the math. Evidence comes in, becomes facts, and feeds a calculator that does not guess.
---

## Why it is not a spreadsheet

A spreadsheet is a useful calculator. It is a poor place to keep the history of
a company. The logic is hidden in cells, the source for a number is easy to
lose, and the person who made a judgment often becomes the only person who can
explain it.

Balsa starts with the evidence a company already produces and the decisions
its people make. It stores those inputs as records, then calculates from them.
You do not maintain a grid of formulas. You ask a question, provide a source, or
settle an ambiguity. The system keeps the resulting state and can explain how it
got there.

Language models handle interpretation and explanation. Deterministic code
handles the math. The model is never the calculator or the database.

## The operating loop

Evidence arrives and observations are extracted. The model interprets them
against what it already knows about the company. If the treatment is clear, the
result becomes Company State. Otherwise it becomes a question for you. Your
answer is saved and the deterministic engine turns Company State into
schedules, statements, and a forecast.

The same loop handles a bank CSV, an invoice PDF, a management-fee agreement, or
a sentence you type into the composer. You never pick a workflow first.

## Accounting starts with economics

Traditional accounting software starts with entries in a ledger. That is useful
for reporting, but it leaves too much of the underlying business outside the
system. A contract, an obligation, a payment, and the policy used to allocate it
are all part of the explanation for a number.

Balsa records that economic state first. It learns who owes what, which
company bears a cost, when an obligation is due, and what judgment governs the
treatment. The ledger and statements follow from that state.

That makes the accounting auditable in a practical sense. When a number changes,
you can follow it back through the schedule to the business fact and the source
that supports it.

On screen the layers read as ink and pencil. Actuals and anything you have
approved are set in ink. Forecasts and unconfirmed facts are pencil. The one
thing waiting on you carries a highlighter mark.

## Reporting and forecasting

Most FP&A tools treat actuals as an import and forecasts as a separate planning
model. That makes the forecast easy to edit, but it also makes the connection
between what happened and what you expected hard to preserve.

Balsa keeps actuals and forecasts in the same operating model. Bank
activity and source documents establish what happened. Your decisions and
policies explain it. The forecast then extends that known state into the future.
It is not a second spreadsheet that someone has to reconcile at the end of the
month.

A forecast can still contain assumptions. The difference is that each
assumption sits beside the state it extends, with a clear line between a known
actual and an estimate. When an actual arrives, the model can show what changed
and why.

## Provenance

Every important piece of state records where it came from: supplied by the CFO,
extracted from a document, observed at the bank, imported from QuickBooks,
inferred by the model, confirmed by the CFO, or calculated by the system. An
inference never silently becomes a confirmed fact. When you ask why a number is
what it is, the answer walks the chain from the statement line to the schedule,
to the obligation, to the decision that allocated it, to the original file.

One distinction the system holds carefully: who paid is not the same as who
bears the cost. The management company may pay a $10,000 legal bill while the
funds economically bear most of it. The result is an expense for the company,
amounts due from each fund, and a single cash movement, with the allocation
traceable to the policy or decision that produced it.

## Getting started

Balsa is self-hosted software. You install the application on your computer or
on a server you control; this website is its introduction and documentation.
The application is currently in private testing. You need repository access
before the installation commands below will work.

### What you need

- Git to download the application source.
- Node.js 22 or newer and pnpm 10 or newer. The repository pins its pnpm version.
- Docker for the included PostgreSQL database, or a PostgreSQL database you
  already manage.
- An OpenAI or OpenRouter account and an API key for your selected provider.
- Storage for uploaded documents and the database. Keep that storage persistent
  if you run Balsa on a server.

You will use a terminal and edit a local configuration file. You do not need to
write application code. Model-provider usage is billed by your provider.

### Install and configure

Once you have source access, clone the application and run its setup command:

```bash
git clone https://github.com/tdavidson/balsa.git
cd balsa
pnpm run setup
```

Setup installs dependencies, creates a private `.env` file if needed, generates
missing application secrets, prepares file storage, starts the included database
when applicable, and applies migrations. Existing configuration is preserved.
If you use your own PostgreSQL database, configure `DATABASE_URL` in `.env` and
run `pnpm run setup -- --no-docker` instead.

Open `.env` and use `.env.example` as the reference. Select OpenAI or OpenRouter
and add that provider’s API key. Choose the access mode for your installation:
email/password sign-in for a shared installation, or disabled authentication for
a private local evaluation. Disabled authentication does not protect the app
from other people on the network. Keep keys and private configuration out of Git.

See [the installation guide](/docs/getting-started/) for authentication and
container setup, and [configuration](/docs/configuration/) for each setting.

### Check the setup and start Balsa

```bash
pnpm run doctor
pnpm dev
```

Resolve any doctor failures, then open `http://localhost:3000`. This starts the
local development application. For a persistent server installation, follow
[operating an installation](/docs/operations/) for deployment, backups, and
upgrades.

### Use your first company

Start with a small set of evidence that you can check. The synthetic files in
`fixtures/company-zero` are a useful way to try the workflow before uploading
your own company’s documents.

1. Open your company and establish its starting cash, period, and currency.
   An opening balance is a starting point; reconcile it against bank evidence.
2. Add a contract, invoice, or transaction export, and explain the business
   context in the composer. Balsa interprets the source and proposes facts.
3. Review **Waiting on you**. Confirm correct interpretations, correct unclear
   ones, and reject unsupported suggestions before relying on the results.
4. Inspect the cash outlook and its assumptions. Follow a number back to its
   source, then reconcile actual payments with what you expected.
5. Ask a question or propose a change. Review the resulting decision and its
   effect on the forecast before applying it.

Continue with [your first financial review](/docs/first-review/) for the full
workflow, or [the worked example](/docs/worked-example/) to follow one agreement
through review, forecast, and payment.

## Building the language for your company

Anything that feels like configuring finance software should be a sentence
instead. Not an allocation settings screen but
`Allocate Carta 60% Fund II, 30% Fund III, 10% management company going forward`.
Not editing forecast cells but
`Assume we hire a finance contractor in January at $6k a month`. Not configuring
recurring revenue but `Fund III pays us $50k quarterly through the end of 2028`.
The agent turns intent into Company State.

**Decisions** answer one question once. When the system asks how to treat
something, select the question under Waiting on you and answer it naturally in
chat. The answer is remembered and applied to similar evidence later.

**Policies** are standing judgment.
`policy: Contractor timing => Recognise on payment date` tells it how to read a
whole class of evidence, and the policy is cited whenever it is used. Decisions
that keep recurring are candidates for policies.

**Names** matter. Use the same name for a fund, customer, or vendor each time,
and the system resolves future references to the same entity.

**Knowledge documents** hold the rest: how the company operates, its accounting
preferences, its forecast philosophy. Ask it to draft them from what you have
uploaded, then correct them in your own words.

**An example model** teaches style. Hand it a spreadsheet you already use and it
learns the structure and formatting: the line items, the ordering, the units and
sign conventions. Future outputs follow that shape. The example changes how
results are presented, never how they are calculated.

Work in small steps and correct it early. A handful of decisions and policies in
the first month do more for accuracy than any amount of setup.

## What it should be able to tell you

- How much management-fee revenue did we earn this month, and how much cash did
  we receive?
- What receipts do we expect next quarter?
- What expenses did we incur, what did we actually pay, and what remains unpaid?
- Which expenses were allocated to funds, and how much do the funds owe us?
- Why is professional-services expense this amount?
- Which parts of next year's forecast are contractual, and which are
  assumptions?
- What questions still need my input?
- What happens if Fund II stops paying management fees next year?

The hypothesis behind all of it: a CFO should be able to give an intelligent
system the same evidence, context, policies, assumptions, and judgment they use
themselves, and have it continuously maintain an auditable financial model
without building or maintaining that model in Excel.

## About Taylor

Balsa is built by Taylor Davidson. Taylor helps founders and investors
create and use financial models through Hemrock, formerly Foresight, whose
template models have been used by more than fifty thousand people worldwide
since 1998. He serves as fractional Chief Financial Officer for Laconia Capital
Group, an early-stage venture firm, running fund administration, capital
planning, investor reporting, and management-company finance.

That work is where Balsa comes from: years of watching the same evidence
get re-keyed into models by hand, and the conviction that a company's financial
operations should be learned from what it already produces rather than
configured up front. He teaches financial modeling, venture fund forecasting,
and cap tables and exit waterfalls, and lives in Pittsburgh.

More at [taylordavidson.com](https://taylordavidson.com).