89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# Implementation Plan: Dashboard Health Windows
|
|
|
|
**Branch**: `026-dashboard-health-windows` | **Date**: 2026-03-10 | **Spec**: [spec.md](./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)
|
|
|
|
```text
|
|
specs/026-dashboard-health-windows/
|
|
├── plan.md
|
|
├── research.md
|
|
├── data-model.md
|
|
├── quickstart.md
|
|
├── contracts/
|
|
│ └── modules.md
|
|
└── tasks.md
|
|
```
|
|
|
|
### Source Code
|
|
|
|
```text
|
|
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. |
|