John Lancaster
197 lines
7.2 KiB
Markdown
197 lines
7.2 KiB
Markdown
---
|
|
name: nicegui
|
|
description: '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.'
|
|
argument-hint: 'What should this app include (pages, DB, AI, docs, constraints)?'
|
|
---
|
|
|
|
# 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:
|
|
|
|
```text
|
|
.
|
|
├─ 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](./references/architecture.md)
|
|
- Source documentation links: [NiceGUI source documentation](./references/source-documentation.md)
|