3DL: DUFT Dashboard Design Language

3DL: DUFT Dashboard Design Language#

DUFT Dashboard Definition Language (3DL) provides a declarative, human-readable approach to defining dashboards, data sources, and visualisations. Unlike traditional reporting systems that require hardcoded UI updates, 3DL enables dashboards to be modified dynamically—without altering frontend or backend code.

3DL is structured like XML, but under the hood, it is JSX, ensuring seamless integration with React. This design choice makes dashboards modular, adaptable, and easy to extend.

Key Engineering Decisions

Several key engineering decisions shaped the design and implementation of 3DL, balancing usability, flexibility, and maintainability:

  • Declarative Structure – JSON is common for configurations but lacks readability for large dashboards. 3DL’s XML-like syntax provides a structured, intuitive format that makes dashboards easier to define and modify. A WYSIWYG editor is planned to further simplify dashboard creation.

  • Seamless React Integration – Because DUFT UI is built on React, 3DL components map directly to React components. This avoids unnecessary translation layers, ensuring efficient rendering and state management.

  • Support for Non-Visual Elements – Dashboards aren’t just for visuals—they can include text, documentation, and indicator definitions. 3DL supports Markdown and HTML snippets, allowing for flexible content integration.

  • Reusability of Data Queries – To avoid redundancy, dashboards reference named queries stored in DUFT Config, ensuring datasets can be reused across multiple dashboards.

Declarative UI Composition#

3DL enables hierarchical and structured dashboard composition using React-like components such as <TabSet>, <Dashboard>, <Grid>, <Row>, <Tile>, and <BarChart>. Dashboards are fully configuration-driven, meaning they can be updated without modifying frontend or backend code.

For example, a simple ART Cascade dashboard in 3DL:

<TabSet>
 <Tab title="ART Cascade">
  <Dashboard>
   <Grid>
    <Row><Header>ART Cascade</Header></Row>
    <Filters>
     <Filter caption="Year" name="year" 
      values_query="SELECT DISTINCT year FROM diagnosis ORDER BY year DESC"/>
     <Filter caption="Gender" name="gender" 
      values_query="SELECT DISTINCT gender FROM client"/>
     <Filter caption="Age Group" name="age_group" 
      values_query="SELECT DISTINCT age_group FROM age_ranges"/>
    </Filters>

    <Row columns="2">
     <DataProvider>
      <QueryData>SELECT new_cases FROM art_data WHERE year = '$year'</QueryData>
      <Tile title="New Cases"/>
     </DataProvider>

     <DataProvider>
      <QueryData>SELECT initiated FROM art_data WHERE year = '$year'</QueryData>
      <Tile title="Initiated"/>
     </DataProvider>
    </Row>
  
    <Row columns="1">
     <DataProvider>
      <QueryData>  
        SELECT category, value FROM art_summary WHERE year = '$year'  
      </QueryData>
      <BarChart header="ART Cascade" subHeader="ART Outcomes"/>
     </DataProvider>
    </Row>
   </Grid>
  </Dashboard>
 </Tab>
</TabSet>

This structure instructs DUFT UI to dynamically render dashboards with data-driven visuals, filters, and navigation.

3DL files can define filters, titles, visualisations, queries, other data sources, tabs, grids, rows, columns, and more. Together with the navigation area (defined in a navigation file), they form an entirely declarative UI.

Dynamic Data Binding#

One of 3DL’s core strengths is real-time data binding. Unlike static reports, 3DL ensures dashboards always reflect live data. Instead of embedding logic in the frontend, 3DL directly binds UI components to SQL queries.

<DataProvider>  
  <QueryData>
    SELECT COUNT(client_id) AS value 
    FROM fact_sentinel_event 
    WHERE last_viral_load_result_is_suppressed = 1
  </QueryData>
  <Tile title="Suppressed Cases" />  
</DataProvider>```

 
Here, the QueryData component retrieves data dynamically, binding it to the Tile component without additional configuration.

However, SQL is not the only data source. 3DL includes data providers that can fetch data from:

- SQL databases (MySQL, PostgreSQL, SQLite, SQL Server)
- Web-based APIs
- OpenMRS
- Static datasets
- Others (in the future)  

This flexibility allows DUFT dashboards to integrate clinical, administrative, and external data seamlessly.

For example, the following query pulls data from OpenMRS’ Appointments API and displays it inside a table:

``` JSX
<DataProvider pageSize="20" searchColumns='client_id, marital_status'>
   <OpenmrsData
     resource="appointments/search"
     method="POST"
       body={{
         startDate: "2025-01-20",
         endDate: "2025-01-20",
      }}
      adapter="patientsFromAppointments"
   />
   <InfiniteScrollTable header=“Appointments" />
 </DataProvider>

This pulls data directly from OpenMRS and renders it dynamically, without requiring custom frontend code.

NOTE:  The OpenMRS Data Provider is designed to display operational data into DUFT. It is not designed for OpenMRS reporting — for reporting it is recommended to first use Mamba ETL to flatten the data, and then use the QueryProvider to query the Mamba ETL database.

Interpreting the 3DL: A Custom Parser#

DUFT’s 3DL Parser dynamically converts 3DL configurations into React components at runtime. Instead of static UI definitions, dashboards are instantly generated by parsing 3DL and mapping it to live React components. This approach ensures that UI layouts are decoupled from static code, allowing immediate updates by modifying DUFT Config—without redeploying the frontend. The Parser will be discussed more in the DUFT UI chapter.

Contents