From abf5829c6bef51610d7ac7d07a3927d563f4c66c Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Wed, 24 Jun 2026 19:54:56 -0500 Subject: [PATCH] nicegui updates --- docs/step5.md | 47 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/docs/step5.md b/docs/step5.md index 1865a17..06964ae 100644 --- a/docs/step5.md +++ b/docs/step5.md @@ -17,15 +17,19 @@ This step composes Steps 1–4 into a usable UI. Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/registers NiceGUI pages via explicit page modules. +Reference baseline: `resource://skills/nicegui/document` + ### Core architecture decisions - **App factory:** `create_app()` - **Lifespan-managed resources:** worker start/stop managed in startup/shutdown - **Modular pages:** upload and jobs pages in separate modules (no monolithic UI file) - **Health endpoint:** FastAPI-side `/healthz` +- **UI composition:** route pages stay modular and reusable shared shell/components live under `ui/components` as needed +- **Styling architecture:** shared CSS loaded once at startup; avoid ad-hoc per-page styling drift - **Dependency direction (one-way):** - `app` -> `config/logging/db/worker/ui/api` - - `ui/pages` -> `services` + - `ui/pages` -> `ui/components` + `services` - `services` -> `db/models/providers` - no reverse imports from services into UI/API @@ -33,6 +37,14 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist - **DB:** already enabled (SQLModel + SQLite), session lifecycle remains request/service-scoped as built in prior steps. - **AI workflow:** already in place via Step 3 transcription service + Step 4 worker; UI does not call provider SDK directly. +- **Mounted docs:** not in Step 5 scope; docs mounting remains disabled for MVP. + +### Async and responsiveness stance + +- Prefer `async def` for page handlers and service boundaries when I/O is involved. +- Keep UI handlers non-blocking (no blocking sleeps or synchronous long I/O calls). +- For long-running user actions, always provide explicit loading/progress/error states. +- Keep cancellation/timeout behavior explicit for refresh/poll operations where applicable. --- @@ -62,6 +74,8 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist - `src/transcription/ui/upload_page.py` (upload flow) - `src/transcription/ui/jobs_page.py` (status list + detail) - `src/transcription/ui/__init__.py` (explicit `register_pages(...)` export) +- `src/transcription/ui/components/*` (shared shell/navigation/status components if introduced) +- `src/transcription/ui/static/*.css` (optional shared CSS loaded once at startup) ### Test files - `tests/test_app.py` @@ -74,6 +88,8 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist ## Implementation Plan + Checklist +Plan baseline and guardrails source: `resource://skills/nicegui/document` + ## Phase A — App factory and lifespan orchestration - [ ] Create `create_app()` in `src/transcription/app.py` @@ -89,6 +105,7 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist - [ ] join/cleanup worker thread/task cleanly - [ ] Register API router(s), including health route - [ ] Register NiceGUI pages via explicit page registration function +- [ ] Load shared CSS once at startup (if present) ## Phase B — FastAPI health endpoint @@ -107,7 +124,8 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist - [ ] On error: - [ ] show user-safe error message - [ ] restore ready UI state -- [ ] Ensure no blocking calls in UI event handlers beyond bounded service interaction +- [ ] Ensure non-blocking I/O in UI event handlers; offload CPU-heavy work to worker path +- [ ] Make timeout/cancellation behavior explicit for any long-running action ## Phase D — Jobs page (`ui/jobs_page.py`) @@ -117,6 +135,7 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist - [ ] Show transcript on success, error detail on failure - [ ] Include explicit refresh action and loading state - [ ] Ensure error states are surfaced to user and logged +- [ ] Keep refresh path async and bounded to avoid UI freeze ## Phase E — UI registration module @@ -125,6 +144,12 @@ Step 5 uses a **FastAPI app factory + lifespan orchestration** and mounts/regist - [ ] Ensure each page module exports `register_page(...)` - [ ] Keep page registration explicit and modular +## Phase F — Shared components and style consistency + +- [ ] Add `ui/components` module only for reusable shell elements (header/nav/status chips), not page-local logic +- [ ] Keep structural layout in Python; keep visual polish in shared CSS +- [ ] Avoid one-off styling duplication across upload/jobs pages + --- ## MCP Testing Workflow (Required) @@ -190,6 +215,7 @@ Suggested coverage: - [ ] success feedback displayed - [ ] error feedback displayed for `UploadError` - [ ] loading/progress state behavior covered +- [ ] timeout/cancellation behavior covered (if implemented) ### `tests/ui/test_jobs_page.py` - [ ] list renders job statuses @@ -202,6 +228,10 @@ Marker strategy: - [ ] `integration` for app/page/service+DB contracts - [ ] `external` not required for default Step 5 lane +Async behavior assertions: +- [ ] long-running actions keep button/inputs in expected disabled state +- [ ] completion/failure returns controls to ready state + --- ## Validation Sequence (strict) @@ -222,8 +252,10 @@ Marker strategy: - [ ] Do not collapse pages into one file. - [ ] Do not use implicit global side effects for runtime wiring. - [ ] Keep UI responsive with explicit loading/progress/error states. +- [ ] Do not block UI handlers with synchronous long I/O. - [ ] Do not place provider SDK calls in UI handlers. - [ ] Keep dependency direction one-way and maintainable. +- [ ] Keep shared UI in `ui/components`; keep service logic out of page modules. --- @@ -234,9 +266,20 @@ Marker strategy: - [ ] Upload page creates queued jobs through service boundary - [ ] Jobs list/detail pages render status/transcript/failure data - [ ] Worker lifecycle is started/stopped by app lifespan +- [ ] Async UI states (loading/success/error) are deterministic and tested - [ ] Scaffold->fill testing flow completed and validated - [ ] Full suite passes: `uv run pytest -q` +## Completion Checks (NiceGUI skill aligned) + +- [ ] Uses app factory and FastAPI lifespan +- [ ] Pages are modularized (not single-file UI) +- [ ] Health endpoint exists on FastAPI side +- [ ] Dependency direction is clean and one-way +- [ ] Async-first guidance is applied where I/O exists, with explicit non-blocking UX states +- [ ] DB/AI/docs decisions are explicit and reflected in structure +- [ ] Plan references baseline URI: `resource://skills/nicegui/document` + --- ## PR Checklist (Integrated)