Skip to content
Browse documentation
More resources

Architecture & source map

Understand how the public API connects to the implementation.

Public entry points

index.ts registers all Node.js engines and exports AVA plus public types. index.browser.ts registers only JavaScript. ava.ts coordinates source state, data model, events, and engine lifecycle.

Source directory map

SourceResponsibility
ava.tsPublic API, source state, and lifecycle
types.tsPublic type definitions and schema-derived types
contracts/API contracts for source, schema, profile, semantic, query, analyze, suggest and visualization
engines.tsEngine selection and registry
analysis/Direct and loop strategies
duckdb/SQL engine, source loaders, and profiling
interpreter/javascript/In-memory data and JavaScript execution
interpreter/python/pandas execution and source validation
remote/supabase/Management API, schema, and profiling
remote/clickhouse/Remote SQL, schema, and profiling
remote/snowflake/Snowflake driver session, schema, and profiling
query/Query generation and dialect validation
visualization/Chart advice, GPT-Vis config, and HTML generation
suggest/Suggested analysis questions
event/Event types and payloads
cli/Commands and local dataset sessions
util/Catalog assembly, model formatting, metric execution rules and result bounds

Contracts follow the public API. source/ keeps each source type's runtime schema in its own file, including CSV/JSON/Excel reader options; source/index.ts assembles the source union and source/shared.ts holds common file and connection fields. schema.ts, profile.ts, semantic.ts, query.ts, analyze.ts, translate.ts and suggest.ts define each API's runtime input and output schemas. visualize.ts holds the chart specification shared by recommend(), viz() and visualize(). Cross-API JSON values and data-model building blocks live in shared/.

types.ts defines public configuration, engine, strategy and data types; data types are inferred from the runtime schemas. The data-model builder owns its stricter assembly input validation, derived from the public metadata fields. Modules import API schemas through contracts/index.ts, internal schemas from their owning modules and types from types.ts; contract definitions reference each other directly to avoid circular dependencies. index.ts and index.browser.ts export API input/output schemas and types with their existing names. CLI wire messages, AI-stage response formats and interpreter-specific restrictions remain local to their modules.

Method to module

Public methodResponsibility / implementation
source() / schema() / dispose()Source state and engine lifecycle in ava.ts
profile()Per-engine profiling; shared metric contracts in util/profile.ts
analyze()Dispatch to analysis/direct.ts or analysis/loop.ts
translate() / query()Engine getDSL() / execute()
suggest()suggest/index.ts
recommend()visualization/advisor.ts and config generation
viz()HTML wrapping in visualization/generator.ts
visualize()Compose recommend() and viz()

Context and state

An AVA instance owns one active engine and its schema/profile cache. source() loads data; schema() discovers structure on first use. profile() computes and retains fresh observations; the data model is assembled from cached metadata when needed. Reloading or disposal clears both caches.

Engines retain data and connections. Their load() returns no metadata; schema() discovers it, profile(schema, options?) computes observations, and getDSL(query, dataModel) consumes AVA's data model. Shared data validators live in contracts/; catalog assembly and metric execution helpers stay in util/.

Analysis strategies share a runtime containing the engine, model configuration, data model, and event emitter. Query result limits are normalized through shared utilities.

Documentation organization

Each topic is a separate MDX file under site/content/docs/, grouped into data/, analysis/, visualization/, engines/, and reference/. This mirrors the public capabilities without exposing every internal helper as a separate user-facing page.