Implementation Plan: Dashboard Health Windows

Branch: 026-dashboard-health-windows | Date: 2026-03-10 | Spec: spec.md Input: Feature specification from /specs/026-dashboard-health-windows/spec.md

Summary

Implement automated LLM validation policies with "Execution Windows" to distribute database load, and create a centralized "Health Center" UI to monitor the latest validation status (Pass/Warn/Fail) of all dashboards, integrating status badges into the main sidebar and AI assistant.

Technical Context

Language/Version: Python 3.9+ (Backend), Node.js 18+ / Svelte 5.x (Frontend) Primary Dependencies: FastAPI, SQLAlchemy, APScheduler (Backend) | SvelteKit, Tailwind CSS, existing UI components (Frontend) Storage: PostgreSQL / SQLite (existing database for ValidationRecord and new ValidationPolicy) Testing: pytest (Backend), vitest (Frontend) Target Platform: Linux server (Docker), Web Browser Project Type: Full-stack web application (Internal Tool) Performance Goals: Schedule and distribute 100+ validation tasks within a 1-hour window without database CPU spikes > 80%; Health Center loads in < 2 seconds. Constraints: Must integrate with existing TaskManager and LLMAnalysisPlugin; UI must reuse existing Tailwind patterns. Scale/Scope: Dozens of policies, hundreds of dashboards, generating daily validation records.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Semantic Protocol Compliance: [DEF], @PRE, @POST, @UX_STATE tags will be strictly used for new modules and components.
Modular Plugin Architecture: The validation logic will continue to reside in the existing DashboardValidationPlugin. The scheduling logic (ThrottledScheduler) will be integrated into the core SchedulerService or built as a specialized orchestrator.
Unified Frontend Experience: The new Health Center will use Tailwind CSS and standard API wrappers (fetchApi/requestApi). No native fetch.
Security & RBAC: The Health Center and Settings will use existing permission guards (e.g., Admin or specific dashboard view rights).
Independent Testability: The scheduler logic (time distribution calculation) and Health Center API data aggregation will be independently testable.
Asynchronous Execution: The background validation tasks are inherently async via TaskManager.

Project Structure

Documentation (this feature)

specs/026-dashboard-health-windows/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── modules.md
└── tasks.md

Source Code

backend/
├── src/
│   ├── api/
│   │   └── routes/
│   │       └── health.py          # New endpoint for Health Center data
│   │       └── settings.py        # Update for validation policies CRUD
│   ├── core/
│   │   └── throttled_scheduler.py # NEEDS CLARIFICATION: Should this be a standalone orchestrator or extend APScheduler?
│   ├── models/
│   │   └── llm.py                 # Update ValidationRecord, add ValidationPolicy
│   └── services/
│       └── health_service.py      # Aggregation logic for Health Center

frontend/
├── src/
│   ├── lib/
│   │   ├── api/
│   │   │   └── health.js          # API client for Health Center
│   │   └── components/
│   │       └── health/
│   │           ├── HealthMatrix.svelte
│   │           └── PolicyForm.svelte
│   ├── routes/
│   │   ├── dashboards/
│   │   │   └── health/
│   │   │       └── +page.svelte   # Health Center view
│   │   └── settings/
│   │       └── automation/
│   │           └── +page.svelte   # Validation policies view

Structure Decision: A standard full-stack slice adding a new feature view (Health Center) and a settings view (Automation Policies), supported by backend API routes, models, and a custom scheduling component.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Custom Scheduler wrapper	APScheduler handles strict cron, but we need dynamic, distributed execution within a window.	Writing a monolithic cron job that sleeps/loops blocks the worker thread and is hard to observe.

4.5 KiB Raw Blame History