Concepts
How anfra fits together, and the terms used across these docs
An anfra project is a folder of code in Git. It holds two things: a semantic layer that defines what your data means, and data apps that show it. anfra Server connects them: when a reader uses an app, the server turns each request into a query on the semantic layer and runs it on your warehouse.
- Reader — Opens an app in the browser
- Data app
- Your page — Your HTML, CSS and charting library: draws the results and handles clicks
- anfra SDK — Declares queries, controls and cross-filters, and sends them to anfra Server
- anfra Server — anfra serve: resolves each SDK request through the semantic layer and runs it
- Warehouse — Your database. Every query runs here
- Semantic layer — Data models, datasets, metrics and dimensions, as AML in your project
- Coding agent — Claude Code, Codex or Cursor, with the anfra skills
- reader → page (interacts)
- page → sdk (uses)
- sdk → server (semantic queries)
- server → warehouse (SQL)
- semantic → server (definitions)
- agent → page (builds)
- agent → semantic (models)
Architecture
Your project
Everything you write lives in one Git repository, as plain files:
models/anddatasets/hold the semantic layer, in AML.apps/holds the data apps, one HTML file each..anfra/holds the project's config, such as warehouse connections.
Because it is all code, a change to a metric or an app is reviewed, versioned and rolled back like any other change. See Project structure.
The semantic layer
The semantic layer defines your business data once: which tables matter, how they join, and what "revenue" or "active user" means. anfra uses AMQL: AML to define the semantic layer, and AQL to query it.
Apps and agents query the semantic layer by name, such as "revenue by month", never with hand-written SQL. anfra generates the SQL, including the joins, so every app gets the same answer to the same question. See Model your data.
Data apps and the anfra SDK
A data app is an HTML page: a dashboard, a report or a custom analysis, built with any HTML, CSS and charting library. The page uses the anfra SDK to declare the data each view needs and how its filters, drill-downs and clicks connect.
The page draws the results. It doesn't build queries, apply filters or compute metrics, so its numbers can't drift from the semantic layer. See Semantic UI.
anfra Server
anfra Server, started with anfra serve, sits between your apps and your warehouse. For each interaction, it applies the reader's choices to the app's queries, resolves them through the semantic layer, generates SQL and runs it on the warehouse.
It also serves the apps themselves, with an Inspect panel showing the query and SQL behind every view, and an API and MCP server that let agents read your models.
Your warehouse
Your data stays in your warehouse, and every query runs there. anfra connects to it with the credentials in .anfra/data_sources.yml. See Data sources.
Coding agents and skills
anfra includes no AI model. You bring your own coding agent, such as Claude Code, Codex or Cursor, and the anfra skills teach it to model data, write queries and build apps. The agent writes code into your project, and you review it like a teammate's. See Set up your coding agent.
anfra Core and anfra Cloud
anfra Core is the open-source engine: the anfra binary, which runs on your machine or a server. anfra Cloud is the hosted product built on the same engine. It adds users and SSO, row-level permissions, sharing links and audit logs, and is not available yet. A project built with Core runs unchanged on Cloud.
How a number reaches the page
- A reader opens an app, or changes a filter, drill or selection in it.
- The SDK sends the app's queries, with the reader's current choices, to anfra Server.
- The server applies those choices to each affected query and resolves it through the semantic layer into SQL.
- The warehouse runs the SQL and returns the rows.
- The page draws the results. The Inspect panel shows the AQL and SQL that produced each one.
Key terms
Semantic layer
| Term | Meaning |
|---|---|
| Data model | Maps one table or SQL query to dimensions and measures. |
| Dataset | Joins data models through relationships. It is what apps and agents query. |
| Metric | A named calculation on a dataset, such as revenue. It can span models and build on other metrics. |
| Measure | An aggregation on a single data model. |
| Dimension | A field to group or filter by, such as a date, status or country. |
| Relationship | How two models in a dataset join, and which side is "many". |
| AML | The language the semantic layer is written in, in .aml files. |
| AQL | The language for querying a dataset, as in explore { dimensions { … } measures { … } }. |
Apps
| Term | Meaning |
|---|---|
| Data app | One HTML file in apps/, served by anfra serve. |
| Query | The data one view needs: a dataset and an AQL query. |
| Control | An input the reader changes: a filter or a date drill. |
| Control mapping | Which queries a control applies to, and on which field. |
| Cross-filter | Filters one query by the rows a reader selects in another. |
| Semantic UI | The SDK's model of an app: queries, controls and the mappings between them. |
| Inspect | Shows the AQL and SQL that actually ran for each query. |