How evidence-dev/evidence works
Project type and purpose
• This is an open-source monorepo for “Evidence”: a Business Intelligence-as-Code toolkit.
• Core deliverables include:
• An Evidence CLI/SDK (packages/evidence, packages/lib/sdk) for scaffolding and building SvelteKit-based data-driven sites.
• A VS Code extension (packages/extension) to bootstrap and interact with Evidence projects.
• A suite of data-source connectors (packages/datasources/*) and libraries (universal-sql, telemetry, db-commons).
• UI component libraries (packages/ui/*) for charts, maps, tables.
• Example/demo SvelteKit sites (sites/docs, sites/example-project, sites/test-env).
• End-to-end tests and CI/CD workflows (.github/workflows).
File structure
• Top-level files: pnpm-workspace.yaml, package.json → monorepo management.
• /.github/workflows → CI pipelines for lint, tests, release, e2e.
• /packages → independent npm packages grouped by function:
• datasources: connectors (BigQuery, CSV, DuckDB, etc.)
• evidence & lib/sdk: CLI, Svelte/Vite plugins, configuration, build pipelines
• extension: VS Code integration
• lib: shared utilities (component-utilities, db-commons, preprocess, telemetry, universal-sql)
• /sites → three self-contained SvelteKit sites (docs site, example-project, test-env) showing usage.
• /e2e → Playwright/Vitest based end-to-end test projects for various scenarios.
Examining the README
• Describes Evidence as a code-based BI tool generating websites from Markdown + SQL.
• Key architecture:
• CLI/VS Code extension to initialize projects
• Markdown pages embed SQL → powered by universal-sql engine
• SvelteKit + Vite + Evidence SDK for processing pages, extracting queries, rendering charts
• Ability to plugin data-sources, UI components, layouts
• Docker/CLI/Cloud hosting options
a. Main components
– Developer workflows: VS Code extension & CLI
– Monorepo management: pnpm workspace
– Evidence CLI & SDK: build-time processors, plugin architecture
– Data-source connectors (universal-sql engine)
– UI component libraries
– SvelteKit/Vite build pipeline → static site / SSR
– Example & docs front-end apps
– CI/CD pipelines (GitHub Actions + e2e tests)
– External services: cloud hosting, databases (BigQuery, Postgres, DuckDB, CSV files, etc.)
b. Relationships and interactions
– Developer → launches CLI or VS Code extension → generates new project scaffold
– CLI invokes SDK → reads evidence.config, loads plugins (datasources, components, layouts)
– SDK preprocessors scan Markdown pages → extract SQL → universal-sql executes queries on configured data sources → returns results
– Vite/SvelteKit + Evidence SDK Vite plugins transform page code → generates static HTML/JS/CSS or SSR exports
– Build output → deployed to Evidence Cloud, Vercel, Netlify or other host
– E2E tests (Playwright) exercise sample sites → report back via CI
c. Architectural patterns & principles
– Monorepo with modular packages: code reuse and independent versioning
– Plugin architecture: datasources, components, layout, Vite plugins
– Static site generation + SSR fallback via SvelteKit
– Separation of concerns: CLI/SDK vs. runtime UI vs. build-time processors
– Test-driven: unit tests per package, e2e scenarios
d. Key technologies
– Node.js, pnpm workspace
– TypeScript/JavaScript, Zod schemas for config validation
– SvelteKit & Vite with custom processors
– Playwright and Vitest for e2e & unit testing
– DuckDB, SQL connectors, bigquery, CSV, etc.
– GitHub Actions for CI/CD
Elements
– Clear labels: “VS Code Extension,” “Evidence CLI/SDK,” “Datasource Plugins,” “Universal-SQL Engine,” “SvelteKit/Vite Build,” “Static Site / SSR,” “CI Pipeline,” “Data Storage” (DuckDB, BigQuery, CSV)
• Developer → CLI/Extension → Scaffold → Build
• Build → Vite plugins → SvelteKit → HTML/JS/CSS
• Markdown → Query extraction → SQL execution → Results
• CI → Tests → Release → npm registry
• Orange for runtime libraries (universal-sql, datasources)
• Purple for UI components
• Gray for external services
Be detailed but not overwhelming
• Model each logically distinct package group as its own node or cluster.
• End-to-end flow from writing Markdown + SQL to hosting a fully rendered site.
• CI/CD and testing as first-class citizens in the architecture.