Numeralens documentation

A production-grade financial analytics frontend built with Next.js 16, React 19, TypeScript and Tailwind CSS v4. It ships with a complete demo dataset so it runs the moment you install it, and a clean adapter layer so you can point it at your own accounting or ERP backend without touching a single UI component.

Numeralens is a reporting and analytics frontend. It reads financial data and presents it; it does not post journals or replace your accounting system.

It scales to a 250,000-line ledger, and it ships an AI intelligence layer that sits on top of a deterministic calculation engine — one that never lets a language model produce a number.

Highlights

• 37 pages — executive dashboard, four analytics modules, seven financial reports, customer and vendor directories with detail views, a transactions explorer, budget and forecast, inventory, a build-your-own dashboard, three intelligence modules, a performance lab, ten settings screens and an in-app help centre.
• Built for real ledgers — 100,000 transactions with sub-10 ms paging, search and filtering, and 26 DOM rows on screen at any moment. Switch the demo ledger between 10K and 250K lines and watch the numbers yourself in the Performance Lab. Every figure is measured; see docs/PERFORMANCE.md.
• Five AI capabilities, none of which can invent a figure — executive narrative, a CFO Copilot that compiles questions into a closed-enum query, predictive cash flow, an anomaly sentry, and AR collection risk. All five work with no API key: a deterministic engine composes them from the same validated numbers. See docs/AI_ARCHITECTURE.md.
• Runs out of the box — a deterministic 25-month double-entry ledger for the fictional "Northstar Holdings" (~8,900 ledger lines, 24 customers, 17 vendors, 1,100+ invoices). Trial balance balances, the balance sheet reconciles, and receivables genuinely age.
• One integration point — implement DataAdapter, or point the bundled HTTP adapter at your REST API and adjust src/services/mappers.ts.
• White-label ready — company name, logo, colours, currency, locale, date format and landing page are configuration, applied at runtime through CSS variables.
• Modular — 17 feature flags switch whole modules off; disabled areas vanish from navigation, search and routing.
• Real authentication and authorisation — signed session cookies, a sign-in screen, and five roles whose permissions are enforced on the server: every data route checks the session before it answers, so hiding a page is not the only thing stopping a Viewer from reading the ledger. Swap in your own identity provider by replacing one file.
• Drill-down everywhere — click a chart segment, KPI or report line to open the underlying ledger entries, then step back through a breadcrumb trail.
• Export — CSV, Excel-compatible CSV and print/PDF from every table and report.
• Mobile, not just responsive — below 768px every table becomes a card list with labelled fields and a disclosure for secondary data. Nothing is dropped to make the UI compact.
• Decimal-safe money — integer-cent arithmetic throughout, so a column of ten thousand rows sums to exactly the printed total.

Quick start

npm install
npm run dev

Open http://localhost:3000. No backend, no API keys, no database — including for the AI features, which fall back to a deterministic engine that composes its answers from the same validated figures.

Sign in with any demo account; the password is demo1234 and the accounts are listed on the sign-in screen. Pick Viewer to watch the permission system work: the ledger and transactions vanish from the navigation, and the API returns 403 if you request them anyway.

To use a live model instead, set ANTHROPIC_API_KEY in .env.local. Nothing else changes: the numbers come from the calculation engine either way.

npm run build && npm run start   # production build
npm run lint                     # ESLint
npm run typecheck                # tsc --noEmit
npm test                         # Vitest (237 tests)
npm run bench                    # engine benchmark across dataset sizes

Requires Node.js 20 or newer.

Connecting your data

Three options, in increasing order of effort:

1. Point at a REST API from the UI — Settings → Data source, enter your base URL, press "Test connection". Nothing to rebuild.
2. Set it at build time — NEXT_PUBLIC_API_URL plus NEXT_PUBLIC_ENABLE_DEMO_MODE=false in .env.local.
3. Write an adapter — implement the 23-method DataAdapter interface in src/services/adapters/ for GraphQL, gRPC, a database client or anything else.

Full walkthrough with request and response shapes: docs/api-integration.md.

Documentation

Tech stack

Next.js 16 (App Router) · React 19 · TypeScript (strict) · Tailwind CSS v4 · TanStack Query 5 · TanStack Table 8 · TanStack Virtual 3 · Recharts 3 · Radix UI · react-hook-form · Zod 4 · date-fns 4 · jose · lucide-react · next-themes · Vitest · Anthropic SDK (optional, server-only).

Project layout

src/
  app/              routes (pages + demo API routes)
  components/       ui primitives, charts, tables, layout, filters, settings
  config/           app, branding, features, roles, navigation
  hooks/            data hooks and localStorage store
  lib/              calculations, dates, formatting, export utilities
    ai/             prompts, schemas, adapters, anomaly + collections engines
    auth/           sessions, credential checks, the authorisation boundary
    calculations/   money, ratios, forecasting, financial formulas
    live/           live-update scheduler
    performance/    Web Vitals measurement
  mock/             demo dataset generator, scale extension, indexes, analytics engine
  providers/        theme, query, branding, features, auth, filters
  services/         adapters, mappers, service facades
  types/            entities, filters, metrics
  proxy.ts          signed-out redirect (Next 16 replacement for middleware.ts)
docs/               documentation
tests/              Vitest suites

Licence

See LICENSE.md. One end product per licence; the Extended Licence covers products you charge end users for. Reselling Numeralens itself as a template or starter kit is not permitted.

Support: six months from purchase — see docs/support.md.

All company names, customers, vendors and figures in the demo data are fictional.