# penguinboi12/dachshund architecture

> Architecture diagram of the GitHub repository penguinboi12/dachshund, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/penguinboi12/dachshund
- Repository: https://github.com/penguinboi12/dachshund

## Overview

Dachshund is an embedded, live admin dashboard for Python services. The host application initializes a dashboard, declares pages, rows, widgets and actions, then emits named events; the dashboard stores and renders those events and pushes updates to connected browser pages over WebSocket. Separate branches cover authentication, action invocation, queryable tables and logs, aggregation and persistence, and widget-specific browser assets. Several runtime modules are indexed but not excerpted, so their connections are included only where the index or README supports them.

Main entry points: [`dachshund/registry.py`](https://github.com/penguinboi12/dachshund/blob/main/dachshund/registry.py) (Dashboard registry), [`dachshund/runtime/http.py`](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/http.py) (HTTP pages), [`dachshund/runtime/ws.py`](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/ws.py) (Live WebSocket), [`dachshund/storage/events.py`](https://github.com/penguinboi12/dachshund/blob/main/dachshund/storage/events.py) (Event store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Dashboard authoring"]
  node_dashboard["Dashboard registry<br/>[registry.py]"]
  node_layout["Pages and layout<br/>[layout.py]"]
  node_actions["User actions<br/>[actions.py]"]
end

subgraph group_serving["Dashboard runtime"]
  node_auth["Authorization<br/>[access.py]"]
  node_http["HTTP pages<br/>[http.py]"]
  node_runtime["Server lifecycle<br/>[boot.py]"]
  node_ws["Live WebSocket<br/>[ws.py]"]
  node_render["Widget rendering<br/>[render.py]"]
  node_dashboardjs["Dashboard client<br/>[dashboard.js]"]
end

subgraph group_events["Events and state"]
  node_queue["Event queue<br/>[queue.py]"]
  node_store[("Event store<br/>[events.py]")]
  node_db[("SQLite setup<br/>[db.py]")]
end

subgraph group_widgets["Widgets and display"]
  node_widgetcore["Widget base<br/>[base.py]"]
  node_aggregate["Value aggregation<br/>[aggregate.py]"]
  node_persist["Persistent state<br/>[persistable.py]"]
  node_state["Keyed widget state<br/>[state.py]"]
  node_table["Queryable tables<br/>[table.py]"]
  node_query["Table queries<br/>[query.py]"]
  node_logs["Log capture<br/>[logs.py]"]
  node_charts["Chart widgets<br/>[line.py]"]
  node_assets["Widget browser assets<br/>[charts.js]"]
end

node_host(("Host application"))
node_browser(("Dashboard browser"))

node_host -->|"initializes"| node_dashboard
node_host -->|"declares pages"| node_dashboard
node_host -->|"emits events"| node_dashboard
node_dashboard -->|"registers pages"| node_layout
node_dashboard -->|"sets up"| node_db
node_dashboard -->|"creates"| node_store
node_dashboard -->|"queues events"| node_queue
node_dashboard -->|"starts"| node_runtime
node_dashboard -->|"binds widgets"| node_widgetcore
node_layout -->|"places widgets"| node_widgetcore
node_layout -->|"builds actions"| node_actions
node_queue -->|"appends events"| node_store
node_ws -.->|"drains events"| node_queue
node_ws -->|"appends and compacts"| node_store
node_ws -->|"renders updates"| node_render
node_ws -->|"broadcasts updates"| node_browser
node_browser -->|"opens socket"| node_ws
node_browser -.->|"runs client"| node_dashboardjs
node_http -->|"checks access"| node_auth
node_http -->|"renders pages"| node_render
node_http -->|"runs actions"| node_actions
node_http -->|"serves pages"| node_browser
node_render -->|"renders payloads"| node_widgetcore
node_render -->|"reads events"| node_store
node_widgetcore -->|"reads event data"| node_store
node_aggregate -->|"extends"| node_persist
node_state -->|"extends"| node_persist
node_table -->|"uses queries"| node_query
node_table -->|"updates rows"| node_state
node_logs -->|"uses table behavior"| node_table
node_charts -->|"aggregates values"| node_aggregate
node_http -->|"serves widget scripts"| node_assets

click node_dashboard "https://github.com/penguinboi12/dachshund/blob/main/dachshund/registry.py"
click node_layout "https://github.com/penguinboi12/dachshund/blob/main/dachshund/layout.py"
click node_actions "https://github.com/penguinboi12/dachshund/blob/main/dachshund/actions.py"
click node_auth "https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/access.py"
click node_http "https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/http.py"
click node_runtime "https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/boot.py"
click node_queue "https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/queue.py"
click node_store "https://github.com/penguinboi12/dachshund/blob/main/dachshund/storage/events.py"
click node_db "https://github.com/penguinboi12/dachshund/blob/main/dachshund/storage/db.py"
click node_ws "https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/ws.py"
click node_render "https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/render.py"
click node_dashboardjs "https://github.com/penguinboi12/dachshund/blob/main/dachshund/static/dashboard.js"
click node_widgetcore "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/base.py"
click node_aggregate "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/aggregate.py"
click node_persist "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/persistable.py"
click node_state "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/state.py"
click node_table "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/table/table.py"
click node_query "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/query.py"
click node_logs "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/logs/logs.py"
click node_charts "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/chart/line.py"
click node_assets "https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/chart/charts.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_layout,node_actions,node_browser toneBlue
class node_auth,node_http,node_runtime,node_ws,node_render,node_dashboardjs toneAmber
class node_queue,node_store,node_db toneMint
class node_widgetcore,node_aggregate,node_persist,node_state,node_table,node_query,node_logs,node_charts,node_assets toneRose
class node_host toneIndigo
```

## Components

### Dashboard authoring

- [Dashboard registry](https://github.com/penguinboi12/dachshund/blob/main/dachshund/registry.py): `dachshund/registry.py`
- [Pages and layout](https://github.com/penguinboi12/dachshund/blob/main/dachshund/layout.py): `dachshund/layout.py`
- [User actions](https://github.com/penguinboi12/dachshund/blob/main/dachshund/actions.py): `dachshund/actions.py`

### Dashboard runtime

- [Authorization](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/access.py): `dachshund/runtime/access.py`
- [HTTP pages](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/http.py): `dachshund/runtime/http.py`
- [Server lifecycle](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/boot.py): `dachshund/runtime/boot.py`
- [Live WebSocket](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/ws.py): `dachshund/runtime/ws.py`
- [Widget rendering](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/render.py): `dachshund/runtime/render.py`
- [Dashboard client](https://github.com/penguinboi12/dachshund/blob/main/dachshund/static/dashboard.js): `dachshund/static/dashboard.js`

### Events and state

- [Event queue](https://github.com/penguinboi12/dachshund/blob/main/dachshund/runtime/queue.py): `dachshund/runtime/queue.py`
- [Event store](https://github.com/penguinboi12/dachshund/blob/main/dachshund/storage/events.py): `dachshund/storage/events.py`
- [SQLite setup](https://github.com/penguinboi12/dachshund/blob/main/dachshund/storage/db.py): `dachshund/storage/db.py`

### Widgets and display

- [Widget base](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/base.py): `dachshund/widgets/base.py`
- [Value aggregation](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/aggregate.py): `dachshund/widgets/aggregate.py`
- [Persistent state](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/persistable.py): `dachshund/widgets/persistable.py`
- [Keyed widget state](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/state.py): `dachshund/widgets/state.py`
- [Queryable tables](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/table/table.py): `dachshund/widgets/table/table.py`
- [Table queries](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/query.py): `dachshund/widgets/query.py`
- [Log capture](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/logs/logs.py): `dachshund/widgets/logs/logs.py`
- [Chart widgets](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/chart/line.py): `dachshund/widgets/chart/line.py`
- [Widget browser assets](https://github.com/penguinboi12/dachshund/blob/main/dachshund/widgets/chart/charts.js): `dachshund/widgets/chart/charts.js`

### Other components

- **Host application**
- **Dashboard browser**

## Connections

- Host application → Dashboard registry: initializes (evidence: `README.md`)
- Host application → Dashboard registry: declares pages (evidence: `README.md`)
- Host application → Dashboard registry: emits events (evidence: `README.md`)
- Dashboard registry → Pages and layout: registers pages (evidence: `dachshund/registry.py`)
- Dashboard registry → SQLite setup: sets up (evidence: `dachshund/registry.py`)
- Dashboard registry → Event store: creates (evidence: `dachshund/registry.py`)
- Dashboard registry → Event queue: queues events (evidence: `dachshund/registry.py`)
- Dashboard registry → Server lifecycle: starts (evidence: `dachshund/registry.py`)
- Dashboard registry → Widget base: binds widgets (evidence: `dachshund/registry.py`)
- Pages and layout → Widget base: places widgets (evidence: `dachshund/layout.py`)
- Pages and layout → User actions: builds actions (evidence: `dachshund/layout.py`)
- Event queue → Event store: appends events (evidence: `dachshund/runtime/queue.py`)
- Live WebSocket → Event queue: drains events
- Live WebSocket → Event store: appends and compacts (evidence: `dachshund/runtime/ws.py`)
- Live WebSocket → Widget rendering: renders updates (evidence: `dachshund/runtime/ws.py`)
- Live WebSocket → Dashboard browser: broadcasts updates (evidence: `dachshund/runtime/ws.py`)
- Dashboard browser → Live WebSocket: opens socket (evidence: `README.md`)
- Dashboard browser → Dashboard client: runs client
- HTTP pages → Authorization: checks access (evidence: `dachshund/runtime/http.py`)
- HTTP pages → Widget rendering: renders pages (evidence: `dachshund/runtime/http.py`)
- HTTP pages → User actions: runs actions (evidence: `dachshund/runtime/http.py`)
- HTTP pages → Dashboard browser: serves pages (evidence: `dachshund/runtime/http.py`)
- Widget rendering → Widget base: renders payloads (evidence: `dachshund/runtime/render.py`)
- Widget rendering → Event store: reads events (evidence: `dachshund/runtime/render.py`)
- Widget base → Event store: reads event data (evidence: `dachshund/widgets/base.py`)
- Value aggregation → Persistent state: extends (evidence: `dachshund/widgets/aggregate.py`)
- Keyed widget state → Persistent state: extends (evidence: `dachshund/widgets/state.py`)
- Queryable tables → Table queries: uses queries (evidence: `dachshund/widgets/table/table.py`)
- Queryable tables → Keyed widget state: updates rows (evidence: `dachshund/widgets/table/table.py`)
- Log capture → Queryable tables: uses table behavior (evidence: `dachshund/widgets/logs/logs.py`)
- Chart widgets → Value aggregation: aggregates values (evidence: `dachshund/widgets/chart/timeseries.py`)
- HTTP pages → Widget browser assets: serves widget scripts (evidence: `dachshund/runtime/http.py`)