# getredash/redash architecture

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

- Interactive diagram: https://gitdiagram.com/getredash/redash
- Repository: https://github.com/getredash/redash

## Overview

1. **What this repository is**
   - This is Redash, a self-hosted analytics platform.
   - The architecture is split into a Python backend, a browser-based React UI, and a shared visualization library used by the UI.

2. **Top-level runtime separation**
   - The backend runs as a web application plus separate background workers.
   - The web app serves HTML/templates, exposes the REST API, and handles auth/session flows.
   - Background jobs execute query refreshes, alert checks, scheduled tasks, and maintenance work.

3. **Backend entry points and deployment shape**
   - `redash/app.py`, `redash/wsgi.py`, and `manage.py` are the main Python entry points.
   - `redash/worker.py` and `redash/tasks/*` define async processing.
   - Docker and compose files in the repo indicate containerized deployment, with distinct web and worker services.

4. **Core server-side domain layer**
   - `redash/models` contains the data model and persistence layer, built around a relational database with Alembic migrations in `migrations/`.
   - `redash/handlers` is the HTTP/API layer for major resources: queries, dashboards, alerts, users, groups, data sources, destinations, settings, embeds, and admin functions.
   - `redash/serializers` shapes responses for API consumers, and `redash/permissions.py` enforces access control across resources.

5. **Query execution pipeline**
   - Queries originate in the UI, are sent to handler endpoints, and are executed by the backend through `redash/query_runner/*`.
   - Each data source type has a dedicated runner implementation; this is the main extensibility boundary for supporting many databases and APIs.
   - Results are stored and reused via `redash/query_runner/query_results.py`, while execution scheduling and refresh logic live under `redash/tasks/queries/`.

6. **Async processing and scheduling**
   - Scheduled query refreshes, alert evaluation, and cleanup jobs are handled asynchronously rather than in the request thread.
   - `worker.conf` and the task modules imply a queue-based worker architecture, with the web app enqueuing work and workers performing the long-running operations.
   - This separation is important: the UI/API remains responsive while data retrieval and alerting happen in the background.

7. **Dashboards, widgets, and visualizations**
   - Dashboards are composed of widgets backed by query results.
   - The backend exposes dashboard/query/visualization APIs; the frontend renders and edits them in the browser.
   - The actual charting and table behavior is shared in `viz-lib`, which provides visualization editors and renderers for chart, table, map, sankey, cohort, funnel, counter, pivot, choropleth, word cloud, and related views.

8. **Frontend application structure**
   - `client/app` is a React application written in a mix of JavaScript, TypeScript, JSX, LESS, and CSS.
   - It is organized by feature areas: queries, dashboards, alerts, users, groups, data sources, destinations, settings, admin, and home.
   - `client/app/services` encapsulates API calls and client-side domain logic, while `client/app/components` provides reusable UI building blocks and dialogs.

9. **Client-side navigation and session handling**
   - Routing and session restoration are handled in `client/app/components/ApplicationArea` and `client/app/services/routes.ts`.
   - There are explicit boundaries for user-session routes and API-key session routes, reflecting different access patterns in the UI.
   - Static templates and entry HTML in `redash/templates` and `client/app/index.html` bridge server-rendered shell pages with the SPA.

10. **Shared visualization package**
   - `viz-lib` is a separate package inside the repo, focused on reusable visualization primitives and editors.
   - It contains rendering logic, settings panels, and shared column/format utilities used by the Redash frontend.
   - This package materially affects architecture because it isolates charting behavior from the broader app and is built with its own TypeScript/webpack setup.

11. **Authentication and organization boundaries**
   - Authentication supports multiple backends: Google OAuth, SAML, LDAP, JWT, remote user auth, and password/login flows.
   - Organization resolution and multi-organization behavior are explicit concerns in `redash/authentication/org_resolving.py` and related settings modules.
   - This means identity and tenancy are first-class boundaries in the server design, not just a UI concern.

12. **Alerts and notification delivery**
   - Alerts are created and managed through backend handlers and scheduled tasks.
   - Deliveries go through `redash/destinations/*`, which includes email, Slack, webhooks, PagerDuty, Teams, Discord, Mattermost, and others.
   - The alert flow is: query result changes trigger evaluation, which can enqueue notification delivery to external services.

13. **External-system integrations**
   - The main external boundary is the data-source connection layer: Redash connects outward to databases, warehouses, metrics systems, search engines, and APIs.
   - The second major external boundary is notification/destination services for alerts and collaboration.
   - Browser clients interact only with Redash’s API; Redash then mediates all access to external data systems.

14. **Quality, build, and operational tooling**
   - Python tests live under `tests/`, frontend tests and Cypress end-to-end coverage live under `client/cypress/`, and `viz-lib` has its own unit tests.
   - CI/CD is defined in GitHub Actions and Docker/compose files, with migration tooling, release scripts, and version management under `bin/`, `scripts/`, and `.ci/`.
   - For an architecture diagram, these are supporting concerns, but they reinforce the repo’s split between backend services, frontend app, worker processes, and shared visualization code.

Main entry points: [`redash/handlers`](https://github.com/getredash/redash/tree/master/redash/handlers) (HTTP handlers), [`redash/tasks`](https://github.com/getredash/redash/tree/master/redash/tasks) (Background tasks), [`client/app/pages`](https://github.com/getredash/redash/tree/master/client/app/pages) (Feature pages), [`viz-lib/src`](https://github.com/getredash/redash/tree/master/viz-lib/src) (viz-lib)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python backend"]
  node_entrypoints["Entry points<br/>Python app/startup<br/>[app.py]"]
  node_http_handlers["HTTP handlers<br/>API/web layer"]
  node_domain_models[("Models<br/>ORM/persistence")]
  node_migrations["Migrations<br/>schema versioning"]
  node_query_runners["Query runners<br/>connector plugins"]
  node_query_results["Result cache<br/>query result store<br/>[query_results.py]"]
  node_tasks["Background tasks<br/>async jobs"]
  node_auth["Authentication<br/>identity/tenancy"]
  node_permissions["Permissions<br/>access control<br/>[permissions.py]"]
  node_serializers["Serializers<br/>response shaping"]
  node_destinations["Destinations<br/>notification adapters"]
  node_worker["Worker runtime<br/>queue worker<br/>[worker.py]"]
end

subgraph group_frontend["React frontend"]
  node_spa_shell["SPA shell<br/>browser entry<br/>[index.js]"]
  node_navigation["Navigation<br/>routing/session"]
  node_feature_pages["Feature pages<br/>UI features"]
  node_client_services["Client services<br/>API client logic"]
  node_ui_components["UI components<br/>shared widgets"]
end

subgraph group_vizlib["Shared viz-lib"]
  node_viz_package["viz-lib<br/>shared visualization package"]
  node_charting["Charting views<br/>visualization types"]
  node_viz_shared["Shared viz utils<br/>rendering utilities"]
end

subgraph group_ops["Ops & build"]
  node_deployment["Deployment<br/>containers/compose<br/>[compose.yaml]"]
  node_ci["CI/CD<br/>automation<br/>[ci.yml]"]
end

node_entrypoints -->|"serves"| node_http_handlers
node_entrypoints -->|"starts"| node_worker
node_http_handlers -->|"reads/writes"| node_domain_models
node_http_handlers -->|"checks"| node_permissions
node_http_handlers -->|"formats"| node_serializers
node_http_handlers -->|"authenticates"| node_auth
node_http_handlers -->|"dispatches"| node_query_runners
node_query_runners -->|"stores"| node_query_results
node_query_runners -->|"enqueues"| node_tasks
node_tasks -->|"consumed by"| node_worker
node_tasks -->|"notifies"| node_destinations
node_tasks -->|"refreshes"| node_query_results
node_domain_models -->|"evolves via"| node_migrations
node_spa_shell -->|"boots"| node_navigation
node_navigation -->|"routes to"| node_feature_pages
node_feature_pages -->|"uses"| node_client_services
node_feature_pages -->|"composes"| node_ui_components
node_feature_pages -->|"renders with"| node_viz_package
node_viz_package -->|"contains"| node_charting
node_viz_package -->|"shares"| node_viz_shared
node_client_services -->|"calls"| node_http_handlers
node_deployment -.->|"runs"| node_entrypoints
node_deployment -.->|"runs"| node_worker
node_ci -.->|"builds/tests"| node_deployment
node_ci -.->|"validates"| node_viz_package

click node_entrypoints "https://github.com/getredash/redash/blob/master/redash/app.py"
click node_http_handlers "https://github.com/getredash/redash/tree/master/redash/handlers"
click node_domain_models "https://github.com/getredash/redash/tree/master/redash/models"
click node_migrations "https://github.com/getredash/redash/tree/master/migrations"
click node_query_runners "https://github.com/getredash/redash/tree/master/redash/query_runner"
click node_query_results "https://github.com/getredash/redash/blob/master/redash/query_runner/query_results.py"
click node_tasks "https://github.com/getredash/redash/tree/master/redash/tasks"
click node_auth "https://github.com/getredash/redash/tree/master/redash/authentication"
click node_permissions "https://github.com/getredash/redash/blob/master/redash/permissions.py"
click node_serializers "https://github.com/getredash/redash/tree/master/redash/serializers"
click node_destinations "https://github.com/getredash/redash/tree/master/redash/destinations"
click node_worker "https://github.com/getredash/redash/blob/master/redash/worker.py"
click node_spa_shell "https://github.com/getredash/redash/blob/master/client/app/index.js"
click node_navigation "https://github.com/getredash/redash/tree/master/client/app/components/ApplicationArea"
click node_feature_pages "https://github.com/getredash/redash/tree/master/client/app/pages"
click node_client_services "https://github.com/getredash/redash/tree/master/client/app/services"
click node_ui_components "https://github.com/getredash/redash/tree/master/client/app/components"
click node_viz_package "https://github.com/getredash/redash/tree/master/viz-lib/src"
click node_charting "https://github.com/getredash/redash/tree/master/viz-lib/src/visualizations"
click node_viz_shared "https://github.com/getredash/redash/tree/master/viz-lib/src/visualizations/shared"
click node_deployment "https://github.com/getredash/redash/blob/master/compose.yaml"
click node_ci "https://github.com/getredash/redash/blob/master/.github/workflows/ci.yml"

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_entrypoints,node_http_handlers,node_domain_models,node_migrations,node_query_runners,node_query_results,node_tasks,node_auth,node_permissions,node_serializers,node_destinations,node_worker toneBlue
class node_spa_shell,node_navigation,node_feature_pages,node_client_services,node_ui_components toneAmber
class node_viz_package,node_charting,node_viz_shared toneMint
class node_deployment,node_ci toneRose
```

## Components

### Python backend

Web app, API, domain models, query runners, auth, and background jobs.

- [Entry points](https://github.com/getredash/redash/blob/master/redash/app.py): Python app/startup · Main Python launch points for web and worker processes. · `redash/app.py`
- [HTTP handlers](https://github.com/getredash/redash/tree/master/redash/handlers): API/web layer · Request handlers for queries, dashboards, alerts, users, groups, settings, embeds, admin, and static pages. · `redash/handlers`
- [Models](https://github.com/getredash/redash/tree/master/redash/models): ORM/persistence · Database-backed domain objects and relational persistence layer. · `redash/models`
- [Migrations](https://github.com/getredash/redash/tree/master/migrations): schema versioning · Alembic migrations that evolve the relational schema. · `migrations`
- [Query runners](https://github.com/getredash/redash/tree/master/redash/query_runner): connector plugins · Extensible execution layer for databases and external data systems. · `redash/query_runner`
- [Result cache](https://github.com/getredash/redash/blob/master/redash/query_runner/query_results.py): query result store · Shared query-result persistence and reuse logic. · `redash/query_runner/query_results.py`
- [Background tasks](https://github.com/getredash/redash/tree/master/redash/tasks): async jobs · Scheduled and asynchronous work for refreshes, alerts, maintenance, and cleanup. · `redash/tasks`
- [Authentication](https://github.com/getredash/redash/tree/master/redash/authentication): identity/tenancy · Login backends and organization resolution for multi-org access control. · `redash/authentication`
- [Permissions](https://github.com/getredash/redash/blob/master/redash/permissions.py): access control · Authorization rules shared across server resources. · `redash/permissions.py`
- [Serializers](https://github.com/getredash/redash/tree/master/redash/serializers): response shaping · API response formatting and serialization helpers. · `redash/serializers`
- [Destinations](https://github.com/getredash/redash/tree/master/redash/destinations): notification adapters · Alert delivery integrations such as email, Slack, webhooks, PagerDuty, and chat systems. · `redash/destinations`
- [Worker runtime](https://github.com/getredash/redash/blob/master/redash/worker.py): queue worker · Separate worker process that executes queued background jobs. · `redash/worker.py`

### React frontend

Browser application for queries, dashboards, alerts, users, and settings.

- [SPA shell](https://github.com/getredash/redash/blob/master/client/app/index.js): browser entry · React application bootstrap and server-delivered shell pages. · `client/app/index.js`
- [Navigation](https://github.com/getredash/redash/tree/master/client/app/components/ApplicationArea): routing/session · Client-side routing, session restoration, and access-bound route wrappers. · `client/app/components/ApplicationArea`
- [Feature pages](https://github.com/getredash/redash/tree/master/client/app/pages): UI features · Primary application screens for queries, dashboards, alerts, users, groups, sources, destinations, settings, and admin. · `client/app/pages`
- [Client services](https://github.com/getredash/redash/tree/master/client/app/services): API client logic · Frontend services for API calls, session state, routing helpers, and domain actions. · `client/app/services`
- [UI components](https://github.com/getredash/redash/tree/master/client/app/components): shared widgets · Reusable React building blocks used across the app. · `client/app/components`

### Shared viz-lib

Reusable visualization editors, renderers, and shared chart utilities.

- [viz-lib](https://github.com/getredash/redash/tree/master/viz-lib/src): shared visualization package · Standalone visualization library with editors, renderers, and shared utilities. · `viz-lib/src`
- [Charting views](https://github.com/getredash/redash/tree/master/viz-lib/src/visualizations): visualization types · Shared implementations for chart, table, map, sankey, cohort, funnel, counter, pivot, choropleth, word cloud, and related views. · `viz-lib/src/visualizations`
- [Shared viz utils](https://github.com/getredash/redash/tree/master/viz-lib/src/visualizations/shared): rendering utilities · Common column formatting, editor helpers, and visualization primitives. · `viz-lib/src/visualizations/shared`

### Ops & build

Containerization, CI, release, and test infrastructure.

- [Deployment](https://github.com/getredash/redash/blob/master/compose.yaml): containers/compose · Docker and compose definitions for web, worker, and CI-like environments. · `compose.yaml`
- [CI/CD](https://github.com/getredash/redash/blob/master/.github/workflows/ci.yml): automation · GitHub Actions, Cypress, scripts, and release tooling. · `.github/workflows/ci.yml`

## Connections

- Entry points → HTTP handlers: serves · Web entry points dispatch requests into the HTTP layer.
- Entry points → Worker runtime: starts · Separate process entry for asynchronous workers.
- HTTP handlers → Models: reads/writes · Handlers persist and query application state through models.
- HTTP handlers → Permissions: checks · Resource access is gated by shared authorization rules.
- HTTP handlers → Serializers: formats · Handlers shape API responses through serializers.
- HTTP handlers → Authentication: authenticates · Login, session, and organization flows feed request handling.
- HTTP handlers → Query runners: dispatches · Query-related endpoints hand execution off to runner plugins.
- Query runners → Result cache: stores · Executed results are cached and reused.
- Query runners → Background tasks: enqueues · Long-running execution and refresh work is scheduled asynchronously.
- Background tasks → Worker runtime: consumed by · Queued jobs are performed by the worker runtime.
- Background tasks → Destinations: notifies · Alert tasks deliver notifications through destination adapters.
- Background tasks → Result cache: refreshes · Background jobs update stored query results.
- Models → Migrations: evolves via · Schema and model changes are managed through migrations.
- SPA shell → Navigation: boots · The SPA shell initializes routing and session restoration.
- Navigation → Feature pages: routes to · Navigation resolves into feature-specific screens.
- Feature pages → Client services: uses · Pages call service modules for API and state operations.
- Feature pages → UI components: composes · Pages assemble reusable UI components.
- Feature pages → viz-lib: renders with · Query, dashboard, and visualization screens use the shared visualization package.
- viz-lib → Charting views: contains · The visualization package organizes concrete visualization types.
- viz-lib → Shared viz utils: shares · Rendering and editor behavior depend on common utilities and primitives.
- Client services → HTTP handlers: calls · Frontend services communicate with the backend API.
- Deployment → Entry points: runs · Container deployment launches the web application entry points.
- Deployment → Worker runtime: runs · Deployment also provisions the background worker service.
- CI/CD → Deployment: builds/tests · Automation covers container builds, tests, and release flows.
- CI/CD → viz-lib: validates · Frontend and visualization package tests are part of CI coverage.
