move
This commit is contained in:
John Lancaster
@@ -0,0 +1,196 @@
|
||||
---
|
||||
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)
|
||||
@@ -0,0 +1,92 @@
|
||||
# NiceGUI Architecture Reference
|
||||
|
||||
This reference expands the workflow in the main skill file and is loaded only when needed.
|
||||
|
||||
## Baseline package boundaries
|
||||
|
||||
- `main.py`: process entrypoint only.
|
||||
- `bootstrap.py`: app composition, router wiring, page registration, lifespan orchestration.
|
||||
- `config.py`: typed settings and env parsing.
|
||||
- `logging.py`: centralized logging setup.
|
||||
- `api/`: HTTP transport layer; delegates to services.
|
||||
- `services/`: business/use-case logic.
|
||||
- `ui/pages/`: route-level NiceGUI pages.
|
||||
- `ui/components/`: shared UI building blocks.
|
||||
|
||||
## Required baseline behavior
|
||||
|
||||
- FastAPI is the base ASGI app.
|
||||
- NiceGUI pages are modular and registered from page modules.
|
||||
- Minimum pages: `/`, `/dashboard`, `/about`.
|
||||
- FastAPI health route: `/healthz`.
|
||||
- Lifespan handles startup/shutdown resources.
|
||||
- No global side effects at import time.
|
||||
|
||||
## Optional extension: Database
|
||||
|
||||
Use only if persistence is required.
|
||||
|
||||
Suggested additions:
|
||||
|
||||
```text
|
||||
src/app/db/
|
||||
├─ __init__.py
|
||||
├─ base.py
|
||||
├─ session.py
|
||||
├─ models/
|
||||
└─ repositories/
|
||||
```
|
||||
|
||||
Guidelines:
|
||||
|
||||
- One engine and one sessionmaker per process.
|
||||
- Request-scoped session dependency using `yield`.
|
||||
- Explicit transaction boundaries in service/repository flows.
|
||||
- Avoid shared sessions across concurrent tasks.
|
||||
- Use Alembic as schema source of truth.
|
||||
|
||||
## Optional extension: LangGraph AI
|
||||
|
||||
Use only for multi-step AI orchestration or human-in-the-loop workflows.
|
||||
|
||||
Suggested additions:
|
||||
|
||||
```text
|
||||
src/app/ai/
|
||||
├─ state.py
|
||||
├─ nodes/
|
||||
├─ graphs/
|
||||
├─ runtime.py
|
||||
└─ contracts.py
|
||||
```
|
||||
|
||||
Guidelines:
|
||||
|
||||
- Keep graph internals outside API/UI modules.
|
||||
- Invoke graph through `services/ai_service.py`.
|
||||
- Use stable thread/session IDs for resumable sessions.
|
||||
- Keep interrupt payloads JSON-serializable.
|
||||
|
||||
## Optional extension: Mounted static docs
|
||||
|
||||
Use only when generated docs should be served in-app.
|
||||
|
||||
Suggested settings:
|
||||
|
||||
- `docs_enabled`
|
||||
- `docs_mount_path`
|
||||
- `docs_site_dir`
|
||||
- `docs_require_build` (optional)
|
||||
|
||||
Guidelines:
|
||||
|
||||
- Mount docs in composition layer (`bootstrap.py`).
|
||||
- Normalize mount path and avoid route conflicts.
|
||||
- Warn on missing build artifacts unless strict mode is enabled.
|
||||
|
||||
## Suggested output quality criteria
|
||||
|
||||
- Clear architecture summary with assumptions.
|
||||
- Explicit decisions for DB, AI, and docs.
|
||||
- Package-scoped implementation checklist.
|
||||
- Minimal test plan aligned to enabled features.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Source Documentation
|
||||
|
||||
Use these links for framework-specific details.
|
||||
|
||||
## FastAPI
|
||||
|
||||
- FastAPI lifespan events: https://fastapi.tiangolo.com/advanced/events/
|
||||
- FastAPI settings and environment variables: https://fastapi.tiangolo.com/advanced/settings/
|
||||
- FastAPI dependencies with yield: https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/
|
||||
- FastAPI SQL databases tutorial: https://fastapi.tiangolo.com/tutorial/sql-databases/
|
||||
|
||||
## SQLAlchemy and Alembic
|
||||
|
||||
- SQLAlchemy engine configuration and pooling: https://docs.sqlalchemy.org/en/20/core/engines.html
|
||||
- SQLAlchemy session lifecycle basics: https://docs.sqlalchemy.org/en/20/orm/session_basics.html
|
||||
- Alembic tutorial: https://alembic.sqlalchemy.org/en/latest/tutorial.html
|
||||
|
||||
## Pydantic
|
||||
|
||||
- Pydantic settings management: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/
|
||||
|
||||
## NiceGUI
|
||||
|
||||
- NiceGUI pages/routing and FastAPI integration: https://www.nicegui.io/documentation/section_pages_routing
|
||||
- NiceGUI security best practices: https://www.nicegui.io/documentation/section_security
|
||||
|
||||
## LangGraph
|
||||
|
||||
- LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview
|
||||
- LangGraph quickstart: https://docs.langchain.com/oss/python/langgraph/quickstart
|
||||
- LangGraph workflows and agents: https://docs.langchain.com/oss/python/langgraph/workflows-agents
|
||||
- LangGraph persistence: https://docs.langchain.com/oss/python/langgraph/persistence
|
||||
- LangGraph memory concepts: https://docs.langchain.com/oss/python/concepts/memory
|
||||
- LangGraph streaming: https://docs.langchain.com/oss/python/langgraph/streaming
|
||||
- LangGraph interrupts and human-in-the-loop: https://docs.langchain.com/oss/python/langgraph/interrupts
|
||||
Reference in New Issue
Block a user