accounted/ARCHITECTURE.md

Architecture

Accounted is a multi-tenant double-entry bookkeeping system built for Swedish accounting law. This document explains how the system is put together and why some parts are deliberately rigid. For contribution workflow, see CONTRIBUTING.md.

Overview

• Framework: Next.js (App Router) with React and TypeScript in strict mode.
• Database: Supabase (PostgreSQL with Row Level Security), which also provides auth (email/password plus TOTP MFA).
• Deployment: Vercel-hosted is the primary target; a Docker self-hosted setup is fully supported (see docs/SELF-HOSTING.md).
• UI: Tailwind CSS with shadcn/ui components. User-facing product language is Swedish and English (messages/sv.json, messages/en.json).

The bookkeeping engine

All accounting writes flow through one engine: lib/bookkeeping/engine.ts.

The journal entry lifecycle is draft, then commit:

1. createDraftEntry() creates an uncommitted entry that can still change.
2. commitEntry() posts it. The voucher number is assigned atomically by the commit_journal_entry database RPC, which keeps numbering sequential per series. Swedish law requires an unbroken, explainable voucher sequence.
3. createJournalEntry() does both steps in one call.

Two invariants hold for every entry:

• Debits equal credits, and both sides are greater than zero.
• Once committed, an entry is never silently edited or deleted. BFL 5 kap. 5 § allows two correction paths, and the code has exactly those two:
  • Storno: reverseEntry() cancels a voucher with a reversal entry and correctEntry() replaces it (lib/core/bookkeeping/storno-service.ts). Always allowed.
  • Inline rättelse (founder-approved 2026-07-23): the correct_entry_metadata and correct_entry_lines_inline RPCs strike-and-replace inside the same voucher, keeping the original readable and writing an immutable who/when record to journal_entry_rattelse_log. Only while the period is open and unlocked; past a lock, close, or declared state, storno is the only path.

If a gap still occurs in a voucher series (for example around imported history), it must be documented, and the explanation is stored (voucher_gap_explanations), following BFNAR 2013:2.

Legal enforcement lives in the database

The rules above are not conventions; they are enforced by PostgreSQL triggers:

• Committed journal entries cannot be edited or deleted. The only changes the triggers permit are the controlled status transition used by the storno flow (marking an entry as reversed) and the audited inline-rättelse RPCs above, which are refused once the period is locked or closed.
• Writes to closed or locked accounting periods are rejected, as are writes behind a company-wide lock date.
• Documents linked to posted entries cannot be deleted; Swedish law requires 7-year retention of accounting records.

Application code never works around these triggers. If a code path hits one, the code path is wrong, not the trigger.

Two smaller invariants that show up everywhere in the codebase:

• Monetary amounts are rounded with Math.round(x * 100) / 100. String-based rounding such as toFixed() causes drift at the öre level and breaks entry balance.
• Account numbers are strings ('1930', never 1930). They are identifiers, not quantities.

Multi-tenancy and security

Users belong to companies through company_members, and every business table carries a company_id. Access control is layered:

• Row Level Security in PostgreSQL restricts rows to companies the user belongs to.
• Explicit filtering: queries still filter by company_id in code, as defense in depth, because service-role code paths bypass RLS.
• Route guards: API routes wrap a shared route context helper that resolves the authenticated user, the active company, and MFA enforcement in one place. Routes never hand-roll their own auth.

The active company is resolved server-side from the user's stored preference, so the Next.js app and RLS always agree on which company is active.

Extension system

Core is a complete accounting product on its own. Optional functionality (AI categorization, receipt OCR, email, calendar, the MCP server, and more) ships as extensions under extensions/, toggled by extensions.config.json.

The boundary is strict and CI-enforced:

• Core code never imports from @/extensions/. CI builds core with zero extensions enabled, so a direct import breaks the build.
• Extensions integrate through the event bus and documented extension APIs, and are wired via a generated static registry (npm run setup:extensions).
• Provider integrations (banks, Skatteverket, Peppol, migration sources) are moving behind the connector: a self-hosted instance with a connector key and no credentials of its own for an upstream reaches that upstream through the hosted app/api/connect/* side (an instance running on its own registered credentials talks to the provider directly, see docs/SELF-HOSTING.md), and the open ledger keeps the contract plus the manual file paths. npm run check:guards ratchets the set of files that name a provider API host directly; that set may only shrink.

Licensing follows the same boundary: the project is AGPL-3.0, with an extension exception that allows third-party extensions using only the documented Extension API to be licensed under any terms. See LICENSE and docs/EXTENSIONS.md.

Agent surface (MCP)

The bookkeeping engine is exposed as an MCP (Model Context Protocol) server with 150+ tools, so AI agents can operate the ledger: list and categorize transactions, draft vouchers, reconcile periods, generate reports and declarations.

• Authentication uses scoped API keys (stored as SHA-256 hashes, rate limited per key). Claude, ChatGPT and Grok connectors instead authenticate with OAuth 2.1 (PKCE; app/api/mcp-oauth/{authorize,register,token} plus the .well-known discovery documents), which mints a scoped API key behind the scenes. Authentication is lazy: a client can connect, list tools, and call a small set of public discovery tools before an account exists; the first tenant-touching call answers 401 and triggers the client's connect prompt (extensions/general/mcp-server/public-tools.ts).
• Posting operations are staged: an agent proposes an operation, and a human approves it before anything is committed to the journal.

Events

lib/events/bus.ts is a module-level singleton event bus. Domain events (for example "invoice created" or "transaction imported") are how extensions react to core activity without core knowing about them.

Repository map

Path	Contents
app/	Next.js App Router pages and API routes
lib/bookkeeping/	Engine, entry generators, account mapping, BAS chart data
lib/core/	Periods, year-end, storno, tax codes, audit, documents
lib/reports/	Balance sheet, income statement, VAT, SIE, tax reports
lib/ (other)	Invoices, transactions, imports, salary, reconciliation, tax, providers
components/	React components (shadcn/ui based)
extensions/	Opt-in extension plugins
supabase/migrations/	Database schema, RLS policies, enforcement triggers
packages/accounted-mcp	Published stdio MCP bridge for new installs (accounted_* tool namespace)
packages/gnubok-mcp	Compatibility MCP bridge for existing installs (kept on purpose)
claude-plugin/	Claude Code plugin: OAuth connector plus approval-gated workflow skills
messages/	Swedish and English UI strings
tests/	Shared test helpers and fixtures
docs/	Self-hosting, Docker, extensions, white-label guides

Testing

• Unit and route tests run on Vitest with mocked Supabase clients (npm test).
• Database behavior (triggers, RPCs, RLS) is tested against a real PostgreSQL instance in *.pg.test.ts files (npm run test:pg), because mocking cannot prove trigger semantics.