ADR 033: Use Grafana as Second Dashboard Tool
Date: 2026-03-10
Status: Reviewed
Decision Makers: CIVITAS/CORE Architecture Board
Context
ADR 008 selects Superset as the primary dashboard tool for CIVITAS/CORE, while ADR 011 selects Grafana as the observability dashboard for logs, metrics, and operational monitoring.
At the same time, some cities already use Grafana to build and publish dashboards. Reusing this tooling can reduce migration effort and speed up adoption for use cases where dashboards are based only on open data and do not require user-specific access control.
The architectural question is therefore not whether Grafana replaces Superset, but whether it should be supported as a secondary dashboard option for clearly scoped scenarios.
The relevant constraints are:
- Superset remains the primary tool for public and stakeholder-facing dashboards in CIVITAS/CORE.
- Grafana is already established in the platform for observability use cases.
- Some cities have existing Grafana knowledge, dashboards, and operating experience.
- Grafana is only suitable as a secondary dashboarding option where no fine-grained authorization is required on the dashboard itself.
Checked Architecture Principles
- [partial] Model-centric data flow
- [partial] Distributed architecture with unified user experience
- [full] Modular design
- [full] Integration capability through defined interfaces
- [full] Open source as the default
- [full] Cloud-native architecture
- [full] Prefer standard solutions over custom development
- [full] Self-contained deployment
- [partial] Technological consistency to ensure maintainability
- [none] Multi-tenancy
- [partial] Security by design
Comments on partial ratings:
- Model-centric data flow: Grafana dashboards can be provisioned as code, but they are still Grafana-specific artifacts and not inherently model-driven from CIVITAS/CORE domain models.
- Distributed architecture with unified user experience: Supporting a second dashboard tool helps local adoption, but introduces another user experience pattern next to Superset.
- Technological consistency to ensure maintainability: The decision is pragmatic for compatibility reasons, but every additional supported tool increases governance and support effort.
- Security by design: The scope is intentionally limited to open/public data dashboards because no dashboard-level authorization is planned in this usage model.
Decision
Grafana is supported as a secondary dashboard tool for CIVITAS/CORE, but only for dashboards based on open or public data.
This means:
- Superset remains the default and preferred dashboard tool for platform dashboards.
- Grafana may be used where cities already operate it successfully and where dashboards do not require protected access.
- Grafana support does not imply that all dashboarding use cases must be implemented twice.
- Protected stakeholder dashboards and authorization-sensitive use cases are out of scope for this decision.
Consequences
- Existing Grafana know-how in cities can be reused instead of forcing an immediate migration to Superset for all cases.
- CIVITAS/CORE must clearly document when to use Superset and when Grafana is acceptable.
- Governance is required to avoid tool sprawl and unclear ownership between observability dashboards and public data dashboards.
- Public Grafana dashboards must be separated from internal monitoring use cases to avoid accidental coupling between operational and public-facing deployments.
- Because authorization is not part of this scope, Grafana must not become the default for protected reporting scenarios.
Alternatives
- Use only Superset: Rejected because it would ignore existing Grafana usage in some cities and increase migration friction for simple public dashboard use cases.
- Replace Superset with Grafana: Rejected because ADR 008 already establishes Superset as the primary dashboard tool and Grafana is weaker for broader business and public dashboard scenarios.
- Support dashboards without any governance: Rejected because unrestricted tool choice would increase maintenance effort and reduce consistency across the platform.