69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
# CONTEXT — Activity / Audit Log
|
||
|
||
Living scratchpad for the feature. The orchestrator updates this between phases. Tier-2
|
||
context (survives across phases; graduates to CLAUDE.md only if it's a lasting project truth).
|
||
|
||
## Config (from approval)
|
||
|
||
- **Mode:** Automated · **Execution:** Orchestrator · **Strategy:** Incremental
|
||
- **Base/merge target:** `master` · **Branch:** `feature/activity-log` · **Branch point:** `17dd2e0`
|
||
- Final merge ALWAYS requires user approval (even in Automated mode).
|
||
|
||
## Product decisions (locked)
|
||
|
||
- Placement: BOTH a top-level **Activity** tab AND a Dashboard **Recent Activity** widget,
|
||
plus a Settings retention panel.
|
||
- Scope: all four categories — entity CRUD, auth, device connect/disconnect, capture & system.
|
||
- Detail: **action metadata only** (no before/after diffs).
|
||
- Durability: **export on demand (CSV/JSON)** + existing whole-DB backup. **No** separate
|
||
backup subsystem.
|
||
- WebUI work uses the `frontend-design` skill (Phases 5–6).
|
||
|
||
## Key codebase facts (verified during planning)
|
||
|
||
- `fire_entity_event(entity_type, action, entity_id)` @ `api/dependencies.py:202` — central
|
||
hook, called by every entity route synchronously in-request; has `_deps` store access.
|
||
- `ProcessorManager.fire_event(dict)` / `subscribe_events()` @ `core/processing/processor_manager.py`
|
||
back `/api/v1/events/ws` (`api/routes/output_targets_control.py:206`). `fire_event` does
|
||
`put_nowait` (no `call_soon_threadsafe`) — fine for the existing consumer; recorder marshals.
|
||
- Frontend realtime: `core/events-ws.ts` re-dispatches `server:<type>`; `_ALLOWED_SERVER_EVENT_TYPES`
|
||
(line 39) is parity-checked by `tests/test_events_ws_parity.py`. Must add `activity_logged`.
|
||
- Actor: `request.state.auth_label` set in `api/auth.py` (129 authenticated, 83 anonymous).
|
||
- Storage: `Database` singleton (`storage/database.py`, single conn, RLock, WAL,
|
||
`synchronous=FULL`, `get_setting/set_setting`). `BaseSqliteStore` loads ALL rows to memory →
|
||
AVOID for the log. Migrations: `storage/data_migrations.py` (`ALL_MIGRATIONS`, idempotent).
|
||
- Backup/restore is **whole-DB** (`Database.backup_to`/`restore_from`, no STORE_MAP allowlist)
|
||
→ the new `activity_log` table is auto-covered. No `system.py` STORE_MAP edit needed.
|
||
- Background-engine pattern: `core/backup/auto_backup.py` (start/stop loop, `_prune`, settings).
|
||
- Thread-marshal precedent: `utils/log_broadcaster.py` (`ensure_loop` + `call_soon_threadsafe`).
|
||
- Device seams: `device_health_changed` (`core/processing/device_health.py`, on transition) +
|
||
`device_discovered`/`device_lost` (`core/devices/discovery_watcher.py`, **zeroconf thread**).
|
||
- **No** API-key create/rotate/revoke routes exist (only `GET /system/api-keys`) → those auth
|
||
events are DESCOPED.
|
||
- Existing **Log Viewer** (`utils/log_broadcaster.py`) = ephemeral debug-log tail; the audit
|
||
log is a different, persistent, structured feature. Differentiate; do not duplicate.
|
||
|
||
## Frozen contracts (fill as phases complete)
|
||
|
||
- ActivityLogEntry fields / dict shape: _(Phase 1/2 handoff)_
|
||
- ActivityLogFilters shape: _(Phase 1 handoff)_
|
||
- recorder.record(...) signature + actor ContextVar import path: _(Phase 2 handoff)_
|
||
- API endpoints + query params + page envelope + settings bounds: _(Phase 4 handoff)_
|
||
|
||
## Failed approaches / rejected designs
|
||
|
||
- Buffered async-writer subsystem (asyncio.Queue): REJECTED — unsafe from the zeroconf thread
|
||
and adds a shutdown-flush ordering hazard. Using direct synchronous-on-loop writes with
|
||
`call_soon_threadsafe` marshaling instead (simpler + correct).
|
||
- Using `BaseSqliteStore` for the log: REJECTED — loads all rows into memory.
|
||
- Separate activity-log backup subsystem: REJECTED — whole-DB backup already covers the table;
|
||
export-on-demand is the portability story.
|
||
|
||
## Deferred / open
|
||
|
||
- Setup-scaffold first-run noise suppression (batch/suppress flag) — deferred (nice-to-have).
|
||
|
||
## Phase progress notes
|
||
|
||
_(Orchestrator appends a short note per phase: what landed, commit sha, any warnings.)_
|