prompts/docs/skills/nicegui/SKILL.md

name, description, argument-hint, x-personal-mcp

name	description	argument-hint	x-personal-mcp
nicegui	Design and scaffold a production-ready NiceGUI + FastAPI application architecture. Use for multi-page app planning, package boundaries, optional DB/LangGraph/docs integration, and implementation checklists.	What should this app include (pages, DB, AI, docs, constraints)?	id version tags capabilities depends_on nicegui 1.0.0 nicegui fastapi ui architecture resource://skills/nicegui/document

NiceGUI

Design a production-minded NiceGUI + FastAPI architecture with clear boundaries, optional extensions, and a concrete implementation checklist.

When to Use

• You need a reusable architecture plan before implementing a NiceGUI app.
• You want FastAPI app-factory structure and lifespan wiring.
• You need optional guidance for database, LangGraph workflows, or mounted static docs.
• You want output that is concise, structured, and implementation-ready.

Inputs to Collect

Collect these inputs up front. If not provided, make safe defaults and state assumptions.

• Product scope and primary user journeys.
• Required pages and route map.
• Whether persistent data is required.
• Whether AI orchestration (multi-step, streaming, approvals) is required.
• Whether generated docs should be mounted in-app.
• Runtime/deployment constraints (single service vs split services, environment requirements).

Outcome

Produce:

• A concise architecture explanation.
• How core services, UI pages, and UI components fit together.
• Explicit decision on DB ownership or involvement.
• Explicit decision on AI workflow (or no AI).
• A checklist implementation plan organized by package and domain.

Procedure

1. Frame the baseline architecture.
2. Choose optional extensions (DB, AI, docs) using decision points below.
3. Map modules, dependencies, and key boundaries.
4. Define async behavior and UI responsiveness expectations.
5. Define key functions/classes and configuration surfaces.
6. Produce phased checklist with rollout or migration notes when relevant.
7. Run completion checks before returning.

1) Baseline architecture

Use a src-layout with FastAPI as the ASGI app and NiceGUI registered via composition.

• App factory pattern: create_app().
• Lifespan for startup and shutdown resource management.
• api/ for HTTP handlers, services/ for business logic.
• ui/pages/ for page modules, ui/components/ for shared UI.
• Health endpoint on FastAPI side: /healthz.

Recommended base shape:

.
├─ pyproject.toml
├─ .env.example
├─ README.md
├─ src/
│  └─ app/
│     ├─ __init__.py
│     ├─ main.py
│     ├─ bootstrap.py
│     ├─ config.py
│     ├─ logging.py
│     ├─ api/
│     │  ├─ __init__.py
│     │  └─ health.py
│     ├─ services/
│     │  ├─ __init__.py
│     │  └─ example_service.py
│     └─ ui/
│        ├─ __init__.py
│        ├─ components/
│        │  ├─ __init__.py
│        │  └─ nav.py
│        └─ pages/
│           ├─ __init__.py
│           ├─ home.py
│           ├─ dashboard.py
│           └─ about.py
└─ tests/
   ├─ test_health.py
   └─ test_pages_registration.py

2) Decision points

Database needed?

• If no: keep services/ pure and skip persistence layers.
• If yes: add db/ package with engine/session/model/repository layering.
• Prefer one process-level engine and request-scoped sessions via yield.
• Prefer Alembic migrations for schema changes.

AI workflow needed?

• If no: keep services/ focused on app logic only.
• If yes: add ai/ package (state, nodes, graph, runtime, contracts).
• Keep graph internals out of ui/pages/ and API handlers.
• Use stable thread/session IDs for resumable flows.

Mounted docs needed?

• If no: skip docs mounting.
• If yes: mount generated static site under configurable route (default /docs).
• Keep docs mounting in composition layer, not page modules.

3) Page and component registration

• Require at minimum page modules for /, /dashboard, /about.
• Prefer explicit registration pattern:
  • ui/pages/__init__.py exports register_pages().
  • Each page module exports register_page().
• Shared shell components (header/nav/drawer) live in ui/components/.

4) Dependency direction rules

Prefer:

• main/bootstrap -> config/logging + api + ui/pages + services
• api -> services
• ui/pages -> ui/components + services
• services -> helpers/clients (and db/ when enabled)

Avoid reverse imports from services into API or UI modules.

5) Async and UI responsiveness rules

• Prefer async def for page handlers, service methods, and integrations when the call path includes I/O.
• Use non-blocking clients/libraries where possible so long-running I/O does not freeze UI updates.
• Do not run blocking calls (time.sleep, blocking HTTP/database clients) in UI event handlers.
• For heavy CPU work, offload to worker/background execution and keep the UI loop free.
• Show progress states for long actions (disable action button, show spinner/progress text, re-enable on completion).
• Stream or chunk incremental results to the UI when workflows are multi-step or long-running.
• Keep cancellation and timeout behavior explicit for user-triggered long tasks.
• Ensure exceptions from async tasks are surfaced with user-friendly feedback and logged for diagnostics.

6) Testing minimums

• Test FastAPI health route behavior.
• Test page registration wiring.
• If DB enabled: session lifecycle and rollback behavior tests.
• If AI enabled: graph happy path and interrupt/resume coverage.
• If docs enabled: mounted docs route returns index page.
• For async flows: test long-running actions preserve UI responsiveness (loading state, completion state, and error state).

7) Styling architecture

• Keep structure and layout in Python modules using NiceGUI class composition.
• Keep visual polish in shared CSS files, loaded once at startup.
• Prefer semantic reusable classes over ad hoc per-page styling.

Completion Checks

• 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.
• Optional DB/AI/docs decisions are explicit and reflected in structure.
• Output includes architecture summary and package-organized checklist.

Output Contract

Return:

• Concise high-level architecture.
• How core services, pages, and shared components fit.
• DB involvement and ownership stance.
• AI workflow stance and runtime flow.
• Checklist plan by package and domain:
  • key functions/classes
  • settings/config surfaces
  • rollout/migration notes (when relevant)

Guardrails

• Do not collapse all pages into one file.
• Do not use globals or implicit global side effects.
• Do not block UI event handlers with synchronous I/O or long CPU tasks.
• Always define loading/progress/error states for long user-triggered actions.
• Keep code minimal but production-minded.
• Prefer clarity and maintainability over clever abstractions.

References

• Architecture and integration details: NiceGUI architecture reference
• Source documentation links: NiceGUI source documentation