# explorerhq/sql-explorer architecture

> Architecture diagram of the GitHub repository explorerhq/sql-explorer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/explorerhq/sql-explorer
- Repository: https://github.com/explorerhq/sql-explorer

## Overview

1. **Repository shape**
   - This is a reusable Django application, packaged as `explorer`, plus a `test_project` that demonstrates embedding it in a real site.
   - The package is split into a core app and an optional enterprise-style extension under `explorer/ee`, with separate URLs and models for upload/database-connection features.

2. **Primary runtime boundary**
   - The main boundary is between the Django app and the SQL data sources it connects to.
   - SQL Explorer does not own the data; it sends SQL to configured databases, receives tabular results, and renders those results in the browser.

3. **Core request flow**
   - Incoming requests enter `explorer/urls.py`, then fan out into view modules under `explorer/views/`.
   - Those views coordinate forms, permissions, model persistence, query execution, and response rendering through templates in `explorer/templates/explorer/`.
   - The core user loop is: create/edit query → run query → inspect results → optionally save, favorite, export, email, or share.

4. **Domain and persistence**
   - The app persists operational metadata rather than analytic data: saved queries, query logs, favorites, snapshots, prompt logs, database connections, and table descriptions.
   - Migrations show the historical evolution of these models, including connection support, user favorites, LLM prompt logging, and upload-related metadata.

5. **Query execution and result handling**
   - Query-related behavior is concentrated in `views/query.py`, `views/export.py`, `views/download.py`, `views/email.py`, `views/stream.py`, and related helpers.
   - This layer is responsible for parameterized execution, result formatting, exporting, streaming large outputs, and auxiliary actions like email delivery.
   - `actions.py`, `exporters.py`, and `charts.py` support non-CRUD behaviors around the query result set.

6. **Schema introspection and UI assistance**
   - `schema.py` plus `views/schema.py` provide database/schema discovery so users can see tables, columns, and inferred structure.
   - The browser-side schema service and editor integrations in `src/js/schemaService.js`, `schema.js`, and `codemirror-config.js` feed autocomplete and query assistance.
   - This is a distinct read-only introspection path from actual query execution.

7. **AI assistant subsystem**
   - The `explorer/assistant/` package is its own feature slice with models, forms, views, URLs, and utilities.
   - It stores prompt history and table descriptions so the assistant can enrich prompts with relevant schema/context before calling an external LLM provider.
   - The README indicates OpenAI-compatible APIs, so the external dependency here is an LLM service, not just the database backend.

8. **Uploaded-data and enterprise connection handling**
   - `explorer/ee/db_connections/` handles user-uploaded or managed data connections, especially CSV, JSON, and SQLite.
   - Supporting modules for MIME detection, type inference, SQLite creation, and connection models show that uploads are converted into queryable databases rather than treated as raw files.
   - This subsystem is isolated behind its own URLs and forms, making it a clear optional boundary.

9. **Frontend architecture**
   - Frontend code lives under `explorer/src/js` and `explorer/src/scss`, with Vite integration via `vite.config.mjs` and the custom `templatetags/vite.py`.
   - The UI is modular: editor/query screens, favorites, pivot table, query list, schema helper, uploads, and assistant each have dedicated JS entry points.
   - Static assets are built separately from the Django backend, then consumed by templates.

10. **Background and operational concerns**
   - `tasks.py` and the feature list suggest scheduled/background work for snapshots and other deferred jobs.
   - `telemetry.py` centralizes usage/diagnostic reporting concerns, keeping them separate from query execution and UI rendering.
   - `permissions.py` and `views/auth.py` define access control boundaries around who can run, save, or manage queries and connections.

11. **Admin and maintenance surfaces**
   - `admin.py` and the many model templates for connections, queries, logs, and assistant records indicate a substantial Django admin/management surface.
   - This is important for architecture diagrams because operational users can manage configuration and metadata without using the main query UI.

12. **Packaging, deployment, and validation**
   - The repo is packaged for distribution (`setup.py`, `MANIFEST.in`, `requirements/`), containerized (`Dockerfile`, `docker-compose.yml`), and continuously tested/linted via GitHub Actions.
   - `docs/` and `test_project/` show that the project supports both embedded use in another Django site and a standalone demo/development deployment.

Main entry points: [`explorer/urls.py`](https://github.com/explorerhq/sql-explorer/blob/master/explorer/urls.py) (URLs), [`explorer/models.py`](https://github.com/explorerhq/sql-explorer/blob/master/explorer/models.py) (Explorer models), [`explorer/views/query.py`](https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/query.py) (Query UI), [`explorer/views/export.py`](https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/export.py) (Query ops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Django app"]
  node_urls["URLs<br/>django routing<br/>[urls.py]"]
  node_views_query["Query UI<br/>request handlers<br/>[query.py]"]
  node_views_ops["Query ops<br/>exports/email/stream<br/>[export.py]"]
  node_views_schema["Schema UI<br/>schema views<br/>[schema.py]"]
  node_views_list["Lists<br/>listing views<br/>[list.py]"]
  node_views_auth["Access control<br/>auth views<br/>[auth.py]"]
  node_models[("Explorer models<br/>domain models<br/>[models.py]")]
  node_forms["Forms<br/>[forms.py]"]
  node_schema["Schema engine<br/>introspection<br/>[schema.py]"]
  node_exporters["Exporters<br/>result formatting<br/>[exporters.py]"]
  node_actions["Actions<br/>[actions.py]"]
  node_permissions["Permissions<br/>policy<br/>[permissions.py]"]
  node_telemetry["Telemetry<br/>diagnostics<br/>[telemetry.py]"]
  node_tasks["Tasks<br/>background jobs<br/>[tasks.py]"]
end

subgraph group_assistant["Assistant"]
  node_assistant_models[("Assistant data<br/>assistant models<br/>[models.py]")]
  node_assistant_views["Assistant UI<br/>assistant views<br/>[views.py]"]
  node_assistant_urls["Assistant URLs<br/>assistant routing<br/>[urls.py]"]
end

subgraph group_enterprise["Enterprise upload/db connections"]
  node_ee_urls["EE URLs<br/>enterprise routing<br/>[urls.py]"]
  node_db_connections[("Connections<br/>managed uploads<br/>[models.py]")]
  node_db_connection_views["Connection UI<br/>enterprise views<br/>[views.py]"]
  node_db_connection_utils["Import utils<br/>file-to-db helpers<br/>[utils.py]"]
end

subgraph group_frontend["Frontend assets"]
  node_js_entry["JS entry<br/>frontend bootstrap<br/>[main.js]"]
  node_schema_service["Schema service<br/>frontend schema<br/>[schemaService.js]"]
  node_vite["Vite build<br/>asset pipeline<br/>[vite.config.mjs]"]
end

subgraph group_demo["Demo project"]
  node_test_project["Demo site<br/>django project<br/>[settings.py]"]
end

node_urls -->|"routes"| node_views_query
node_urls -->|"routes"| node_views_ops
node_urls -->|"routes"| node_views_schema
node_urls -->|"routes"| node_views_list
node_urls -->|"routes"| node_views_auth
node_views_query -->|"uses"| node_forms
node_views_query -->|"persists"| node_models
node_views_query -->|"delegates"| node_actions
node_views_ops -->|"formats"| node_exporters
node_views_ops -->|"records"| node_models
node_views_schema -->|"introspects"| node_schema
node_schema -->|"feeds"| node_views_schema
node_models -->|"gated by"| node_permissions
node_views_auth -->|"enforces"| node_permissions
node_telemetry -.->|"observes"| node_models
node_tasks -.->|"updates"| node_models
node_assistant_urls -->|"routes"| node_assistant_views
node_assistant_views -->|"reads/writes"| node_assistant_models
node_assistant_views -->|"enriches"| node_schema
node_ee_urls -->|"routes"| node_db_connection_views
node_db_connection_views -->|"persists"| node_db_connections
node_db_connection_utils -->|"creates"| node_db_connections
node_js_entry -->|"uses"| node_schema_service
node_js_entry -->|"built by"| node_vite
node_test_project -->|"embeds"| node_urls
node_test_project -.->|"optionally embeds"| node_ee_urls

click node_urls "https://github.com/explorerhq/sql-explorer/blob/master/explorer/urls.py"
click node_views_query "https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/query.py"
click node_views_ops "https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/export.py"
click node_views_schema "https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/schema.py"
click node_views_list "https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/list.py"
click node_views_auth "https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/auth.py"
click node_models "https://github.com/explorerhq/sql-explorer/blob/master/explorer/models.py"
click node_forms "https://github.com/explorerhq/sql-explorer/blob/master/explorer/forms.py"
click node_schema "https://github.com/explorerhq/sql-explorer/blob/master/explorer/schema.py"
click node_exporters "https://github.com/explorerhq/sql-explorer/blob/master/explorer/exporters.py"
click node_actions "https://github.com/explorerhq/sql-explorer/blob/master/explorer/actions.py"
click node_permissions "https://github.com/explorerhq/sql-explorer/blob/master/explorer/permissions.py"
click node_telemetry "https://github.com/explorerhq/sql-explorer/blob/master/explorer/telemetry.py"
click node_tasks "https://github.com/explorerhq/sql-explorer/blob/master/explorer/tasks.py"
click node_assistant_models "https://github.com/explorerhq/sql-explorer/blob/master/explorer/assistant/models.py"
click node_assistant_views "https://github.com/explorerhq/sql-explorer/blob/master/explorer/assistant/views.py"
click node_assistant_urls "https://github.com/explorerhq/sql-explorer/blob/master/explorer/assistant/urls.py"
click node_ee_urls "https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/urls.py"
click node_db_connections "https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/db_connections/models.py"
click node_db_connection_views "https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/db_connections/views.py"
click node_db_connection_utils "https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/db_connections/utils.py"
click node_js_entry "https://github.com/explorerhq/sql-explorer/blob/master/explorer/src/js/main.js"
click node_schema_service "https://github.com/explorerhq/sql-explorer/blob/master/explorer/src/js/schemaService.js"
click node_vite "https://github.com/explorerhq/sql-explorer/blob/master/vite.config.mjs"
click node_test_project "https://github.com/explorerhq/sql-explorer/blob/master/test_project/settings.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_urls,node_views_query,node_views_ops,node_views_schema,node_views_list,node_views_auth,node_models,node_forms,node_schema,node_exporters,node_actions,node_permissions,node_telemetry,node_tasks toneBlue
class node_assistant_models,node_assistant_views,node_assistant_urls toneAmber
class node_ee_urls,node_db_connections,node_db_connection_views,node_db_connection_utils toneMint
class node_js_entry,node_schema_service,node_vite toneRose
class node_test_project toneIndigo
```

## Components

### Core Django app

Main reusable explorer package: query UI, execution, persistence, schema discovery, and admin surfaces.

- [URLs](https://github.com/explorerhq/sql-explorer/blob/master/explorer/urls.py): django routing · Top-level request routing into the app's feature surfaces. · `explorer/urls.py`
- [Query UI](https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/query.py): request handlers · Create, edit, run, and inspect SQL queries; main user loop. · `explorer/views/query.py`
- [Query ops](https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/export.py): exports/email/stream · Auxiliary result-set actions such as export, download, email, and streaming. · `explorer/views/export.py`
- [Schema UI](https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/schema.py): schema views · Read-only database discovery and schema presentation. · `explorer/views/schema.py`
- [Lists](https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/list.py): listing views · Query lists, logs, and other browse/manage screens. · `explorer/views/list.py`
- [Access control](https://github.com/explorerhq/sql-explorer/blob/master/explorer/views/auth.py): auth views · Authentication and permission-sensitive boundaries for the app. · `explorer/views/auth.py`
- [Explorer models](https://github.com/explorerhq/sql-explorer/blob/master/explorer/models.py): domain models · Saved queries, logs, favorites, snapshots, prompt logs, and other operational metadata. · `explorer/models.py`
- [Forms](https://github.com/explorerhq/sql-explorer/blob/master/explorer/forms.py): validation forms · User input handling for queries, filters, and metadata actions. · `explorer/forms.py`
- [Schema engine](https://github.com/explorerhq/sql-explorer/blob/master/explorer/schema.py): introspection · Database inspection and schema metadata assembly used by the UI and assistant. · `explorer/schema.py`
- [Exporters](https://github.com/explorerhq/sql-explorer/blob/master/explorer/exporters.py): result formatting · Transforms query results into downloadable formats and tabular representations. · `explorer/exporters.py`
- [Actions](https://github.com/explorerhq/sql-explorer/blob/master/explorer/actions.py): query actions · Non-CRUD behavior around executing, favoriting, and manipulating query results. · `explorer/actions.py`
- [Permissions](https://github.com/explorerhq/sql-explorer/blob/master/explorer/permissions.py): policy · Authorization rules for running, saving, and managing explorer resources. · `explorer/permissions.py`
- [Telemetry](https://github.com/explorerhq/sql-explorer/blob/master/explorer/telemetry.py): diagnostics · Usage and diagnostic reporting separated from request handling. · `explorer/telemetry.py`
- [Tasks](https://github.com/explorerhq/sql-explorer/blob/master/explorer/tasks.py): background jobs · Deferred or scheduled work such as snapshots and other operational jobs. · `explorer/tasks.py`

### Assistant

LLM-assisted prompt enrichment and table-description workflow.

- [Assistant data](https://github.com/explorerhq/sql-explorer/blob/master/explorer/assistant/models.py): assistant models · Prompt history and table-description storage for contextual LLM assistance. · `explorer/assistant/models.py`
- [Assistant UI](https://github.com/explorerhq/sql-explorer/blob/master/explorer/assistant/views.py): assistant views · Assistant forms, views, and utilities that prepare context for an external LLM. · `explorer/assistant/views.py`
- [Assistant URLs](https://github.com/explorerhq/sql-explorer/blob/master/explorer/assistant/urls.py): assistant routing · Dedicated assistant feature routes isolated from the core explorer URLs. · `explorer/assistant/urls.py`

### Enterprise upload/db connections

Optional extension for managed or uploaded data sources.

- [EE URLs](https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/urls.py): enterprise routing · Optional URLs for the upload and managed-connection extension. · `explorer/ee/urls.py`
- [Connections](https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/db_connections/models.py): managed uploads · Upload-backed and managed database connections for CSV, JSON, and SQLite sources. · `explorer/ee/db_connections/models.py`
- [Connection UI](https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/db_connections/views.py): enterprise views · Forms and views for creating, inspecting, and deleting managed connections. · `explorer/ee/db_connections/views.py`
- [Import utils](https://github.com/explorerhq/sql-explorer/blob/master/explorer/ee/db_connections/utils.py): file-to-db helpers · MIME detection, type inference, and SQLite creation for uploaded data. · `explorer/ee/db_connections/utils.py`

### Frontend assets

Bundled JavaScript, styles, and Vite integration for the browser UI.

- [JS entry](https://github.com/explorerhq/sql-explorer/blob/master/explorer/src/js/main.js): frontend bootstrap · Main browser entry points that wire the Django templates to interactive UI features. · `explorer/src/js/main.js`
- [Schema service](https://github.com/explorerhq/sql-explorer/blob/master/explorer/src/js/schemaService.js): frontend schema · Client-side schema discovery and autocomplete support. · `explorer/src/js/schemaService.js`
- [Vite build](https://github.com/explorerhq/sql-explorer/blob/master/vite.config.mjs): asset pipeline · Frontend build integration for bundling JS and CSS into templates. · `vite.config.mjs`

### Demo project

Standalone Django project used to embed and exercise the app.

- [Demo site](https://github.com/explorerhq/sql-explorer/blob/master/test_project/settings.py): django project · Standalone Django project showing how to embed the explorer app. · `test_project/settings.py`

## Connections

- URLs → Query UI: routes · Core routes dispatch query screens and execution flows.
- URLs → Query ops: routes · Routes auxiliary export, download, email, and streaming actions.
- URLs → Schema UI: routes · Routes schema discovery and schema display pages.
- URLs → Lists: routes · Routes list and management views.
- URLs → Access control: routes · Routes authentication and access-control views.
- Query UI → Forms: uses · Query screens rely on forms for validation and parameters.
- Query UI → Explorer models: persists · Reads and writes saved queries, logs, favorites, and snapshots.
- Query UI → Actions: delegates · Execution and result-set behaviors are factored into query actions.
- Query ops → Exporters: formats · Export and download responses are rendered through exporters.
- Query ops → Explorer models: records · Operational actions can store logs and related metadata.
- Schema UI → Schema engine: introspects · Schema pages build on database discovery helpers.
- Schema engine → Schema UI: feeds · Schema metadata powers the read-only schema views.
- Explorer models → Permissions: gated by · Model-level operations are constrained by permissions.
- Access control → Permissions: enforces · Authentication views apply access policy boundaries.
- Telemetry → Explorer models: observes · Telemetry records usage and diagnostic signals tied to app activity.
- Tasks → Explorer models: updates · Background work operates on persisted operational metadata.
- Assistant URLs → Assistant UI: routes · Assistant-specific routing enters the assistant feature slice.
- Assistant UI → Assistant data: reads/writes · Assistant requests store prompt history and table descriptions.
- Assistant UI → Schema engine: enriches · Schema metadata is used to build contextual prompts.
- EE URLs → Connection UI: routes · Enterprise routes separate upload and managed connection screens.
- Connection UI → Connections: persists · Connection forms and views store managed data-source metadata.
- Import utils → Connections: creates · Uploaded files are converted into queryable database-backed connections.
- JS entry → Schema service: uses · Browser entry points consume the schema service for autocomplete and assistance.
- JS entry → Vite build: built by · Frontend bundles are produced through the Vite pipeline.
- Demo site → URLs: embeds · The demo site mounts the reusable explorer app.
- Demo site → EE URLs: optionally embeds · The demo site can also exercise the enterprise extension.
