evidence-dev/evidence
Business intelligence as code: build fast, interactive data visualizations in SQL and markdown
Converts SQL queries and markdown files into interactive data visualization websites
Evidence processes SQL-embedded markdown files by first setting up a template project structure, then executing SQL queries against configured data sources to generate result sets, and finally rendering these results into interactive components that are built into static websites. The CLI coordinates this entire pipeline while file watchers enable live reloading during development.
Under the hood, the system uses 3 feedback loops, 3 data pools, 4 control points to manage its runtime behavior.
A 6-component fullstack. 553 files analyzed. Data flows through 5 distinct pipeline stages.
How Data Flows Through the System
Evidence processes SQL-embedded markdown files by first setting up a template project structure, then executing SQL queries against configured data sources to generate result sets, and finally rendering these results into interactive components that are built into static websites. The CLI coordinates this entire pipeline while file watchers enable live reloading during development.
- Initialize Evidence Project — The CLI populates the .evidence/template directory with framework files, preserves user settings like .profile.json and static assets, and clears any existing query cache [template source files → project structure]
- Execute SQL Queries — Data source connectors like getRunner import JavaScript files or execute SQL against databases, inferring column types and returning standardized QueryResult objects with rows and metadata [JavaScript data files → QueryResult]
- Process Markdown Files — The file watcher monitors pages/*.md files, transforms them by converting index.md to +page.md and other files to directory/+page.md structure, then syncs to template directory [markdown files with SQL → processed page files]
- Render Components — Evidence components consume QueryResult data to generate interactive charts, tables, and dashboards, using the inferred column types to determine appropriate visualizations [QueryResult → rendered components]
- Generate Static Site — The build process compiles all processed pages and components into a static website, applying configuration like deployment.basePath for proper asset linking [rendered components → static website] (config: deployment.basePath)
Data Models
The data structures that flow between stages — the contracts that hold the system together.
packages/datasources/javascript/index.jsobject with rows: array of data objects, columnTypes: array of {name: string, evidenceType: EvidenceType, typeFidelity: string}, expectedRowCount: number
Created by data source connectors when queries execute, consumed by Evidence components to render charts and tables
packages/lib/sdk/configconfiguration object with deployment.basePath and other project settings loaded from evidence.plugins.yaml
Loaded at startup from configuration files, used throughout the build process to control deployment paths and feature flags
e2e/hmr/tests/fs-utils.jsMap entries with filePath: string keys and originalContent: string values, plus Set of created files and deleted files
Tracks file modifications during HMR testing, allows rollback of changes after test completion
Hidden Assumptions
Things this code relies on but never validates. These are the things that cause silent failures when the system changes.
4096MB of system memory is available and NODE_OPTIONS environment variable won't exceed shell command line limits when appended to
If this fails: On systems with less RAM or with very long existing NODE_OPTIONS, Evidence projects will fail to start with out-of-memory errors or command line argument overflow
packages/evidence/cli.js:increaseNodeMemoryLimit
JavaScript data files export a 'data' property containing a non-empty array where data[0] exists and represents the schema for all rows
If this fails: If data array is empty or data[0] is undefined, Object.keys(data[0]) throws 'Cannot convert undefined or null to object' error, crashing query execution
packages/datasources/javascript/index.js:getRunner
All rows in the data array have identical column structure matching data[0], and data[0] contains all possible columns that will appear in any row
If this fails: If later rows have additional columns not present in data[0], those columns are silently ignored in column type inference, leading to incomplete schema detection
packages/datasources/javascript/index.js:getRunner
All files tracked in originalFiles, createdFiles, and deletedFiles still exist and are writable when restoration occurs, and the process has not been interrupted between tracking and restoration
If this fails: If files were externally deleted or made read-only, or process crashed before restoration, test cleanup fails silently leaving orphaned files and modified content in the test environment
e2e/hmr/tests/fs-utils.js:restoreChangedFiles
Template population completes before any file watchers start monitoring the .evidence/template directory, and clearQueryCache() completes before template files are copied
If this fails: Race condition where file watchers detect template files being written during population, triggering unnecessary rebuilds or corrupting the template structure mid-copy
packages/evidence/cli.js:populateTemplate
Chokidar can successfully watch all specified file patterns and the filesystem supports inotify/FSEvents, with sufficient file descriptor limits for the number of watched files
If this fails: On systems with exhausted file descriptors or filesystems without change notification support, file watching silently fails causing hot reload to stop working without user notification
packages/evidence/cli.js:runFileWatcher
File system has sufficient disk space for file modifications and the process has write permissions to all files being tracked in the Maps
If this fails: When disk is full or permissions are revoked mid-test, file modifications fail but tracking data remains inconsistent, leading to incomplete rollback attempts
e2e/hmr/tests/fs-utils.js:editFile
JavaScript data arrays are small enough to fit in memory multiple times (original + processed output) and Object.keys() operation on data[0] completes quickly
If this fails: Large datasets cause memory exhaustion during column type inference or long blocking operations that freeze the Evidence build process
packages/datasources/javascript/index.js:getRunner
The template source directory structure at path.join(__dirname, '/template') matches the expected Evidence project structure and all template files are valid
If this fails: If template directory is corrupted or incomplete, Evidence projects will be created with missing critical files, causing mysterious runtime failures in generated sites
packages/evidence/cli.js:populateTemplate
Files marked for deletion in deletedFiles Map haven't been modified between deletion and restoration, and the content read before deletion still represents the correct state
If this fails: If external processes modify files after Evidence deletes them but before restoration, the restored content will be stale, potentially losing important changes made during the test
e2e/hmr/tests/fs-utils.js:deleteFile
System Behavior
How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
Staging area where Evidence assembles the complete project structure before building, preserving user data while updating framework files
Stores executed query results to avoid re-running expensive database queries during development
Runtime Maps and Sets that track all file modifications during HMR testing to enable complete rollback
Feedback Loops
- Hot Module Reload Loop (polling, reinforcing) — Trigger: File system changes detected by chokidar watchers. Action: Sync modified files to template directory, trigger browser refresh, clear affected query cache. Exit: Development server shutdown.
- Query Result Caching (cache-invalidation, balancing) — Trigger: SQL query execution or source data changes. Action: Store results in .evidence-queries/cache, serve cached results for identical queries. Exit: Cache cleared or expired.
- Test File Rollback (self-correction, balancing) — Trigger: Test completion in HMR test suite. Action: Restore all modified files to original state, delete created files, recreate deleted files. Exit: All changes reverted successfully.
Delays
- Development Server Startup (compilation, ~3000ms base + 4500ms on CI + 1500ms on Windows) — Users wait for Vite compilation and Evidence template population before the dev server becomes interactive
- Query Cache Population (async-processing) — First-time query execution takes longer as results are computed and cached, subsequent runs are faster
- File Watcher Debouncing (batch-window) — Multiple rapid file changes are batched together to avoid excessive rebuilds during development
Control Points
- NODE_OPTIONS Memory Limit (runtime-toggle) — Controls: Node.js heap size allocation, automatically set to 4096MB if not already configured. Default: --max-old-space-size=4096
- EVIDENCE_STRICT_MODE (env-var) — Controls: Whether Evidence enforces stricter validation and error handling during builds. Default: true in production builds
- DEV Environment Flag (env-var) — Controls: Switches between development and preview mode testing, affecting report output directories. Default: undefined in preview, true in dev mode
- Base Path Configuration (feature-flag) — Controls: URL path prefix for deployed Evidence sites, affects asset linking and routing. Default: configurable per deployment
Technology Stack
Provides the web framework foundation for generating static sites from markdown and components
Powers the development server with hot module reloading and handles the build process
Enables comprehensive end-to-end testing across different browsers and deployment scenarios
Watches file system changes during development to trigger automatic rebuilds and synchronization
Manages the monorepo workspace with linked packages and coordinates build scripts across all packages
Provides in-browser SQL execution capabilities for client-side data processing
Supplies utility-first styling system for Evidence components and themes
Renders interactive charts and visualizations from SQL query results
Key Components
- getRunner (executor) — Executes JavaScript files as data sources by importing them and extracting their exported data array, inferring column types from the first row
packages/datasources/javascript/index.js - EvidenceCLI (orchestrator) — Main command-line interface that orchestrates project creation, development server startup, file watching, and build processes
packages/evidence/cli.js - populateTemplate (processor) — Creates and maintains the .evidence/template directory by copying framework files and preserving user settings like telemetry profiles
packages/evidence/cli.js - runFileWatcher (monitor) — Watches for changes in pages and source files using chokidar, automatically syncing modifications to the template directory while ignoring system pages
packages/evidence/cli.js - createEvidenceProject (factory) — Scaffolds new Evidence test projects by generating package.json, Playwright configuration, and default test files
e2e/create-e2e-project.js - FileSystemUtils (adapter) — Provides transactional file system operations for testing, tracking all changes to enable complete rollback after test completion
e2e/hmr/tests/fs-utils.js
Package Structure
End-to-end test utilities and configuration shared across all test packages
Tests Evidence projects deployed with custom base paths
Basic functionality tests for Evidence project creation and rendering
Performance tests measuring Evidence development server startup times
Hot module reload tests verifying live updates during development
Tests Evidence package creation and distribution workflows
Tests static pre-rendering of SQL queries and components at build time
Tests single-page application mode for Evidence projects
Tests custom theming and styling capabilities
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Fullstack Repositories
Frequently Asked Questions
What is evidence used for?
Converts SQL queries and markdown files into interactive data visualization websites evidence-dev/evidence is a 6-component fullstack written in JavaScript. Data flows through 5 distinct pipeline stages. The codebase contains 553 files.
How is evidence architected?
evidence is organized into 3 architecture layers: Core Framework, Data Connectors, Test Infrastructure. Data flows through 5 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.
How does data flow through evidence?
Data moves through 5 stages: Initialize Evidence Project → Execute SQL Queries → Process Markdown Files → Render Components → Generate Static Site. Evidence processes SQL-embedded markdown files by first setting up a template project structure, then executing SQL queries against configured data sources to generate result sets, and finally rendering these results into interactive components that are built into static websites. The CLI coordinates this entire pipeline while file watchers enable live reloading during development. This pipeline design reflects a complex multi-stage processing system.
What technologies does evidence use?
The core stack includes SvelteKit (Provides the web framework foundation for generating static sites from markdown and components), Vite (Powers the development server with hot module reloading and handles the build process), Playwright (Enables comprehensive end-to-end testing across different browsers and deployment scenarios), Chokidar (Watches file system changes during development to trigger automatic rebuilds and synchronization), pnpm (Manages the monorepo workspace with linked packages and coordinates build scripts across all packages), DuckDB (Provides in-browser SQL execution capabilities for client-side data processing), and 2 more. A focused set of dependencies that keeps the build manageable.
What system dynamics does evidence have?
evidence exhibits 3 data pools (Template Directory, Query Cache), 3 feedback loops, 4 control points, 3 delays. The feedback loops handle polling and cache-invalidation. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does evidence use?
4 design patterns detected: Template-Based Project Structure, Plugin-Based Data Sources, Transactional Testing, Shared Test Configuration.
Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.