Architecture
The whole system on one page. What runs, how a question becomes a checked answer, and the design decisions that shape the code.
OpenDash is two application images and one stateful dependency. Your warehouse holds the analytical data; OpenDash keeps only what it needs to run (conversations, definitions, results and jobs) in PostgreSQL.
Your infrastructure
web and worker, around one PostgreSQL. Your warehouse keeps the analytical data.Ideas that shape the code
- Numbers are references. The agent cites cells of recorded query runs, and a deterministic answer gate resolves and recomputes every claim. No model decides whether a figure is right.
- A governed path first. A verified query, then a metric query, then SQL over datasets, and only then raw SQL, which is labelled and always cross-checked. Datasets and metrics compile to SQL through OpenDash's own compiler, which only joins many-to-one, so a fan-out can't inflate a number.
- Context is versioned. Glossary terms, guides, verified queries and skills have immutable versions. Anything learned from users reaches shared scope only through a proposal that is checked, tested and reviewed.
- Durability lives in the data model. The transcript in Postgres is canonical. The job queue is the only liveness authority, each attempt is fenced by its number, tool calls are recorded, and side effects go through an idempotent outbox. Long waits are rows, not sleeping jobs.
- Postgres does everything stateful. Data, search (full text, trigram and vectors), jobs and change notification. There is no other store to run.
- Tenancy by construction. Every tenant table is keyed by
(org_id, id)with row-level security, and is reached only throughwithTenant, which sets the tenant for one transaction. The application role can't bypass it. - Only workers reach customer databases, through vetted addresses, as read-only sessions with server-side time limits.
- One engine, many surfaces. The web app, Slack, routines and the API run the same agent loop.
How a question is answered
The web app records it
web saves the message and the run, and puts the run on the queue.
A worker runs the analyst
A worker claims the run, rebuilds the conversation from Postgres, and runs the agent loop and its tools: search over your knowledge, metric queries and SQL through the query gateway.
The answer gate checks it
Every number in the draft answer must reference a cell of a recorded query result. The gate resolves and recomputes each one. An answer that can't be checked is sent back, and ships marked as unverified if it still fails.
The browser sees it live
Events are written to Postgres, announced with NOTIFY, and streamed to the browser over server-sent events.
Dashboards are code the analyst writes against a definition of named queries and filters. The code is drawn in a sandboxed frame on an origin of its own, so it never runs where an OpenDash session does. The frame asks for a query by its id; the server checks it, runs it as the viewer under row-level security, and caches the result by the complete bound query. Routines are found by a dispatcher when due, run their action, and send through the outbox once per person and channel.
Repository layout
apps/web Next.js UI, oRPC API, SSE, Better Auth, webhooks
apps/worker agent runs, connection checks, syncs, routines, delivery
packages/db Drizzle schema, RLS policies, partitions
packages/auth Better Auth setup, organizations, API keys, tenant resolution
packages/core tenancy, context, semantic compiler, query gateway, routines, learning, answer gate
packages/agent the agent adapter, profiles, tools, prompts
packages/api the typed API: contracts, the oRPC router and handlers, the client
packages/apps the sandboxed frame runtime dashboards are drawn in, its bridge and checks
packages/charts chart drawing for the page, PDFs and Slack images
packages/connectors PostgreSQL, MySQL and ClickHouse drivers, with per-dialect safety
packages/slack the Slack bot and replies
packages/email transactional and routine email templates
packages/markdown an answer's markdown, for the page and the PDF
packages/pdf answer PDFs
packages/ui the design system and its tokens
packages/tokens the design tokens as values, for email and server-drawn charts
packages/evals DashBench: generators, questions, graders
infra/ docker compose files, Caddy, the self-host smoke test
ee/ enterprise features (OCVSAL)Stack
| Layer | Choice |
|---|---|
| Runtime | Node 24 · pnpm and Turborepo · Biome · Vitest |
| Web | Next.js 16 · React 19 · Tailwind 4 · HeroUI · oRPC |
| Auth | Better Auth (organizations, API keys) |
| Agent | AI SDK, with provider packages for Anthropic, OpenAI, Google, Bedrock, Vertex, OpenRouter and the Vercel AI Gateway |
| Documents | Apache ECharts · react-pdf |
| Data | PostgreSQL · Drizzle · pgvector · pg-boss |
| Integrations | Slack · Resend or SMTP for email · MCP servers for connected services |