UI API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• ui/main.py
• ui/README.md
• TODO_ts.md
• TODO_python.md
• bubus/bridge_postgres.py

Introduction

The bubus UI is a monitoring dashboard designed to provide real-time visibility into the event bus lifecycle. It is built as a minimal FastAPI web application that interfaces with a SQLite history backend. The system tracks event statuses, handler results, and parent-child relationships between events. Sources: ui/README.md:3-6, ui/main.py:27-28

The primary purpose of these API endpoints is to expose event and result logs stored by the SQLiteHistoryMirrorMiddleware. This allows developers and administrators to debug asynchronous event flows, monitor performance, and verify error taxonomy across both Python and TypeScript runtimes. Sources: ui/README.md:1-10, TODO_ts.md:255-258

Core API Endpoints

The UI backend provides several RESTful endpoints and a WebSocket stream to facilitate data retrieval and real-time monitoring. Sources: ui/main.py:465-515

REST Endpoints

The following table summarizes the available HTTP GET endpoints:

Endpoint	Method	Parameters	Description
/	GET	None	Serves the main HTML dashboard interface.
/events	GET	limit (int, 1-200)	Retrieves the latest processed events in JSON format.
/results	GET	limit (int, 1-200)	Retrieves the latest handler execution results in JSON format.
/meta	GET	None	Returns database path, existence status, and table readiness flags.

Sources: ui/main.py:465-498, ui/README.md:23-28

WebSocket Streaming

The system utilizes WebSockets to push live updates to the frontend as new rows appear in the database. Sources: ui/main.py:501-515

• Endpoint: WS /ws/events
• Query Parameters:
  • since_event_id: The ID of the last event received by the client to prevent duplicates.
  • since_result_id: The ID of the last result received by the client.
• Logic: The backend enters an infinite loop, polling the database via db.stream_new_rows and sending JSON updates containing events and results lists.

Sources: ui/main.py:501-515, ui/README.md:28

Data Flow and Architecture

The UI API acts as a consumer of data produced by the bubus middleware system. It specifically depends on tables generated by the mirror middleware. Sources: ui/README.md:3-6, TODO_ts.md:255-258

System Interaction Diagram

The following diagram illustrates how the API interacts with the storage layer and the frontend.

The UI dashboard consumes history logs produced by the EventBus through specialized mirror middlewares. Sources: ui/README.md:3-10, bubus/bridge_postgres.py:126-130

Request Lifecycle Sequence

When a client requests the latest event data, the backend follows a structured retrieval process.

The backend includes a _format_timestamp utility to ensure SQLite timestamp strings are converted to ISO 8601 format before reaching the client. Sources: ui/main.py:31-41, ui/main.py:465-470

Metadata and Schema Validation

The /meta endpoint provides diagnostic information regarding the health of the monitoring system. It checks for the existence of the physical database file and the specific tables required for logging. Sources: ui/main.py:488-498

Field	Type	Description
db_path	string	Absolute path to the SQLite history file.
db_exists	boolean	True if the file exists on the filesystem.
events_table_exists	boolean	Indicates if events_log table is ready.
results_table_exists	boolean	Indicates if event_results_log table is ready.

Sources: ui/main.py:488-498, ui/README.md:25

Implementation Details

Timestamp Normalization

Timestamps retrieved from the database are normalized to ensure consistency across the UI. This is critical because the Python and TypeScript runtimes may use different monotonic or wall-clock anchors. Sources: ui/main.py:31-41, TODO_python.md:92-95

# From ui/main.py:31-41
def _format_timestamp(value: str | None) -> str | None:
    if not value:
        return None
    try:
        return datetime.fromisoformat(value.replace('Z', '+00:00')).isoformat()
    except ValueError:
        return value

Event Ingestion and Filtering

The frontend JavaScript (served via /) performs client-side ingestion of the API responses to build a hierarchical tree view of events, resolving event_parent_id relationships. Sources: ui/main.py:186-215, ui/main.py:228-251

Conclusion

The UI API Endpoints serve as the bridge between the internal event bus history and the developer-facing dashboard. By providing both standard REST access and real-time WebSocket updates, the system ensures that event flows and handler failures (e.g., EventHandlerTimeoutError, EventHandlerAbortedError) are observable and searchable. Sources: ui/README.md:1-10, TODO_ts.md:26-31