Luca Technical Glossary

Claude Co-Work Architecture #

Claude Co-Work is Anthropic's agentic AI platform for automating multi-step knowledge work tasks. It is the platform that Luca is built on. Think of it as the runtime environment — Claude Co-Work provides the AI reasoning engine, the tool execution framework, and the skill loading infrastructure that Luca's logic layers run inside.

Luca itself is not a standalone application in the traditional sense. It is a set of Skills and MCP tools that execute within a Claude Co-Work session. When a user interacts with Luca, they are interacting with Claude Co-Work, which is orchestrating Luca's specialised accounting logic on their behalf.

Cost: Claude Co-Work Pro is $20/month, billed by Anthropic directly. This subscription is required to run Luca regardless of which Luca plan you choose. It is a separate charge on top of any Luca hosting fees.

MCP — Model Context Protocol Architecture Technology #

Model Context Protocol (MCP) is an open standard developed by Anthropic that defines how AI models communicate with external tools and data sources. It is the interface layer between Claude Co-Work's reasoning engine and the outside world.

In Luca's architecture, MCP is how Claude Co-Work calls the Luca General Ledger. Luca exposes over 40 accounting operations as MCP tools — each one is a discrete, typed function that Claude can call when it needs to perform an accounting action. Examples include gl_post_transaction, gl_reconcile_bank_account, gl_get_vat_return, and gl_get_merkle_proof. Claude decides which tool to call based on the user's intent; it does not have to be told explicitly which function to invoke.

MCP tools have structured input and output schemas (JSON). This means Claude's output is constrained to well-defined accounting operations — it cannot, for example, issue arbitrary SQL against the database. All accounting state changes go through the MCP layer, which enforces business rules and audit logging before committing anything to the General Ledger.

Skills Architecture #

In the Claude Co-Work architecture, a Skill is a bundle of structured instructions, workflows, and tool access permissions that give Claude Co-Work a specialised domain capability. Skills are analogous to a job description: they tell Claude Co-Work what role it is playing, what tools it can use, what procedures to follow, and what quality standards to meet.

Luca is implemented as two primary Skills:

lucas-general-ledger — the main accounting brain. This skill handles conversational accounting queries, orchestrates day-to-day bookkeeping, interprets the user's intent (e.g. "what is my VAT position this quarter?"), and calls the appropriate MCP tools to retrieve or update the General Ledger.

gl-document-posting — the document ingestion skill. When a financial document (invoice, receipt, bank statement, credit note, payroll summary) is presented, this skill classifies it, extracts the relevant fields, determines the correct accounting treatment, and posts the resulting journal entry to the ledger via MCP.

A third scheduled skill handles batch processing — running overnight reconciliation, generating period-end reports, computing FX revaluation adjustments, and preparing VAT returns.

REST API Technology #

A REST API (Representational State Transfer Application Programming Interface) is a standardised way for software components to communicate over HTTP. It defines a set of endpoints (URLs), each of which accepts a specific HTTP method (GET, POST, PUT, DELETE) and a structured request body, and returns a structured response — typically JSON.

Luca's General Ledger is implemented as a REST API. The MCP tools that Claude Co-Work calls are thin wrappers around this API — they translate Claude's structured tool calls into HTTP requests against the GL REST API endpoints, and translate the HTTP responses back into data Claude can reason about.

This architecture means the General Ledger is a fully self-contained service, decoupled from the AI layer. It can be called by other integrations (your own code, other tools) directly via REST, without going through Claude at all. The source code for both the GL API and the MCP layer is available on GitHub.

Open Source Technology #

Open source software is software whose source code is publicly available for anyone to inspect, modify, and distribute. Luca is open source — the complete source code for the General Ledger API, the MCP tool layer, and the Skill definitions is available at github.com/roger296/lucaV0.5.

This means you can self-host Luca on your own infrastructure at zero software cost. You can inspect exactly what Luca does with your financial data. You can fork and modify it to suit your requirements. You can contribute improvements back to the project.

If you find Luca useful, please consider starring the repository on GitHub. Stars are the primary signal of interest and utility in the open source community — they help the project gain visibility and attract contributors. You can star the repo at github.com/roger296/lucaV0.5 — it takes three seconds and makes a genuine difference.

General Ledger (GL) Accounting #

The General Ledger is the central accounting record of a business. Every financial transaction the business makes — every sale, purchase, payment, receipt, payroll run, bank transfer — is recorded in the General Ledger as a journal entry. The GL is the source of truth from which all financial reports (P&L, balance sheet, cashflow statement) are derived.

Luca's General Ledger is a purpose-built double-entry accounting engine, implemented as a REST API backed by a PostgreSQL database. It is not built on top of Xero, QuickBooks or any other third-party accounting platform — it is a from-scratch implementation with a Merkle Chain audit trail baked in from the ground up.

The GL supports a configurable Chart of Accounts, period management (soft close / hard close), multi-currency transactions with FX revaluation, and a full suite of statutory reports.

Double-Entry Bookkeeping Accounting #

Double-entry bookkeeping is the fundamental accounting principle that every financial transaction must be recorded as two equal and opposite entries — a debit and a credit — affecting at least two accounts. The total of all debits must always equal the total of all credits. This constraint is what makes accounting self-correcting and auditable: any error or tampering disturbs the balance and becomes detectable.

For example, when a customer pays a £1,000 invoice: Debit Bank (asset increases by £1,000) and Credit Debtors / Accounts Receivable (liability decreases by £1,000). The net effect on the accounting equation (Assets = Liabilities + Equity) is zero, but the individual accounts now correctly reflect the business's financial position.

Luca's General Ledger enforces double-entry at the database level — a transaction that does not balance (debits ≠ credits) is rejected before it is written to the ledger. This happens in the GL API, not in the AI layer, so even if Claude were to generate a malformed posting request, the ledger itself would refuse it.

Chart of Accounts Accounting #

The Chart of Accounts (CoA) is the complete, structured list of every account in a business's General Ledger. Each account has a unique code, a name, a type (asset, liability, equity, revenue, or expense), and a normal balance direction (debit or credit). Every journal entry must reference accounts that exist in the CoA.

Luca ships with a default CoA appropriate for UK SMEs, covering the standard account categories needed for statutory reporting. It can be customised via the MCP tool gl_import_chart_of_accounts to match your specific business structure. You can create accounts, modify account names, and reorganise the hierarchy. You cannot delete accounts that have transactions posted to them (this would corrupt the ledger).

Journal Entry Accounting #

A journal entry is the atomic unit of accounting — a single recorded transaction in the General Ledger. Each journal entry contains a date, a description, and two or more lines (each specifying an account from the Chart of Accounts, an amount, and a debit/credit direction). The entry must balance: total debits equal total credits.

In Luca, journal entries are created by the gl-document-posting skill (when processing documents) or by the lucas-general-ledger skill (when handling conversational instructions). They are posted via the gl_post_transaction MCP tool, which calls the GL REST API, which validates the entry, writes it to PostgreSQL, and appends it to the Merkle Chain.

Once a journal entry is posted to a hard-closed period, it cannot be modified. Corrections must be made via a new reversing journal entry — this preserves the integrity of the audit trail.

Trial Balance Accounting #

The Trial Balance is a report that lists every account in the Chart of Accounts with its current debit or credit balance. The defining property of a correct Trial Balance is that the sum of all debit balances equals the sum of all credit balances. If they don't match, there is an error in the ledger.

The Trial Balance is the starting point for preparing the statutory financial statements (P&L and Balance Sheet). Luca generates a live Trial Balance via the gl_get_trial_balance MCP tool at any point in time, not just at period end. This means you always have an up-to-date view of the ledger's mathematical integrity.

Bank Reconciliation Accounting #

Bank reconciliation is the process of matching every line in a bank statement against a corresponding entry in the General Ledger — confirming that the ledger and the bank agree. Unmatched lines indicate either an error in the ledger, a timing difference (e.g. an outstanding cheque), or potential fraud.

Luca automates bank reconciliation via the gl_import_bank_statement and gl_reconcile_bank_account MCP tools. Bank statement lines are imported (as OFX, CSV or MT940), and Luca attempts to match each line against existing journal entries using a combination of amount, date, and description heuristics. High-confidence matches are confirmed automatically; uncertain matches are surfaced for human review via the gl_confirm_bank_match tool.

Luca can also post and match simultaneously — if a bank line arrives with no matching ledger entry, Luca will post the necessary journal and immediately match against it, using the document inbox to classify the transaction type.

Aged Debtors & Aged Creditors Accounting #

Aged Debtors (also called Accounts Receivable Ageing) is a report listing all outstanding sales invoices, grouped by how long they have been unpaid — typically in bands of 0–30, 31–60, 61–90, and 90+ days. It shows you who owes you money and how overdue those debts are.

Aged Creditors (Accounts Payable Ageing) is the mirror image — listing all outstanding supplier invoices by overdue band. It shows what you owe to suppliers and what is at risk of becoming overdue.

Both reports are generated from the General Ledger via the gl_get_aged_debtors and gl_get_aged_creditors MCP tools. Luca can be asked to generate these reports conversationally at any time, and will proactively flag heavily overdue items as part of its regular insights.

VAT & Making Tax Digital (MTD) Accounting #

Value Added Tax (VAT) is a consumption tax applied to most goods and services in the UK. VAT-registered businesses must collect VAT on their sales (output tax), reclaim VAT on their purchases (input tax), and submit quarterly VAT returns to HMRC showing the net amount owed or reclaimed.

Making Tax Digital (MTD) is HMRC's programme requiring VAT-registered businesses to keep digital records and submit VAT returns via compatible software. Luca is designed to be MTD-compatible — it maintains digital VAT records at the transaction level, accumulates output and input tax against a configurable VAT period, and prepares the nine VAT return boxes automatically via the gl_get_vat_return MCP tool.

All transactions in Luca can carry VAT codes. The GL tracks VAT treatment at the line level, allowing precise calculation of partially exempt scenarios. Luca does not currently submit returns directly to HMRC's MTD API (you must review and submit manually), but direct MTD submission is planned for a future release.

FX Revaluation Accounting #

FX (Foreign Exchange) Revaluation is the accounting process of restating the base-currency value of outstanding multi-currency balances at the current exchange rate, and recognising the resulting gain or loss in the P&L. This is required at period end by most accounting standards (UK GAAP, IFRS).

For example: if you raised a €10,000 invoice when EUR/GBP was 0.87 (booked as £8,700), and at period end EUR/GBP has moved to 0.85, the outstanding debtor balance should be restated to £8,500 — recognising a £200 unrealised FX loss.

Luca handles FX revaluation automatically. Exchange rates are stored in the GL via gl_add_exchange_rate and can be retrieved via gl_get_exchange_rate. The gl_fx_revaluation MCP tool sweeps all open multi-currency balances at period end, calculates the revaluation adjustments, and posts the resulting journal entries automatically.

Soft Close & Hard Close Accounting #

Period management controls which accounting periods are open for posting and which are locked. Luca supports two levels of period closure:

Soft Close (gl_soft_close_period) — The period is marked as closed, which prevents casual posting. However, authorised adjustments can still be made with an override. This is appropriate at month-end, after initial management accounts have been prepared but before the period has been reviewed and agreed.

Hard Close (gl_hard_close_period) — The period is permanently locked. No further postings can be made to it under any circumstances. Any correction must be recorded in a subsequent open period as a reversing or adjusting entry. Hard close is appropriate after the period has been formally signed off — for example, after a quarterly VAT return has been filed or after year-end accounts have been finalised.

Hard close is enforced at the database constraint level in the GL, not just in the application layer. Even a direct database query cannot insert a journal into a hard-closed period without overriding the constraint.

Batch Processing Architecture #

Batch processing refers to executing a set of accounting tasks automatically on a schedule, without requiring user interaction. Luca includes a scheduled batch runner that executes nightly (or on demand) to perform tasks that are best done in bulk rather than reactively.

The Luca batch runner is implemented as a Claude Co-Work Skill triggered by a scheduled task. A typical nightly batch run includes: importing and reconciling bank feeds (gl_import_bank_statement, gl_reconcile_bank_account), scanning the document inbox for unprocessed items (gl_scan_inbox), running any outstanding FX revaluation entries (gl_fx_revaluation), updating aged debtor/creditor reports, and generating an exception report of items requiring human attention.

Batch run state is tracked via gl_start_batch_run, gl_record_batch_task, and gl_complete_batch_run — this means every batch run is logged with its constituent tasks and outcomes, giving you a complete history of what Luca has done autonomously.

Merkle Chain Audit Trail Technology #

A Merkle Tree is a cryptographic data structure where every data block is hashed, and each hash is combined with its sibling hash to produce a parent hash — all the way up to a single root hash (the "Merkle root") that represents the entire dataset. The key property is that any change to any single data block invalidates all hashes above it in the tree, making tampering immediately detectable.

Luca's General Ledger maintains a Merkle Chain: every journal entry is hashed, and each hash incorporates the hash of the previous transaction (similar to a blockchain, but simpler and purpose-built for accounting). This creates a cryptographically linked chain of all accounting records.

The practical implication: if anyone modifies or deletes a historical journal entry — even directly in the PostgreSQL database — the Merkle Chain breaks. The gl_verify_chain and gl_verify_chain_sequence MCP tools will detect the discrepancy. Individual transactions can be proven with a gl_get_merkle_proof — a short chain of hashes that proves a specific transaction was in the ledger at a specific point in time, without needing to reveal any other transaction data.

This gives Luca an audit trail with a much stronger integrity guarantee than a conventional database log. It is particularly relevant in a system where an AI has autonomous posting authority — the Merkle Chain provides mathematical proof that the audit trail has not been altered after the fact.