Deprecation message

2026-08-08 22:43:01 +01:00
parent 2735e6e96b
commit 26ca2d3256
33 changed files with 889 additions and 637 deletions
@@ -0,0 +1,85 @@
+# DynaLab Architecture and Naming
+
+## Goals
+
+DynaLab accepts live data from multiple connector implementations and presents it in a
+desktop UI. The architecture keeps transport code, application state, and Dear PyGui
+code independent so that adding a connector or UI feature does not require edits across
+unrelated modules.
+
+## Data Flow
+
+```text
+connector session -> ConnectorEvent queue -> UI feature controller -> feature state -> view
+```
+
+The connector thread owns sockets, handshakes, and heartbeat bookkeeping. It communicates
+with the main thread only through immutable events. The main thread owns application state
+and all Dear PyGui calls.
+
+## Package Layout
+
+```text
+src/dynalab/
+  app.py                    composition, lifecycle, frame loop, shutdown
+  state.py                  focused application, signal, and recording state
+  connectors/
+    events.py               typed connector-to-application events
+    protocol_server.py      asyncio server and connector sessions
+  ui/
+    shell.py                top-level window, menus, and feature navigation
+    loading/                loading view and tags
+    errors/                 error modal view and tags
+    live_data/              gauge view, event controller, and tags
+    recording/              recording view, controller, presenter, and tags
+```
+
+Feature folders own their widgets, tags, callbacks, and model-to-widget synchronization.
+Avoid global tag collections and modules named after generic implementation techniques,
+such as `windows`, `routines`, or `render`.
+
+## Naming
+
+- `build_*` creates widgets once.
+- `refresh_*` synchronizes existing widgets from state.
+- `on_*` is a thin Dear PyGui callback.
+- `handle_*` processes an application event or user intent.
+- `start_*` and `stop_*` control service lifecycle.
+- `load_*` and `save_*` access persistent storage.
+- `*_tag` functions generate dynamic Dear PyGui identifiers.
+- `*State` holds mutable state owned by the main thread.
+- `*Event` is immutable communication across a boundary.
+
+Tags are feature-qualified strings, for example `recording.dialog` and
+`live_data.gauge.<uuid>`. Display labels are never parsed to recover domain identifiers;
+features maintain explicit label-to-ID mappings.
+
+## Ownership Rules
+
+- Only the connector thread accesses streams, sessions, and heartbeat timestamps.
+- Only the main thread mutates `ApplicationState` and calls Dear PyGui.
+- `app.py` composes services and dispatches events; it does not build feature widgets.
+- Controllers translate intent or events into state changes and view operations.
+- Views construct widgets and contain no connector logic.
+- Presenters format state for existing widgets and contain no networking logic.
+
+## Adding a Connector
+
+A connector adapts its transport into the event types in `connectors/events.py`. It must
+not mutate application state or invoke Dear PyGui. Connector-specific handshake and
+framing stay within its own server/session implementation.
+
+## Adding a UI Feature
+
+Create a folder under `ui/` containing only the pieces the feature needs. A typical
+feature has `view.py`, `controller.py`, `presenter.py`, and `tags.py`; small features may
+use fewer files. Register its top-level view in `ui/shell.py` and dispatch relevant events
+from the application loop.
+
+## Testing Boundaries
+
+- Test event and state behavior without importing Dear PyGui.
+- Test controllers with a stubbed gauge or Dear PyGui adapter.
+- Test connector sessions with local asyncio streams or protocol fakes.
+- Keep manual connector simulators under `test/` or move them to `tools/` when the
+  automated integration suite is introduced.