evidence-dev/evidence

Business intelligence as code: build fast, interactive data visualizations in SQL and markdown

6,115 stars JavaScript 9 components 5 connections

Business Intelligence as Code: Generate interactive data visualizations using SQL and markdown

Evidence processes markdown files with embedded SQL queries, executes them against configured datasources, and renders the results as interactive web components in a SvelteKit application.

Under the hood, the system uses 1 feedback loop, 2 data pools, 3 control points to manage its runtime behavior.

Structural Verdict

A 9-component data pipeline with 5 connections. 553 files analyzed. Loosely coupled — components are relatively independent.

How Data Flows Through the System

Evidence processes markdown files with embedded SQL queries, executes them against configured datasources, and renders the results as interactive web components in a SvelteKit application.

Template Population — CLI copies Evidence template to .evidence/template/ directory
File Watching — Chokidar watches source files and syncs changes to template directory
Query Execution — Datasource connectors execute SQL/JavaScript queries and return typed results
Component Rendering — SvelteKit processes markdown+SQL into interactive UI components
Web Serving — Development server or static site serves the generated application (config: packages, redirects)

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Query Cache (cache)
Cached query results to avoid re-executing expensive queries

Template Directory (file-store)
Working directory where Evidence processes source files

Feedback Loops

File Watch Loop (polling, balancing) — Trigger: Source file changes detected by chokidar. Action: Sync changed files to template directory. Exit: Development server stopped.

Delays & Async Processing

Template Sync (async-processing) — Source changes must sync to template before being visible
Query Execution (async-processing) — Database queries execute asynchronously before results render

Control Points

EVIDENCE_STRICT_MODE (env-var) — Controls: Enables stricter validation during production builds. Default: true
DEV (env-var) — Controls: Switches between dev and preview test modes
NODE_OPTIONS (env-var) — Controls: Memory limit for Node.js processes. Default: --max-old-space-size=4096

Package Structure

This monorepo contains 8 packages:

evidence (app)
Core framework that processes markdown+SQL files into interactive web applications

core-components (library)
UI component library for charts, tables, and visualizations

datasources (library)
Database connectors for various sources (PostgreSQL, BigQuery, DuckDB, etc)

lib (shared)
Shared utilities including preprocessing, SDK, telemetry, and SQL handling

ui (library)
UI packages including icons, tailwind config, and component library

example-project (app)
Demo Evidence project showcasing features and capabilities

docs (app)
Documentation site built with Evidence itself

e2e-tests (tooling)
End-to-end test suites covering different deployment scenarios

Technology Stack

SvelteKit (framework)
Web application framework for Evidence projects

Chokidar (build)
File system watching for development hot reload

Playwright (testing)
End-to-end testing across browsers

PNPM (build)
Package manager with workspace support

Vite (build)
Build tool and development server

DuckDB (database)
In-browser SQL database for client-side queries

ECharts (library)
Charting library for data visualizations

TailwindCSS (library)
Utility-first CSS framework

Key Components

Evidence CLI (cli-command) — Main command-line interface for Evidence projects with dev server, build, and file watching packages/evidence/cli.js
JavaScript Datasource (module) — Datasource connector that executes JavaScript files returning data objects packages/datasources/javascript/index.js
populateTemplate (function) — Copies Evidence template files to .evidence/template directory for project structure packages/evidence/cli.js
clearQueryCache (function) — Removes cached query results from .evidence/template/.evidence-queries/cache packages/evidence/cli.js
runFileWatcher (function) — Sets up chokidar file watchers to sync source files to template directory during development packages/evidence/cli.js
getRunner (function) — Returns query runner that imports and executes JavaScript files, inferring column types from data packages/datasources/javascript/index.js
E2E Project Creator (cli-command) — CLI tool to scaffold new Evidence e2e test projects with Playwright configuration e2e/create-e2e-project.js
Playwright Config (config) — Shared Playwright test configuration for e2e tests across multiple browsers e2e/playwright-config.js
File System Utils (utility) — Test utilities for editing, creating, and restoring files during HMR testing e2e/hmr/tests/fs-utils.js

Configuration

pnpm-workspace.yaml (yaml)

packages (array, unknown) — default: e2e,e2e/*,!e2e/packaging,packages/**,sites/*

vercel.json (json)

redirects (array, unknown) — default: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Explore the interactive analysis

See the full architecture map, data flow, and code patterns visualization.

Analyze on CodeSea

Related Data Pipeline Repositories

Frequently Asked Questions

What is evidence used for?

Business Intelligence as Code: Generate interactive data visualizations using SQL and markdown evidence-dev/evidence is a 9-component data pipeline written in JavaScript. Loosely coupled — components are relatively independent. The codebase contains 553 files.

How is evidence architected?

evidence is organized into 5 architecture layers: Core Framework, Data Sources, UI Components, Sites & Examples, and 1 more. Loosely coupled — components are relatively independent. This layered structure keeps concerns separated and modules independent.

How does data flow through evidence?

Data moves through 5 stages: Template Population → File Watching → Query Execution → Component Rendering → Web Serving. Evidence processes markdown files with embedded SQL queries, executes them against configured datasources, and renders the results as interactive web components in a SvelteKit application. This pipeline design reflects a complex multi-stage processing system.

What technologies does evidence use?

The core stack includes SvelteKit (Web application framework for Evidence projects), Chokidar (File system watching for development hot reload), Playwright (End-to-end testing across browsers), PNPM (Package manager with workspace support), Vite (Build tool and development server), DuckDB (In-browser SQL database for client-side queries), and 2 more. A focused set of dependencies that keeps the build manageable.

What system dynamics does evidence have?

evidence exhibits 2 data pools (Query Cache, Template Directory), 1 feedback loop, 3 control points, 2 delays. The feedback loops handle polling. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does evidence use?

4 design patterns detected: Monorepo Architecture, Plugin System, Template System, E2E Testing Matrix.

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.