# akashn-tech/lens architecture

> Architecture diagram of the GitHub repository akashn-tech/lens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akashn-tech/lens
- Repository: https://github.com/akashn-tech/lens

## Overview

XYMP Lens is a database exploration and natural-language analytics product. Users create projects for connected databases or spreadsheets, inspect their schema, ask questions in a conversational playground, and review query results or synthesized analysis. The backend separates project and conversation APIs, SQL and analysis agents, database connectors, and spreadsheet ingestion. The frontend’s landing and table views are represented alongside those runtime layers. Several spreadsheet and connector capabilities are documented by module names and references, but their internal call paths were not sampled, so uncertain links are omitted.

Main entry points: [`backend/app/api/projects.py`](https://github.com/akashn-tech/lens/blob/main/backend/app/api/projects.py) (Project API), [`backend/app/agent/analysis_agent.py`](https://github.com/akashn-tech/lens/blob/main/backend/app/agent/analysis_agent.py) (Analysis chain), [`backend/app/main.py`](https://github.com/akashn-tech/lens/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/api/sql_routes.py`](https://github.com/akashn-tech/lens/blob/main/backend/app/api/sql_routes.py) (SQL API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["App routing<br/>[App.tsx]"]
  node_landing["Project landing<br/>[landing-page.tsx]"]
  node_tables["Table explorer<br/>[tables-page.tsx]"]
  node_playground["Playground chat"]
  node_results["Query results"]
end

subgraph group_api["Backend API"]
  node_main["FastAPI app<br/>[main.py]"]
  node_projects_api["Project API<br/>[projects.py]"]
  node_sql_api["SQL API<br/>[sql_routes.py]"]
  node_analysis_api["Analysis API<br/>[analysis_routes.py]"]
  node_conversation_api["Conversation API"]
end

subgraph group_agents["SQL and analysis"]
  node_sql_generator["SQL generation<br/>[sql_generator.py]"]
  node_analysis_agent["Analysis chain<br/>[analysis_agent.py]"]
  node_schema_introspection["Schema introspection"]
  node_sql_executor["SQL execution agent<br/>[sql_executor.py]"]
end

subgraph group_data["Database access"]
  node_query_runner["Query runner<br/>[query_runner.py]"]
  node_connectors["DB connectors"]
  node_duckdb["DuckDB connector<br/>[duckdb_file.py]"]
  node_xlsx_ingest["Spreadsheet ingestion<br/>[xlsx_ingest.py]"]
  node_schema_catalog[("Schema catalog<br/>[schema_catalog.py]")]
end

subgraph group_persistence["Projects and state"]
  node_app_db[("Project database<br/>[app_db.py]")]
  node_learnings[("Query learnings<br/>[learnings.py]")]
  node_conversations[("Conversation store<br/>[conversations.py]")]
  node_storage["Supabase file storage"]
end

node_user(("User"))
node_supabase[("Supabase")]
node_openai["OpenAI model"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_landing
node_app -->|"routes to"| node_tables
node_user -.->|"asks questions"| node_playground
node_playground -.->|"renders results"| node_results
node_main -->|"registers"| node_projects_api
node_main -->|"registers"| node_sql_api
node_main -->|"registers"| node_analysis_api
node_main -->|"registers"| node_conversation_api
node_projects_api -->|"manages projects"| node_app_db
node_projects_api -->|"updates catalog"| node_schema_catalog
node_projects_api -->|"ingests files"| node_xlsx_ingest
node_projects_api -->|"stores files"| node_storage
node_storage -->|"uploads files"| node_supabase
node_sql_api -->|"generates SQL"| node_sql_generator
node_sql_api -->|"executes SQL"| node_sql_executor
node_sql_api -->|"records attempts"| node_learnings
node_analysis_api -->|"runs analysis"| node_analysis_agent
node_analysis_api -->|"persists turns"| node_conversations
node_analysis_api -->|"records attempts"| node_learnings
node_conversation_api -->|"checks projects"| node_app_db
node_conversation_api -->|"loads conversations"| node_conversations
node_sql_generator -->|"introspects schema"| node_schema_introspection
node_sql_generator -->|"loads learnings"| node_learnings
node_analysis_agent -->|"introspects schema"| node_schema_introspection
node_analysis_agent -->|"executes queries"| node_sql_executor
node_analysis_agent -->|"records attempts"| node_learnings
node_analysis_agent -.->|"requests model"| node_openai
node_sql_generator -.->|"requests model"| node_openai
node_sql_executor -->|"delegates execution"| node_query_runner
node_query_runner -->|"loads project"| node_app_db
node_query_runner -->|"selects connector"| node_connectors
node_connectors -.->|"supports engine"| node_duckdb
node_app_db -.->|"stores project data"| node_supabase

click node_app "https://github.com/akashn-tech/lens/blob/main/frontend/src/App.tsx"
click node_landing "https://github.com/akashn-tech/lens/blob/main/frontend/src/pages/landing-page.tsx"
click node_tables "https://github.com/akashn-tech/lens/blob/main/frontend/src/pages/tables-page.tsx"
click node_playground "https://github.com/akashn-tech/lens/blob/main/frontend/src/components/playground/playground-chat.tsx"
click node_results "https://github.com/akashn-tech/lens/blob/main/frontend/src/components/query-result/query-result-renderer.tsx"
click node_main "https://github.com/akashn-tech/lens/blob/main/backend/app/main.py"
click node_projects_api "https://github.com/akashn-tech/lens/blob/main/backend/app/api/projects.py"
click node_sql_api "https://github.com/akashn-tech/lens/blob/main/backend/app/api/sql_routes.py"
click node_analysis_api "https://github.com/akashn-tech/lens/blob/main/backend/app/api/analysis_routes.py"
click node_conversation_api "https://github.com/akashn-tech/lens/blob/main/backend/app/api/conversation_routes.py"
click node_sql_generator "https://github.com/akashn-tech/lens/blob/main/backend/app/agent/sql_generator.py"
click node_analysis_agent "https://github.com/akashn-tech/lens/blob/main/backend/app/agent/analysis_agent.py"
click node_schema_introspection "https://github.com/akashn-tech/lens/blob/main/backend/app/agent/introspect_schema.py"
click node_sql_executor "https://github.com/akashn-tech/lens/blob/main/backend/app/agent/sql_executor.py"
click node_query_runner "https://github.com/akashn-tech/lens/blob/main/backend/app/db/query_runner.py"
click node_connectors "https://github.com/akashn-tech/lens/tree/main/backend/app/db/connectors"
click node_duckdb "https://github.com/akashn-tech/lens/blob/main/backend/app/db/connectors/duckdb_file.py"
click node_xlsx_ingest "https://github.com/akashn-tech/lens/blob/main/backend/app/storage/xlsx_ingest.py"
click node_schema_catalog "https://github.com/akashn-tech/lens/blob/main/backend/app/db/schema_catalog.py"
click node_app_db "https://github.com/akashn-tech/lens/blob/main/backend/app/db/app_db.py"
click node_learnings "https://github.com/akashn-tech/lens/blob/main/backend/app/db/learnings.py"
click node_conversations "https://github.com/akashn-tech/lens/blob/main/backend/app/db/conversations.py"
click node_storage "https://github.com/akashn-tech/lens/blob/main/backend/app/storage/supabase_storage.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,node_landing,node_tables,node_playground,node_results,node_user toneBlue
class node_main,node_projects_api,node_sql_api,node_analysis_api,node_conversation_api,node_supabase toneAmber
class node_sql_generator,node_analysis_agent,node_schema_introspection,node_sql_executor toneMint
class node_query_runner,node_connectors,node_duckdb,node_xlsx_ingest,node_schema_catalog toneRose
class node_app_db,node_learnings,node_conversations,node_storage,node_openai toneIndigo
```

## Components

### User interface

- [App routing](https://github.com/akashn-tech/lens/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Project landing](https://github.com/akashn-tech/lens/blob/main/frontend/src/pages/landing-page.tsx): `frontend/src/pages/landing-page.tsx`
- [Table explorer](https://github.com/akashn-tech/lens/blob/main/frontend/src/pages/tables-page.tsx): `frontend/src/pages/tables-page.tsx`
- [Playground chat](https://github.com/akashn-tech/lens/blob/main/frontend/src/components/playground/playground-chat.tsx): `frontend/src/components/playground/playground-chat.tsx`
- [Query results](https://github.com/akashn-tech/lens/blob/main/frontend/src/components/query-result/query-result-renderer.tsx): `frontend/src/components/query-result/query-result-renderer.tsx`

### Backend API

- [FastAPI app](https://github.com/akashn-tech/lens/blob/main/backend/app/main.py): `backend/app/main.py`
- [Project API](https://github.com/akashn-tech/lens/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [SQL API](https://github.com/akashn-tech/lens/blob/main/backend/app/api/sql_routes.py): `backend/app/api/sql_routes.py`
- [Analysis API](https://github.com/akashn-tech/lens/blob/main/backend/app/api/analysis_routes.py): `backend/app/api/analysis_routes.py`
- [Conversation API](https://github.com/akashn-tech/lens/blob/main/backend/app/api/conversation_routes.py): `backend/app/api/conversation_routes.py`

### SQL and analysis

- [SQL generation](https://github.com/akashn-tech/lens/blob/main/backend/app/agent/sql_generator.py): `backend/app/agent/sql_generator.py`
- [Analysis chain](https://github.com/akashn-tech/lens/blob/main/backend/app/agent/analysis_agent.py): `backend/app/agent/analysis_agent.py`
- [Schema introspection](https://github.com/akashn-tech/lens/blob/main/backend/app/agent/introspect_schema.py): `backend/app/agent/introspect_schema.py`
- [SQL execution agent](https://github.com/akashn-tech/lens/blob/main/backend/app/agent/sql_executor.py): `backend/app/agent/sql_executor.py`

### Database access

- [Query runner](https://github.com/akashn-tech/lens/blob/main/backend/app/db/query_runner.py): `backend/app/db/query_runner.py`
- [DB connectors](https://github.com/akashn-tech/lens/tree/main/backend/app/db/connectors): `backend/app/db/connectors`
- [DuckDB connector](https://github.com/akashn-tech/lens/blob/main/backend/app/db/connectors/duckdb_file.py): `backend/app/db/connectors/duckdb_file.py`
- [Spreadsheet ingestion](https://github.com/akashn-tech/lens/blob/main/backend/app/storage/xlsx_ingest.py): `backend/app/storage/xlsx_ingest.py`
- [Schema catalog](https://github.com/akashn-tech/lens/blob/main/backend/app/db/schema_catalog.py): `backend/app/db/schema_catalog.py`

### Projects and state

- [Project database](https://github.com/akashn-tech/lens/blob/main/backend/app/db/app_db.py): `backend/app/db/app_db.py`
- [Query learnings](https://github.com/akashn-tech/lens/blob/main/backend/app/db/learnings.py): `backend/app/db/learnings.py`
- [Conversation store](https://github.com/akashn-tech/lens/blob/main/backend/app/db/conversations.py): `backend/app/db/conversations.py`
- [Supabase file storage](https://github.com/akashn-tech/lens/blob/main/backend/app/storage/supabase_storage.py): `backend/app/storage/supabase_storage.py`

### Other components

- **User**
- **Supabase**
- **OpenAI model**

## Connections

- User → App routing: uses (evidence: `frontend/src/App.tsx`)
- App routing → Project landing: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Table explorer: routes to (evidence: `frontend/src/App.tsx`)
- User → Playground chat: asks questions
- Playground chat → Query results: renders results
- FastAPI app → Project API: registers (evidence: `backend/app/main.py`)
- FastAPI app → SQL API: registers (evidence: `backend/app/main.py`)
- FastAPI app → Analysis API: registers (evidence: `backend/app/main.py`)
- FastAPI app → Conversation API: registers (evidence: `backend/app/main.py`)
- Project API → Project database: manages projects (evidence: `backend/app/api/projects.py`)
- Project API → Schema catalog: updates catalog (evidence: `backend/app/api/projects.py`)
- Project API → Spreadsheet ingestion: ingests files (evidence: `backend/app/api/projects.py`)
- Project API → Supabase file storage: stores files (evidence: `backend/app/api/projects.py`)
- Supabase file storage → Supabase: uploads files (evidence: `backend/app/storage/supabase_storage.py`)
- SQL API → SQL generation: generates SQL (evidence: `backend/app/api/sql_routes.py`)
- SQL API → SQL execution agent: executes SQL (evidence: `backend/app/api/sql_routes.py`)
- SQL API → Query learnings: records attempts (evidence: `backend/app/api/sql_routes.py`)
- Analysis API → Analysis chain: runs analysis (evidence: `backend/app/api/analysis_routes.py`)
- Analysis API → Conversation store: persists turns (evidence: `backend/app/api/analysis_routes.py`)
- Analysis API → Query learnings: records attempts (evidence: `backend/app/api/analysis_routes.py`)
- Conversation API → Project database: checks projects (evidence: `backend/app/api/conversation_routes.py`)
- Conversation API → Conversation store: loads conversations (evidence: `backend/app/api/conversation_routes.py`)
- SQL generation → Schema introspection: introspects schema (evidence: `backend/app/agent/sql_generator.py`)
- SQL generation → Query learnings: loads learnings (evidence: `backend/app/agent/sql_generator.py`)
- Analysis chain → Schema introspection: introspects schema (evidence: `backend/app/agent/analysis_agent.py`)
- Analysis chain → SQL execution agent: executes queries (evidence: `backend/app/agent/analysis_agent.py`)
- Analysis chain → Query learnings: records attempts (evidence: `backend/app/agent/analysis_agent.py`)
- Analysis chain → OpenAI model: requests model
- SQL generation → OpenAI model: requests model
- SQL execution agent → Query runner: delegates execution (evidence: `backend/app/agent/sql_executor.py`)
- Query runner → Project database: loads project (evidence: `backend/app/db/query_runner.py`)
- Query runner → DB connectors: selects connector (evidence: `backend/app/db/query_runner.py`)
- DB connectors → DuckDB connector: supports engine
- Project database → Supabase: stores project data