xbrlkit viewer

The xbrlkit viewer is the browser side of xbrlkit: a static, client-side renderer for holon.jsonld and tavi.json financial reports — the analog of Arelle's ixbrl-viewer. A holon is a portable RDF artifact and a Tavi model is compiled JSON, not self-rendering HTML, so the viewer reconstructs the financial statements from the document and layers on interactive inspection, in-browser query, and AI analysis. No sign-up and no backend — open a file and go.

Live at https://xbrlkit.com. From the command line, uvx xbrlkit view NVDA renders a filing here without downloading anything by hand. The viewer is a RoboSystems project; the earlier holon.robosystems.ai address keeps working as an alias.

• File Mode: Open a local holon.jsonld or tavi.json (the same filing as a Project Tavi compiled model) and render the full report — offline, no API key, no backend, no network call. A report on the web opens by link: /?url=https://…/holon.jsonld (or …/tavi.json) (the host must allow cross-origin reads; the RoboSystems public data CDN does, and so does xbrlkit view's loopback server). Try it locally with npm run preview — the dev server cannot serve a ?url= link, Vite reserves that query for asset imports.
• Graph Mode: Search any public company and pull its report from the live SEC knowledge graph with your own RoboSystems API key. Same renderer; the authenticated call is made client-side.
• Statement Rendering: Reconstructs the complete report — balance sheet, income statement, cash flow, equity, and every disclosure section — from the holon's scene / boundary / projection named graphs, with a table-of-contents sidebar for navigation.
• Dimensional Facts & Disclosures: Renders dimensional breakdowns (segments and other axes) and text-block note disclosures alongside the numeric statements, at full fidelity.
• Fact Inspection: Inspect any fact — its element, period, unit, and the calculation rule it participates in — directly in the statement tables.
• AI Analysis: Ask questions of the loaded report in natural language. A Claude-powered agent answers by querying the report in your browser (MCP-style tools) — SPARQL over a holon's RDF, jq over a Tavi model's JSON — so responses are grounded in the report's actual facts. The two hand-offs are the same shape (a describe tool, then one query tool), so the report's representation is the only thing that differs.
• One-Click Summary: Generate an AI narrative overview of the report on demand.
• Voice: Have summaries and answers read aloud via ElevenLabs text-to-speech, with a configurable voice and quality preset — the same eleven_v3 house setting the content-machine narrations ship with, or Turbo when you would rather it start speaking sooner.
• In-Browser Query Engines: A Comunica SPARQL engine runs client-side over a holon's RDF, and jq (compiled to WebAssembly, in a Web Worker with a wall-clock limit) over a Tavi model — both power the AI's query tool with no server round-trip.
• Bring-Your-Own Keys: Anthropic, ElevenLabs, and RoboSystems API keys are entered in a keys drawer and persisted only in your browser — never sent to an app backend (there isn't one).

Quick Start

npm install      # Install dependencies
npm run dev      # Start the dev server (Vite, default http://localhost:5173)

Open the bundled sample report, or drag in your own holon.jsonld or tavi.json. Build either from any SEC filing with xbrlkit, or skip the file entirely: uvx xbrlkit view NVDA serves a filing from your machine and opens it in the hosted viewer.

Configuration

File Mode needs no configuration. For Graph Mode, the viewer talks to the RoboSystems API — production (https://api.robosystems.ai) by default. To point it at a local backend, copy the env template and set the URL:

cp .env.example .env
# VITE_ROBOSYSTEMS_API_URL=http://localhost:8000

In npm run dev the dev server proxies /v1/* to that target server-side, so a local backend works without a CORS allowlist entry. (Inline still works too: VITE_ROBOSYSTEMS_API_URL=http://localhost:8000 npm run dev.)

Development Commands

Core Development

npm run dev              # Start the Vite dev server
npm run build            # Production build → dist/ (pure static files)
npm run preview          # Preview the production build locally

Testing

npm run test:all         # format:check + lint + typecheck + test + build (the CI gate)
npm run test             # Run the Vitest test suite
npm run test:watch       # Vitest in watch mode

Code Quality

npm run lint             # ESLint validation
npm run lint:fix         # Auto-fix linting issues
npm run format           # Prettier code formatting
npm run format:check     # Check formatting compliance
npm run typecheck        # TypeScript type checking

SDLC Commands

npm run feature:create   # Create a feature branch

Prerequisites

System Requirements

• Node.js 24+ (LTS)
• npm
• Modern browser (Chrome, Firefox, Safari, Edge)

API Keys (bring-your-own, optional)

Keys are entered in the app's keys drawer and stored only in your browser.

• File Mode needs none.
• RoboSystems API key — for Graph Mode (pull live company reports)
• Anthropic API key — for AI analysis and summaries
• ElevenLabs API key (get one) — for voice / read-aloud

Deployment Requirements

• Fork this repo
• AWS account with IAM Identity Center (SSO)
• S3 + CloudFront for static hosting, provisioned via CloudFormation
• Custom domains are optional, from two repo variables: VIEWER_DOMAIN (the canonical name, in a public Route53 hosted zone; an apex domain also gets its www. form, redirected to it at the edge) and VIEWER_LEGACY_DOMAIN (an earlier name, served as an alias of the same distribution — never redirected, because a published xbrlkit view allows only the origin it was built with to read the report it serves)
• A production GitHub environment on the repo (required reviewer; deployment refs main, release/*): the deploy workflow's gate job binds it, so every production deploy pauses for approval

Architecture

Application Layer:

• Vite + React 19 + TypeScript single-page app
• @robosystems/report-components — the source-agnostic rendering library shared with the RoboLedger app and others; this repo is the shell around it
• N3.js quad store + Comunica for in-browser RDF and SPARQL; jq-wasm (in a Web Worker) for in-browser jq over Tavi models
• Anthropic SDK for AI; ElevenLabs for voice
• @robosystems/client (RoboSystems TypeScript SDK) for Graph Mode reads

Rendering:

The render logic is not in this app — it lives in @robosystems/report-components. The viewer supplies read-only adapters (the holon.jsonld and tavi.json file parsers and a SEC graph client) plus the UI shell: file-drop / graph-connect UX, fact inspection, chat, voice, and branding.

Infrastructure:

• Builds to pure static files — no backend at runtime
• Hosted on AWS S3 + CloudFront
• CloudFormation-managed; deployed via GitHub Actions

CI/CD

• deploy.yml: Static-site deploy to S3 + CloudFront (manual dispatch, approval-gated by the production environment)
• test.yml: Automated testing on pull requests

Support

• Issues
• Wiki
• Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT © 2026 RFS LLC