How getredash/redash works
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: handlers HTTP handlers · tasks Background tasks · pages Feature pages · src viz-lib
Components 22
Python backend
Web app, API, domain models, query runners, auth, and background jobs.
- Entry points · Main Python launch points for web and worker processes.
redash/app.py - HTTP handlers · Request handlers for queries, dashboards, alerts, users, groups, settings, embeds, admin, and static pages.
redash/handlers - Models · Database-backed domain objects and relational persistence layer.
redash/models - Migrations · Alembic migrations that evolve the relational schema.
migrations - Query runners · Extensible execution layer for databases and external data systems.
redash/query_runner - Result cache · Shared query-result persistence and reuse logic.
redash/query_runner/query_results.py - Background tasks · Scheduled and asynchronous work for refreshes, alerts, maintenance, and cleanup.
redash/tasks - Authentication · Login backends and organization resolution for multi-org access control.
redash/authentication - Permissions · Authorization rules shared across server resources.
redash/permissions.py - Serializers · API response formatting and serialization helpers.
redash/serializers - Destinations · Alert delivery integrations such as email, Slack, webhooks, PagerDuty, and chat systems.
redash/destinations - Worker runtime · Separate worker process that executes queued background jobs.
redash/worker.py
React frontend
Browser application for queries, dashboards, alerts, users, and settings.
- SPA shell · React application bootstrap and server-delivered shell pages.
client/app/index.js - Navigation · Client-side routing, session restoration, and access-bound route wrappers.
client/app/components/ApplicationArea - Feature pages · Primary application screens for queries, dashboards, alerts, users, groups, sources, destinations, settings, and admin.
client/app/pages - Client services · Frontend services for API calls, session state, routing helpers, and domain actions.
client/app/services - UI components · Reusable React building blocks used across the app.
client/app/components
Shared viz-lib
Reusable visualization editors, renderers, and shared chart utilities.
- viz-lib · Standalone visualization library with editors, renderers, and shared utilities.
viz-lib/src - Charting views · Shared implementations for chart, table, map, sankey, cohort, funnel, counter, pivot, choropleth, word cloud, and related views.
viz-lib/src/visualizations - Shared viz utils · Common column formatting, editor helpers, and visualization primitives.
viz-lib/src/visualizations/shared
Ops & build
Containerization, CI, release, and test infrastructure.
- Deployment · Docker and compose definitions for web, worker, and CI-like environments.
compose.yaml - CI/CD · GitHub Actions, Cypress, scripts, and release tooling.
.github/workflows/ci.yml
Connections 25
- 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.