RoboLedger Demo Walkthrough

RoboLedger Demo Walkthrough

The fastest way to see RoboLedger work end-to-end. Run one command, get a fully-populated tenant — 16 months of synthetic books for a consulting firm, with a filed FY annual report, mapped Chart of Accounts, depreciation and prepaid schedules, and exactly one period ready for the AI-driven close workflow.

No QuickBooks account needed. No Intuit Developer setup. No ngrok tunnel. The demo emulates data arriving the same way a real QB sync produces it — same typed event vocabulary, same OLTP shape, same materialized graph — without the OAuth and external-API requirements. It's the canonical surface for prospect demos, frontend evaluation, regression testing, and learning the feature set.

Table of Contents

• Overview
• Prerequisites
• Quick Start
• What Gets Created
• The Company — Cascade Advisory Group
• The Filed Annual Report
• The Close-Period Workflow
• The Rule Engine
• The Mapping View
• Schedules
• Frontend Tour
• Exploring with MCP
• Resetting the Demo
• Customization
• Comparison to the QuickBooks Workflow
• Next Steps

Overview

When just demo-roboledger finishes (~60 seconds), the tenant has:

• A new entity (or one provisioned into an existing graph) modeling Cascade Advisory Group LLC, a 3–5 person boutique consulting firm
• 16 months of business data on a rolling window ending at the current month, so the demo always covers "recent history" regardless of when you run it
• A clean 27-account Chart of Accounts with 100% renderable mapping coverage to rs-gaap
• ~305 typed business events (invoice_issued, payment_received, bill_received, bill_paid, journal_entry_recorded) emulating data arriving via the same HTTP API a real adapter uses
• ~132 discharge chains linking payments to their originating invoices/bills (REA duality)
• A fiscal calendar with the prior month's prior month closed and the last completed month queued — exactly one period ready to close
• 6 schedules: 2 depreciation, 4 prepaid amortization, staggered across the window
• 4 policy documents (close procedures, depreciation, prepaid, revenue)
• An FY annual report — generated, packaged, and filed as a complete Report-Block lifecycle demonstration

After setup, the natural flow is:

1. Open the frontend, browse the entity, mapping coverage, and the filed annual report
2. Drop into the AI close workflow on the queued period via Claude Desktop or any MCP client
3. Inspect the rule engine output (the demo ships 38 validator checks; first run passes all 38)
4. Query the graph directly to explore the data shape

Prerequisites

Just the local stack:

git clone https://github.com/RoboFinSystems/robosystems.git
cd robosystems
just start

You don't need Intuit credentials, ngrok, or any external service. The demo is fully self-contained and runs entirely against the local stack.

If you want to drive the AI close workflow at the end, you'll also want an MCP client (Claude Desktop, Claude Code, or a custom client). That's optional — everything else inspects via the frontend or the API.

Quick Start

# In one terminal — start the backend stack if you haven't already.
cd robosystems
just start

# In another terminal — start the frontend (optional, but recommended for the tour).
cd ../roboledger-app
npm run dev

# Run the demo. ~60 seconds.
cd ../robosystems
just demo-roboledger

Output includes the API key + user credentials and the graph id of the new tenant — copy them or read them from .local/config.json. The last line prints the exact MCP prompt to use for the AI close on the queued period.

To load the demo into an existing graph (e.g. on a user / graph you've already provisioned):

just demo-roboledger <graph_id>

To validate the data without writing anything:

just demo-roboledger --dry-run

What Gets Created

Component	Count	Detail
Chart of Accounts	27	Clean asset / liability / equity / revenue / expense breakdown with realistic small-business categories
Agents	17	6 customers + 8 vendors + 2 employees + 1 government (IRS). Same shape a real QB sync produces.
Business events	~305	Typed event stream: invoice/payment pairs, bill/payment pairs, opening-balance and payroll journal entries. Mirrors the exact event vocabulary QB ingestion emits.
Discharge chains	~132	payment_received → invoice_issued and bill_paid → bill_received links — the REA duality that drives open-AR / open-AP aging
CoA → rs-gaap mappings	27	100% coverage, all renderable under the active Reporting Style
Fiscal calendar	1	closed_through = month_before_last, close_target = last_completed_month
Fiscal periods	16	One per month, first 14 closed, last 2 open
Schedules	6	2 depreciation (computer equipment, office furniture) + 4 prepaid amortization (insurance, software licenses, AWS prepay, etc.)
Schedule facts	mixed	Historical (pre-target, baked into opening balances) vs in_scope (target onward, surfaced by the close workflow)
Documents	4	Markdown policies: close procedures, depreciation, prepaid, revenue recognition
Filed FY report	1	Annual report — facts generated, package assembled, lifecycle stamped filed. Demonstrates the full Report-Block lifecycle end-to-end.
Rules	38	Validator + arithmetic checks; demo data is intentionally clean, so all 38 pass on first run

Every event flows through the same HTTP API the frontend UI and MCP tools call. The only direct-DB path is _reset.py, used to clean up between re-runs.

The Company — Cascade Advisory Group

The demo emulates Cascade Advisory Group LLC, a 3–5 person boutique management consulting firm. Grounding the data in a believable business shape makes the close workflow, the report numbers, and the policy documents all read as coherent — closer to what a real customer would walk in with than abstract test fixtures.

Aspect	Value
Service lines	Three revenue streams: general consulting, strategy advisory, implementation services
Monthly revenue	$18K – $22K, with seasonality
Customers	6 named customers across professional-services verticals
Vendors	8 named vendors: landlord, payroll provider, AWS, software licenses, etc.
Employees	2 — driving the monthly payroll JE
Key expenses	Payroll ($9,500/mo), rent ($2,500/mo), software ($450/mo), cloud hosting ($180/mo), professional services
Fixed assets	$4,800 computer equipment + $1,500 office furniture (driving depreciation schedules)
Prepaids	$1,200/yr insurance + $300/yr software + $600/yr AWS prepay (driving amortization schedules)

The 16-month rolling window means the demo is always running a business — you're never in "future data" or "ancient history." That matches how real customers experience the product.

The Filed Annual Report

The most material output: a fully-rendered FY annual report, filed, demonstrating the Report-Block lifecycle from generation through packaging through filing.

To inspect:

API_KEY=$(jq -r .api_key .local/config.json)
GRAPH_ID=$(jq -r '.graphs | keys[0]' .local/config.json)

# List reports
curl "http://localhost:8000/v1/graphs/$GRAPH_ID/reports" \
  -H "X-API-Key: $API_KEY" | jq '.'

# Inspect facts on the filed report
docker exec robosystems-pg psql -U postgres -d extensions -tAc "
  SET search_path TO $GRAPH_ID;
  SELECT s.block_type AS statement,
         REPLACE(e.qname, 'rs-gaap:', '') AS concept,
         ROUND(f.value::numeric, 2) AS value
  FROM facts f
  JOIN fact_sets fs ON fs.id = f.fact_set_id
  JOIN elements e ON e.id = f.element_id
  JOIN structures s ON s.id = fs.structure_id
  WHERE fs.report_id = (SELECT id FROM reports WHERE filing_status = 'filed' LIMIT 1)
  ORDER BY s.block_type, ABS(f.value) DESC;"

You'll see facts distributed across all four statements (Balance Sheet, Income Statement, Cash Flow, Statement of Equity). The trial balance balances to the cent, retained earnings rolls forward correctly, and dividends/distributions net out of equity as expected.

In the frontend, navigate to Reports → the filed FY report → view the rendered BS / IS / CF / SE statements with drill-downs into Information Blocks for supporting detail.

The Close-Period Workflow

The fiscal calendar is initialized so the prior month's prior month is closed_through and the last completed month is the close target — exactly one period ready to close. This matches what a real business onboarding mid-year does: wall off pre-onboarding periods as historical, start running the close workflow from a clean boundary.

The natural way to drive the close is via the AI workflow. With Claude Desktop or any MCP client connected to the local RoboSystems MCP server:

1. Paste the prompt from examples/roboledger_demo/prompt.md (or copy the close-month-specific prompt the setup script prints at the end)
2. Ask: "Close the books for the most recent completed month."

The agent walks through the standard 8-step close checklist (loaded into the tenant as the close procedures document):

1. Review the active close procedures — search-documents finds the checklist
2. Check period status — get-period-close-status shows the target month with any pending obligations
3. Resolve open obligations — schedules with in-scope facts pending approval; the agent proposes journal entries to record them
4. Generate and review month-end accruals — depreciation (PP&E rollforward), prepaid amortization (insurance, software, AWS)
5. Validate — evaluate-rules runs the 38 structural and arithmetic checks
6. Close the period — close-period flips the boundary forward
7. Generate the close report — month-over-month variance + balance sheet snapshot
8. Document — append any close notes to the documents corpus

Each step exercises a different RoboLedger surface: documents, schedules, journal entries, rule engine, period management, reports. The agent's run is auditable — every action is a typed operation in the event log, replayable on demand.

If you'd rather drive manually, the same operations are exposed via REST under /extensions/roboledger/{graph_id}/operations/.

The Rule Engine

The demo ships with 38 rules covering structural validity (no cycles in the CoA, unique qnames, leaf accounts have classifications), arithmetic checks (debit-credit balance per entry, period rollforward integrity, accounting equation), and policy adherence (rolling forward accumulated depreciation, prepaid amortization completion).

To run:

curl -X POST "http://localhost:8000/extensions/roboledger/$GRAPH_ID/operations/evaluate-rules" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.result | {passed, failed, total, by_severity}'

First-run output:

{
  "passed": 38,
  "failed": 0,
  "total": 38,
  "by_severity": {"error": 0, "warning": 0, "info": 0}
}

The demo data is intentionally clean — the rule engine isn't supposed to find issues. The value is showing the shape of the rule engine output and the breadth of what it covers. Once you start the close workflow and the agent proposes adjustments, the rule engine catches anything that would break the books.

To see what's actually being checked:

curl "http://localhost:8000/v1/graphs/$GRAPH_ID/rules" \
  -H "X-API-Key: $API_KEY" | jq '.[] | {name, severity, target_kind}' | head -40

The Mapping View

100% of the 27 CoA accounts are mapped to rs-gaap reporting concepts, and 100% of those mappings are renderable — they target concepts the active Reporting Style's structures actually walk.

From the frontend, Chart of Accounts shows each account with its rs-gaap target alongside. From the MCP:

list-mapping-structures
→ returns the CoA→rs-gaap mapping structure id

get-mapping-summary --mapping_id=<id>
→ {
    "total_coa_elements": 27,
    "mapped_count": 27,
    "unmapped_count": 0,
    "coverage_percent": 100,
    "unreachable_count": 0,
    "confidence_distribution": { "high": 27, "medium": 0, "low": 0, "manual": 0 }
  }

Every mapping was machine-generated by the MappingAgent at demo-load time. The 27 accounts are chosen to have unambiguous canonical targets (Operating Cash → CashCashEquivalentsAndShortTermInvestments, Consulting Revenue → RevenueFromContractWithCustomerExcludingAssessedTax, etc.) — useful for showing how the workflow looks when coverage is complete, separately from the harder real-world mapping cases.

Schedules

The demo creates 6 schedules to show RoboLedger's recurring-entry surface:

Schedule	Type	Asset	Monthly amount
Computer equipment	Depreciation	$4,800 PP&E, 3-year life	$133.33
Office furniture	Depreciation	$1,500 PP&E, 5-year life	$25
Business insurance	Prepaid amortization	$1,200/year	$100
Software licenses	Prepaid amortization	$300/year	$25
AWS prepay	Prepaid amortization	$600/year	$50
Professional services renewal	Prepaid amortization	$450/year, staggered	$37.50

Schedules generate schedule facts for each period in their window. Facts before closed_through are flagged historical (already baked into the closed-period opening balances). Facts at or after the close target are flagged in_scope — they're the obligations the close workflow proposes to materialize as actual entries.

To inspect:

curl "http://localhost:8000/v1/graphs/$GRAPH_ID/schedules" \
  -H "X-API-Key: $API_KEY" | jq '.[] | {id, name, classification, monthly_amount}'

Frontend Tour

Once the demo is loaded, walk through these screens in roboledger-app at http://localhost:3001:

Screen	What to look at
Entity	The Cascade Advisory Group profile, with fiscal year metadata and a recent activity summary
Connections	Empty for the synthetic demo (no QB connection — this is the whole point)
Chart of Accounts	27 accounts, each with its rs-gaap mapping displayed inline. 100% mapped, 100% renderable.
Transactions	The full posted event log — invoices, payments, bills, payroll JEs
Ledger / Journal Entries	Manual JE form and the entry list grouped by transaction
Schedules	6 schedules with their facts and in-scope state
Documents	4 policy markdown files, searchable
Reports	The filed FY annual report — click in for the full BS / IS / CF / SE rendering with Information Block drill-downs
Close	The fiscal calendar view + the one queued period ready to close + blocker payload (in_scope schedule facts)
Inbox	Empty for the demo (events auto-commit for QB-style sources; demo events do the same)
Agents	The 17 parties: customers, vendors, employees, IRS

The "Close" screen is the most product-distinctive surface — drives the AI-assisted close workflow and surfaces all the period's outstanding items in one place.

Exploring with MCP

For agent-driven exploration, the demo is the easiest entrypoint to the RoboLedger MCP server. Connect Claude Desktop (or any MCP client) to the local server (http://localhost:8000/v1/mcp) and try:

"What entities are in this graph?"
→ get-graph-info

"Show me the chart of accounts grouped by classification"
→ read-graph-cypher with a MATCH (e:Element) ... query

"How many transactions per year?"
→ read-graph-cypher with a date_part('year', t.date) aggregation

"What's the close status for the target period?"
→ get-period-close-status

"Search for the depreciation policy"
→ search-documents with "depreciation"

"Build a fact grid showing year-over-year revenue"
→ build-fact-grid

"Close the books for the most recent completed month"
→ multi-step workflow: get-period-close-status, list-period-drafts,
  preview-event-block, create-event-block, evaluate-rules, close-period

The full prompt for the AI close workflow lives at examples/roboledger_demo/prompt.md — paste it into the client to load the workflow context, then ask the close question.

Resetting the Demo

To re-run cleanly:

# Reset the demo's graph (preserves user + auth)
just demo-roboledger --reset

# Or fully reset everything (drops local data + auth)
just reset-local

--reset clears the demo's events, transactions, line items, mappings, schedules, documents, fiscal calendar, and reports from the tenant, then re-runs the load. Useful for getting back to a known-good state after experimenting with the close workflow or breaking something with manual entries.

reset-local is heavier — drops the entire local stack's data including all users, graphs, and credentials. Use when you want a fresh slate.

Customization

The demo's content lives in examples/roboledger_demo/:

• data.py — event generators (the 305 transactions). Modify to change the business shape, transaction patterns, monthly volumes, or vendor / customer lists.
• mappings.py — the CoA → rs-gaap mapping table. Change targets to demo different statement compositions.
• policies.py — the four policy documents loaded as searchable content.
• agents.py — the 17 parties (customers, vendors, employees, government).
• validate.py — the 38 rules. Add or modify checks to demo different validation scenarios.
• main.py — the orchestration script. Idempotent (--reset clears prior state); re-running picks up your edits.

Common customizations:

• Change the company name and shape — edit data.py COMPANY_NAME and the revenue / expense generators
• Add a failing rule — modify validate.py to introduce a deliberate violation, then run evaluate-rules to see it caught
• Demo a different industry — replace the consulting revenue generators with retail, SaaS, or manufacturing patterns
• Test multi-year history — extend the rolling window beyond 16 months in data.py

Comparison to the QuickBooks Workflow

Aspect	Synthetic Demo	QuickBooks Local
Setup time	One command (~60 sec)	5–15 minutes (Intuit + ngrok config)
External dependencies	None	Intuit Developer + ngrok + QBO subscription
Data shape	Designed for the product — clean, 100% mappable, balanced	Real-world messy — partial mapping coverage, edge-case transaction types
Use for	Product evaluation, regression testing, agent demos, learning the feature set	Real-data smoke testing, your own books, adapter debugging
Iteration speed	Fast — --reset for clean re-runs	Slow — re-sync takes minutes, data isn't deterministic
Mapping coverage	100% renderable on first run	Variable — auto-map agent runs, partial coverage typical, manual remap for edge cases

Both paths produce the same OLTP shape, the same materialized graph, and the same Report-Block lifecycle. The demo is for showing the product; QB is for using it on your own books. See the Connecting QuickBooks Locally guide for the QB workflow.

Next Steps

Once you're comfortable with the demo:

• Connect a real QB company — see Connecting QuickBooks Locally to layer real data on top of the same workflow
• Customize the demo — modify data.py to demo a different vertical for a specific prospect
• Extend the rule engine — add domain-specific validation rules in validate.py
• Build a custom MCP workflow — the close prompt at examples/roboledger_demo/prompt.md is one starting point; you can build vertical-specific agent workflows on the same MCP surface

If you're evaluating RoboLedger for a real engagement: run the demo, drive the AI close, inspect the rule engine output, then connect one of your own QB companies via the QB Local guide. The full evaluation arc takes ~30 minutes if everything's smooth.