# agno-agi/dash architecture

> Architecture diagram of the GitHub repository agno-agi/dash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agno-agi/dash
- Repository: https://github.com/agno-agi/dash

## Overview

1. **What this repo is**
   - Dash is a Python-based **text-to-SQL data agent** for the F1 sample domain.
   - The architecture is centered on one core loop: **understand the question, retrieve grounding context, generate SQL, run it, explain the result, and remember what happened**.

2. **Two runtime entrypoints**
   - `app/main.py` is the **service entrypoint** used when running Dash as an API server.
   - `dash/__main__.py` exposes the same core package as a **CLI mode**.
   - Both appear to share the same underlying agent implementation in `dash/agent.py`.

3. **Core orchestration layer**
   - `dash/agent.py` is the main orchestrator.
   - It likely coordinates prompt construction, context retrieval, SQL generation, execution, result interpretation, and learning/persistence.
   - This is the main boundary to draw in the diagram: everything else supports this loop.

4. **Grounding / context subsystem**
   - `dash/context/semantic_model.py` and `dash/context/business_rules.py` define the agent’s semantic layer.
   - This is where raw schema is translated into human-meaningful concepts like metrics, business rules, and table meanings.
   - The repo’s “6 layers of context” concept is implemented around this subsystem plus external retrieval.

5. **Curated knowledge assets**
   - `dash/knowledge/tables/*.json` captures table descriptions, use cases, and caveats.
   - `dash/knowledge/business/*.json` stores metric definitions and business rules.
   - `dash/knowledge/queries/*.sql` stores validated query patterns the agent can reuse.
   - These files are versioned in the repo, then loaded into runtime storage by scripts.

6. **Runtime schema introspection**
   - `dash/tools/introspect.py` provides live schema inspection.
   - This is the “current state” boundary: it lets the agent adapt to schema changes that are not reflected in static knowledge.
   - In the architecture, place this as a bridge from the agent to the operational database.

7. **Learning and reuse**
   - `dash/tools/save_query.py` and the “learning” flow described in the README support the self-improving loop.
   - Successful queries and discovered fixes become reusable knowledge; recurring failures become learned patterns.
   - This is the key feedback path that makes the system improve without retraining.

8. **Database layer**
   - `db/session.py` and `db/url.py` isolate database connectivity.
   - The app’s working data, loaded knowledge, and learned artifacts are all expected to be stored behind this DB boundary.
   - `dash/scripts/load_data.py` seeds the sample dataset; `dash/scripts/load_knowledge.py` imports the curated context into the system.

9. **Evaluation harness**
   - `dash/evals/test_cases.py`, `dash/evals/grader.py`, and `dash/evals/run_evals.py` form an offline benchmark subsystem.
   - This is separate from production serving and is used to validate question answering, SQL quality, and groundedness.
   - In a diagram, keep evals outside the main request path.

10. **Deployment and operations**
   - `Dockerfile`, `compose.yaml`, and `scripts/*` define local and production operations.
   - `railway.json` and the Railway scripts show a deployment path to Railway.
   - `.github/workflows/validate.yml` suggests CI validation of the repo before deployment.

11. **External dependencies that matter**
   - `OPENAI_API_KEY` is required for the LLM-backed agent behavior.
   - `EXA_API_KEY` is optional for external web search / institutional knowledge.
   - The README also references the Agno ecosystem for learning behavior, which is part of the agent’s adaptive loop.

12. **How data flows through the system**
   - User question enters via API or CLI.
   - The agent retrieves static knowledge, learned patterns, and live schema context.
   - It generates SQL, executes against the database, then interprets results into a useful answer.
   - On success it may store reusable knowledge; on failure it stores a learning so the same mistake is less likely next time.

13. **Good diagram boundaries**
   - Draw the core service boundary around `dash/` plus `app/`.
   - Draw the database as an external persistence boundary.
   - Draw `dash/knowledge/` as a repo-managed knowledge source feeding ingestion scripts.
   - Draw `dash/evals/` and `scripts/` as offline/supporting systems, not part of the request runtime.

Main entry points: [`dash/agent.py`](https://github.com/agno-agi/dash/blob/main/dash/agent.py) (Agent loop), [`db/session.py`](https://github.com/agno-agi/dash/blob/main/db/session.py) (DB session), [`dash/evals/run_evals.py`](https://github.com/agno-agi/dash/blob/main/dash/evals/run_evals.py) (Eval runner), [`app/main.py`](https://github.com/agno-agi/dash/blob/main/app/main.py) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Runtime service"]
  node_app_main["API server<br/>entrypoint<br/>[main.py]"]
  node_dash_cli["CLI mode<br/>entrypoint<br/>[__main__.py]"]
  node_agent{{"Agent loop<br/>orchestrator<br/>[agent.py]"}}
  node_introspect(("Schema introspect<br/>tool<br/>[introspect.py]"))
  node_save_query(("Save query<br/>tool<br/>[save_query.py]"))
end

subgraph group_knowledge["Knowledge layer"]
  node_semantic_model["Semantic model<br/>context model<br/>[semantic_model.py]"]
  node_business_rules["Business rules<br/>context rules<br/>[business_rules.py]"]
  node_table_docs["Table docs<br/>knowledge asset"]
  node_metric_defs["Metric defs<br/>knowledge asset<br/>[metrics.json]"]
  node_query_patterns["Query patterns<br/>knowledge asset<br/>[common_queries.sql]"]
end

subgraph group_data["Database boundary"]
  node_db_session[("DB session<br/>db access<br/>[session.py]")]
  node_db_url["DB URL<br/>db config<br/>[url.py]"]
  node_operational_db[("Operational DB<br/>database")]
end

subgraph group_support["Support systems"]
  node_load_knowledge["Load knowledge<br/>ingestion<br/>[load_knowledge.py]"]
  node_load_data["Seed data<br/>ingestion<br/>[load_data.py]"]
  node_eval_runner["Eval runner<br/>evaluation<br/>[run_evals.py]"]
  node_grader["Grader<br/>evaluation<br/>[grader.py]"]
  node_test_cases["Test cases<br/>evaluation corpus<br/>[test_cases.py]"]
  node_deployment["Deployment<br/>ops"]
end

node_app_main -->|"requests"| node_agent
node_dash_cli -->|"invokes"| node_agent
node_agent -->|"grounds in"| node_semantic_model
node_agent -->|"applies"| node_business_rules
node_agent -->|"retrieves"| node_table_docs
node_agent -->|"retrieves"| node_metric_defs
node_agent -->|"reuses"| node_query_patterns
node_agent -->|"inspects"| node_introspect
node_introspect -->|"reads schema via"| node_db_session
node_agent -->|"executes against"| node_db_session
node_db_session -->|"configured by"| node_db_url
node_db_session -->|"connects to"| node_operational_db
node_save_query -->|"persists via"| node_db_session
node_agent -->|"learns"| node_save_query
node_load_knowledge -->|"imports"| node_operational_db
node_load_data -->|"seeds"| node_operational_db
node_eval_runner -->|"uses"| node_test_cases
node_eval_runner -->|"scores with"| node_grader
node_grader -.->|"evaluates"| node_agent
node_deployment -->|"ships"| node_app_main
node_deployment -.->|"supports"| node_eval_runner

click node_app_main "https://github.com/agno-agi/dash/blob/main/app/main.py"
click node_dash_cli "https://github.com/agno-agi/dash/blob/main/dash/__main__.py"
click node_agent "https://github.com/agno-agi/dash/blob/main/dash/agent.py"
click node_semantic_model "https://github.com/agno-agi/dash/blob/main/dash/context/semantic_model.py"
click node_business_rules "https://github.com/agno-agi/dash/blob/main/dash/context/business_rules.py"
click node_table_docs "https://github.com/agno-agi/dash/tree/main/dash/knowledge/tables"
click node_metric_defs "https://github.com/agno-agi/dash/blob/main/dash/knowledge/business/metrics.json"
click node_query_patterns "https://github.com/agno-agi/dash/blob/main/dash/knowledge/queries/common_queries.sql"
click node_introspect "https://github.com/agno-agi/dash/blob/main/dash/tools/introspect.py"
click node_save_query "https://github.com/agno-agi/dash/blob/main/dash/tools/save_query.py"
click node_db_session "https://github.com/agno-agi/dash/blob/main/db/session.py"
click node_db_url "https://github.com/agno-agi/dash/blob/main/db/url.py"
click node_load_knowledge "https://github.com/agno-agi/dash/blob/main/dash/scripts/load_knowledge.py"
click node_load_data "https://github.com/agno-agi/dash/blob/main/dash/scripts/load_data.py"
click node_eval_runner "https://github.com/agno-agi/dash/blob/main/dash/evals/run_evals.py"
click node_grader "https://github.com/agno-agi/dash/blob/main/dash/evals/grader.py"
click node_test_cases "https://github.com/agno-agi/dash/blob/main/dash/evals/test_cases.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_main,node_dash_cli,node_agent,node_introspect,node_save_query toneBlue
class node_semantic_model,node_business_rules,node_table_docs,node_metric_defs,node_query_patterns toneAmber
class node_db_session,node_db_url,node_operational_db toneMint
class node_load_knowledge,node_load_data,node_eval_runner,node_grader,node_test_cases,node_deployment toneRose
```

## Components

### Runtime service

API and CLI entrypoints plus the core agent loop.

- [API server](https://github.com/agno-agi/dash/blob/main/app/main.py): entrypoint · Runs Dash as a service endpoint. · `app/main.py`
- [CLI mode](https://github.com/agno-agi/dash/blob/main/dash/__main__.py): entrypoint · Runs the same package in command-line mode. · `dash/__main__.py`
- [Agent loop](https://github.com/agno-agi/dash/blob/main/dash/agent.py): orchestrator · Coordinates question understanding, retrieval, SQL generation, execution, explanation, and memory. · `dash/agent.py`
- [Schema introspect](https://github.com/agno-agi/dash/blob/main/dash/tools/introspect.py): tool · Inspects the live database schema to adapt to current state. · `dash/tools/introspect.py`
- [Save query](https://github.com/agno-agi/dash/blob/main/dash/tools/save_query.py): tool · Persists successful queries and learned fixes for reuse. · `dash/tools/save_query.py`

### Knowledge layer

Repo-managed semantic, business, and query assets that ground the agent.

- [Semantic model](https://github.com/agno-agi/dash/blob/main/dash/context/semantic_model.py): context model · Maps raw schema into business concepts and metric meaning. · `dash/context/semantic_model.py`
- [Business rules](https://github.com/agno-agi/dash/blob/main/dash/context/business_rules.py): context rules · Encodes domain caveats and rules that constrain answers. · `dash/context/business_rules.py`
- [Table docs](https://github.com/agno-agi/dash/tree/main/dash/knowledge/tables): knowledge asset · Curated table descriptions, use cases, and caveats. · `dash/knowledge/tables`
- [Metric defs](https://github.com/agno-agi/dash/blob/main/dash/knowledge/business/metrics.json): knowledge asset · Curated business metric definitions and rule metadata. · `dash/knowledge/business/metrics.json`
- [Query patterns](https://github.com/agno-agi/dash/blob/main/dash/knowledge/queries/common_queries.sql): knowledge asset · Validated SQL patterns that can be reused by the agent. · `dash/knowledge/queries/common_queries.sql`

### Database boundary

Persistence and live operational schema access.

- [DB session](https://github.com/agno-agi/dash/blob/main/db/session.py): db access · Connection/session boundary for application persistence. · `db/session.py`
- [DB URL](https://github.com/agno-agi/dash/blob/main/db/url.py): db config · Builds or resolves the database connection URL. · `db/url.py`
- **Operational DB**: database · Stores working data, knowledge imports, and learned artifacts.

### Support systems

Offline loading, evaluation, and deployment tooling.

- [Load knowledge](https://github.com/agno-agi/dash/blob/main/dash/scripts/load_knowledge.py): ingestion · Imports curated context assets into runtime storage. · `dash/scripts/load_knowledge.py`
- [Seed data](https://github.com/agno-agi/dash/blob/main/dash/scripts/load_data.py): ingestion · Loads the sample F1 dataset used by the agent and evals. · `dash/scripts/load_data.py`
- [Eval runner](https://github.com/agno-agi/dash/blob/main/dash/evals/run_evals.py): evaluation · Runs offline benchmark cases against the system. · `dash/evals/run_evals.py`
- [Grader](https://github.com/agno-agi/dash/blob/main/dash/evals/grader.py): evaluation · Scores answer quality, SQL validity, and groundedness. · `dash/evals/grader.py`
- [Test cases](https://github.com/agno-agi/dash/blob/main/dash/evals/test_cases.py): evaluation corpus · Benchmark questions and expected behaviors. · `dash/evals/test_cases.py`
- **Deployment**: ops · Container, compose, Railway, and CI deployment boundary.

## Connections

- API server → Agent loop: requests · API requests enter the core agent loop.
- CLI mode → Agent loop: invokes · CLI mode reuses the same agent implementation.
- Agent loop → Semantic model: grounds in · Uses semantic context to interpret tables and metrics.
- Agent loop → Business rules: applies · Constrains reasoning with domain rules and caveats.
- Agent loop → Table docs: retrieves · Pulls table-level documentation as grounding context.
- Agent loop → Metric defs: retrieves · Pulls metric definitions for domain meaning.
- Agent loop → Query patterns: reuses · Reuses validated SQL patterns when applicable.
- Agent loop → Schema introspect: inspects · Checks the live schema before generating SQL.
- Schema introspect → DB session: reads schema via · Schema inspection uses the database session boundary.
- Agent loop → DB session: executes against · Runs generated SQL and reads results from the database.
- DB session → DB URL: configured by · Session connectivity is built from the database URL config.
- DB session → Operational DB: connects to · Application state and data persist in the operational database.
- Save query → DB session: persists via · Writes learned queries and fixes back through the DB boundary.
- Agent loop → Save query: learns · Successful or corrected runs are stored for future reuse.
- Load knowledge → Operational DB: imports · Loads curated knowledge assets into runtime storage.
- Seed data → Operational DB: seeds · Populates the sample domain data.
- Eval runner → Test cases: uses · Evaluation runs are driven by benchmark cases.
- Eval runner → Grader: scores with · Results are judged by the grader.
- Grader → Agent loop: evaluates · Offline grading measures the behavior of the core agent.
- Deployment → API server: ships · Container and deployment tooling package the service entrypoint.
- Deployment → Eval runner: supports · Ops tooling also supports offline validation workflows.
