Dashboard Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Kodus Runtime Dashboard is a web-based user interface for monitoring events and workflows within the Kodus event processing system. Built as a single-page application using React and Vite, it provides a real-time view of system statistics by communicating with the backend API. The dashboard is a key component of the monorepo, designed to offer observability into the Rust-based runtime core.
The application is structured with a main layout that includes a persistent sidebar for navigation and a header. It uses client-side routing to render different pages for the Dashboard, Events, Workflows, and Settings, allowing users to navigate the application without full page reloads.
Sources: README.md, apps/dashboard/package.json, apps/dashboard/src/pages/Dashboard.tsx:1-30
Architecture and Core Components
The dashboard is a React application bootstrapped with Vite. Its architecture is component-based, centered around a main App component that manages routing and a Layout component that provides the consistent UI shell.
Sources: apps/dashboard/package.json, apps/dashboard/src/App.tsx
Component Hierarchy
The following diagram illustrates the primary component structure of the dashboard application.
This diagram shows that the App.tsx component sets up the Router, which wraps a Layout component and a set of Routes. The Layout contains the Sidebar and Header, while the Routes map URL paths to specific page components.
Sources: apps/dashboard/index.html, apps/dashboard/src/App.tsx:1-10, apps/dashboard/src/components/Layout.tsx
Key Components
| Component | File Path | Description |
|---|---|---|
App | apps/dashboard/src/App.tsx | The root component that sets up react-router-dom and defines the application's routes. |
Layout | apps/dashboard/src/components/Layout.tsx | A wrapper component that provides the main structure, including the Sidebar and Header. |
Sidebar | apps/dashboard/src/components/Sidebar.tsx | Renders the main navigation menu with links to different pages. |
Header | apps/dashboard/src/components/Header.tsx | Displays the top bar of the application with the dashboard title. |
Dashboard | apps/dashboard/src/pages/Dashboard.tsx | The main landing page, displaying key statistics about the runtime. |
Workflows | apps/dashboard/src/pages/Workflows.tsx | A placeholder page for managing workflows, currently displaying a "coming soon" message. |
Sources: apps/dashboard/src/App.tsx, apps/dashboard/src/components/Layout.tsx, apps/dashboard/src/pages/Workflows.tsx:1-10
Routing
Client-side routing is managed by react-router-dom. The App.tsx component defines the available paths and maps them to their corresponding page components.
| Path | Component | Description |
|---|---|---|
/ | Dashboard | The main dashboard view. |
/events | Events | Page for viewing events (component not detailed in provided files). |
/workflows | Workflows | Page for managing workflows. |
/settings | Settings | Page for application settings (component not detailed). |
Sources: apps/dashboard/src/App.tsx:10-15, apps/dashboard/src/components/Sidebar.tsx:4-9
Dashboard Page
The main Dashboard page is responsible for fetching and displaying high-level statistics from the Kodus Runtime API.
Sources: apps/dashboard/src/pages/Dashboard.tsx
Data Fetching
The component uses the @tanstack/react-query library to fetch data from the /api/events/stats endpoint.
- Query Key:
['stats'] - Fetching Logic: Makes a
fetchrequest to/api/events/stats. - Polling: The data is automatically refetched every 5 seconds (
refetchInterval: 5000) to provide near real-time updates.
Sources: apps/dashboard/src/pages/Dashboard.tsx:7-15
The following sequence diagram shows the data fetching flow.
Displayed Statistics
The dashboard displays several metric cards. The Stats interface defines the expected data structure from the API.
// From apps/dashboard/src/pages/Dashboard.tsx
interface Stats {
totalEvents: number
treeStats: string
}
Sources: apps/dashboard/src/pages/Dashboard.tsx:3-6
| Statistic | Value Source | Notes |
|---|---|---|
| Total Events | stats.totalEvents | Fetched from the /api/events/stats endpoint. |
| Active Workflows | Hardcoded 0 | This value is static and does not reflect real data. |
| Queue Size | Hardcoded 0 | This value is static and does not reflect real data. |
Sources: apps/dashboard/src/pages/Dashboard.tsx:48-50, apps/dashboard/src/pages/Dashboard.tsx:70-72, apps/dashboard/src/pages/Dashboard.tsx:92-94
Technology Stack
The dashboard is built with a modern frontend toolchain. The key dependencies are listed in its package.json.
| Dependency | Version | Purpose |
|---|---|---|
react | ^19.1.1 | Core UI library. |
react-router-dom | ^7.9.1 | Client-side routing. |
@tanstack/react-query | ^5.90.1 | Data fetching, caching, and state synchronization. |
axios | ^1.12.2 | HTTP client for making API requests. |
tailwindcss | ^4.1.13 | Utility-first CSS framework for styling. |
vite | ^7.1.7 | Build tool and development server. |
@heroicons/react | ^2.2.0 | Icon library. |
Sources: apps/dashboard/package.json:11-20
Deployment
The dashboard is designed to be deployed as a Docker container. The docker-compose.yml file defines a dashboard service that builds a Docker image from tools/docker/Dockerfile.dashboard and exposes it on port 80.
# From tools/docker/docker-compose.yml
services:
# ...
dashboard:
build:
context: ../..
dockerfile: tools/docker/Dockerfile.dashboard
container_name: kodus-dashboard
ports:
- "80:80"
environment:
- NODE_ENV=production
restart: unless-stopped
# ...
This configuration makes the dashboard accessible at http://localhost when running the Docker setup.
Sources: tools/docker/docker-compose.yml:29-43, README.md:68-70