Evidence

Evidence is a self‑hosted, code‑centric business intelligence platform that turns SQL queries and markdown into fully functional, interactive web dashboards. At its core, Evidence compiles a directory of Markdown files—each containing embedded SQL and component directives—into a static site. The rendering engine executes the SQL against configured data sources, injects the results into templated components (charts, tables, maps), and serves a fast, client‑side application that remains responsive even when handling millions of rows. This approach keeps the entire data pipeline in source control, enabling versioning, CI/CD, and reproducibility.

Architecture & Technical Stack

Evidence is built with a modern JavaScript/TypeScript stack. The serverless core runs on Node.js and leverages Deno Runtime for sandboxed query execution. Data connectivity is abstracted through a pluggable Data Source Adapter layer, supporting PostgreSQL, MySQL, BigQuery, Snowflake, and REST/GraphQL APIs. The Markdown processor is powered by MDX‑style syntax, extended with custom directives ({sql}, {chart}) that are parsed by a Babel plugin. Rendering is performed using React components packaged as reusable UI widgets, allowing developers to replace or extend the visual library without touching the Markdown. The final output is a static bundle that can be deployed to any CDN or static‑site host.

Core Capabilities & APIs

• SQL Engine: Evidence parses {sql} blocks, runs them against the configured data source, and returns typed results. It supports parameterized queries and caching layers to avoid redundant round‑trips.
• Component Library: Built‑in charts (bar, line, scatter), tables, and AI chat widgets are exposed as JSX components. Developers can create custom components by exporting React modules to the components/ directory.
• Templating & Control Flow: Markdown supports loops ({% for %}) and conditionals ({% if %}), enabling dynamic page generation (e.g., per‑customer dashboards) from a single template.
• API & Webhooks: Evidence exposes a lightweight REST API for querying data and triggering rebuilds, as well as webhook endpoints that integrate with CI/CD pipelines or external services.

Deployment & Infrastructure

Evidence is intentionally container‑agnostic. A Docker image (evidence-dev/evidence) ships with all dependencies, making it trivial to run on Kubernetes, Docker Compose, or serverless platforms like Vercel and Netlify. For self‑hosted deployments, a single binary can be dropped into any environment that supports Node.js. The static output is CDN‑ready, so scaling is achieved by offloading traffic to edge caches rather than spinning up more instances. The platform also offers a cloud‑managed hosting option (Evidence Cloud) for teams that prefer a fully managed experience.

Integration & Extensibility

The plugin system is exposed through a manifest file (evidence.json) where developers declare data source adapters, component overrides, and custom CLI commands. Evidence’s extensibility is further enhanced by its AI‑powered IDE in VSCode, which provides autocomplete for SQL, Markdown syntax, and component props. Webhooks can be configured to trigger data refreshes or rebuilds when source files change, enabling a fully automated workflow from code commit to live dashboard.

Developer Experience

Evidence prioritizes the modern developer workflow: all artifacts are plain text, stored in Git; syntax errors surface immediately via the VSCode extension; and tests can be written with Jest or Playwright to assert query results and component rendering. Documentation is modular, with dedicated sections for data adapters, component development, and deployment strategies. The community is active on Slack and GitHub, providing quick support for integration questions or plugin development.

Use Cases

• Internal Analytics Portals: Build secure, version‑controlled dashboards for product or finance teams that can be updated through pull requests.
• Embedded Analytics: Generate lightweight, static reports that can be embedded in SaaS products or customer portals without exposing backend APIs.
• Data‑Driven Reports: Automate quarterly business reviews by templating markdown files that pull fresh data each build.
• AI‑Enhanced Data Exploration: Leverage the built‑in AI chat component to let stakeholders query data conversationally, with queries automatically translated into SQL.

Advantages

Evidence offers performance (sub‑second rendering on large datasets) and flexibility (full control over SQL, markdown, and components). Its MIT license removes licensing friction, while the open‑source nature encourages community contributions. Compared to drag‑and‑drop BI tools, Evidence eliminates the cognitive load of visual query builders and aligns closely with DevOps practices, making it an attractive choice for engineering teams that value reproducibility, testability, and fine‑grained control over their data products.