Add design docs for SQLite + Command Executor telemetry#269
Open
NodeJSmith wants to merge 9 commits intomainfrom
Open
Add design docs for SQLite + Command Executor telemetry#269NodeJSmith wants to merge 9 commits intomainfrom
NodeJSmith wants to merge 9 commits intomainfrom
Conversation
Move interface-design and research artifacts from .claude/ to design/ where they belong as version-controlled project docs. Add: - design/README.md explaining folder structure and conventions - design/adrs/0001 recording the SQLite + Command Executor decision - design/research/ with 7 prereq breakdowns for the implementation - CLAUDE.md section pointing to design/
Prereq 1 redesigned as full data model with normalized schema (parent tables + slim execution tables), structured identity fields, Instant timestamps, AST-based source capture, and safe JSON serialization for args/kwargs. Prereq 2 (stable_key) superseded by parent table natural keys. Cross-references updated across prereqs 3, 5, and 6.
- Prereq 3: Exception handling decisions (HassetteError logging distinction, executor owns timing, CancelledError produces record, listener.once stays in _dispatch) - Prereq 4: Frontend query requirements rewritten from "what should the UI show", Strategy A only (DB single source of truth), session queries, handler invocation drill-down (new UI view), runtime vs DB data boundary documented - Prereq 5: Full schema rewrite with 5 normalized tables (sessions, listeners, scheduled_jobs, handler_invocations, job_executions), session FK on execution tables, updated indexes - Prereq 6: All open questions resolved (aiosqlite, hassette.db, configurable retention, diskcache kept separate) - Prereq 7: Alembic setup with raw SQL migrations matching prereq 5 schema, DatabaseService init flow with orphaned session recovery - Prereq 8: New prereq for DataSyncService decomposition
Audits are diagnostic snapshots, not feasibility analysis for proposed changes. Giving them their own top-level folder under design/ clarifies the distinction and leaves room for future audit artifacts.
alert_context() is defined in web/ui/context.py (not partials.py) and calls get_all_manifests_snapshot() (not get_app_status_snapshot()).
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #269 +/- ##
=======================================
Coverage 78.57% 78.57%
=======================================
Files 128 128
Lines 8912 8912
Branches 920 920
=======================================
Hits 7003 7003
Misses 1543 1543
Partials 366 366 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive design documentation for a SQLite + Command Executor feature that will enable persistent operational telemetry in the Hassette framework. The PR reorganizes design artifacts from .claude/ into a new design/ directory with a clear structure for ADRs, research documents, audits, and interface design specifications.
Changes:
- Adds ADR-0001 documenting the decision to use SQLite with a Typed Command Executor pattern for operational telemetry
- Adds 8 prerequisite documents detailing data model, schema design, frontend query requirements, exception handling, Alembic setup, and service decomposition
- Adds a comprehensive codebase health audit (dated 2026-02-17) identifying technical debt and improvement opportunities
- Reorganizes design artifacts into
design/with subdirectories and addsdesign/README.mdto document the structure - Updates
CLAUDE.mdwith documentation about design artifact organization - Makes cosmetic table formatting improvements to
design/interface-design/system.md
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
design/README.md |
Documents the structure and purpose of the design/ directory with subdirectories for ADRs, audits, interface-design, and research |
design/adrs/0001-sqlite-command-executor-for-telemetry.md |
ADR accepting the Typed Command Executor approach for persistent telemetry, with context, consequences, and alternatives |
design/research/2026-02-16-sqlite-command-pattern/research.md |
Main research brief analyzing the SQLite + Command Executor proposal with table formatting improvements |
design/research/.../prereq-01-data-model.md |
Defines the full data model including parent tables (listeners, scheduled_jobs) and execution tables with normalized schema design |
design/research/.../prereq-02-stable-listener-identity.md |
Superseded note indicating parent tables with natural keys replaced the stable_key approach |
design/research/.../prereq-03-exception-handling-audit.md |
Documents current exception semantics in BusService and SchedulerService to ensure behavioral equivalence in the executor |
design/research/.../prereq-04-frontend-query-requirements.md |
Specifies SQL queries and index requirements driven by UI needs, with 9 query patterns defined |
design/research/.../prereq-05-schema-design.md |
Complete SQLite schema design for 5 tables with indexes, PRAGMAs, and upsert logic |
design/research/.../prereq-06-open-questions.md |
Resolves 5 technical decisions including aiosqlite choice, DB location, retention policy, and diskcache coexistence |
design/research/.../prereq-07-alembic-setup.md |
Alembic migration setup with raw SQL approach, migration directory layout, and initial schema migration |
design/research/.../prereq-08-datasyncservice-decomposition.md |
Plans decomposition of DataSyncService into TelemetryQueryService and RuntimeQueryService with method-by-method migration strategy |
design/audits/2026-02-17/research.md |
Comprehensive codebase health audit identifying 67 broad exception catches, 79% test coverage, and other technical debt |
design/interface-design/system.md |
Cosmetic table formatting improvements for better alignment |
CLAUDE.md |
Adds Design Artifacts section documenting the design/ directory structure |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
design/research/2026-02-16-sqlite-command-pattern/prereq-04-frontend-query-requirements.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…ontend-query-requirements.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+62
to
+64
| - **Field name**: `execution_start_dtme` (not `started_at` — follows project naming convention) | ||
|
|
||
| No need to store `execution_end_dtme` — `duration_ms` is sufficient and avoids redundant computation. |
There was a problem hiding this comment.
The column name execution_start_dtme uses an unconventional abbreviation "dtme". While the document states this "follows project naming convention", this abbreviation is unclear and not widely recognized. Consider using a more standard naming convention such as execution_start_time, execution_started_at, or execution_start_ts (for timestamp). The abbreviation "dtme" could be confusing for future developers and doesn't clearly communicate that this represents a datetime/timestamp value.
Suggested change
| - **Field name**: `execution_start_dtme` (not `started_at` — follows project naming convention) | |
| No need to store `execution_end_dtme` — `duration_ms` is sufficient and avoids redundant computation. | |
| - **Field name**: `execution_start_time` (not `started_at` — clearer than the old `execution_start_dtme` abbreviation) | |
| No need to store `execution_end_time` — `duration_ms` is sufficient and avoids redundant computation. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
design/with subfolders for ADRs, research, audits, and interface design (moved from.claude/); adddesign/README.mddocumenting the structure