john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reorg

Browse Source
This commit is contained in:
John Lancaster
2026-06-16 23:39:45 -05:00
parent 8ada18b7fd
commit c8906cef7b
5 changed files with 269 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/nicegui/SKILL.md
+387
View File
@@ -0,0 +1,387 @@
---
name: nicegui
description: Build and scaffold production-ready NiceGUI + FastAPI app architecture.
---
# NiceGUI
Build a production-ready, multi-page NiceGUI application that follows modern FastAPI project layout and architecture practices.
## Goal
Create a clean, maintainable app structure where:
- FastAPI is the underlying ASGI app.
- NiceGUI is mounted/initialized in a way that aligns with FastAPI best practices.
- Each page is implemented as a separate module in `pages/`.
- The project is easy to test, extend, and deploy.
## Requirements
- Prefer Pydantic settings with a `.env` example.
- Consider adding structured logging configuration.
- Use a `src/`-style layout with clear package boundaries.
- Use an app factory (`create_app`) and avoid global side effects at import time.
- Register NiceGUI pages from modules in `pages/`.
- Keep UI logic in page modules and shared UI helpers/components in a separate package.
- Include at least these pages:
- Home (`/`)
- Dashboard (`/dashboard`)
- About (`/about`)
- Include a health endpoint (`/healthz`) on the FastAPI side.
- Provide minimal test examples for FastAPI routes and page registration.
- Use FastAPI lifespan for startup/shutdown resource management.
## Recommendations
- Consider a shared navigation/header component and left drawer used by all pages.
- Consider including dev tooling basics (formatting/lint/test commands).
- Prefer clear separation of concerns:
- `db/` for engine/session/base/models/repositories (if needed)
- `api/` for HTTP endpoints
- `ui/` for NiceGUI pages/components
- `services/` for business logic
- If you need database access, a solid pattern is to use FastAPI + SQLAlchemy best practices:
- Use one engine per application process (do not create per request).
- Prefer a request-scoped session dependency using `yield`.
- Keep transaction boundaries explicit (commit/rollback) in service/repository flows.
- Avoid sharing a session across concurrent tasks.
- Consider production-minded pool settings (`pool_pre_ping=True` and sensible recycle/timeout values).
- Prefer Alembic for schema migrations.
## Suggested Project Structure
Base structure (no database required):
```text
.
├─ pyproject.toml
├─ .env.example
├─ README.md
├─ src/
│ └─ app/
│ ├─ __init__.py
│ ├─ main.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
│ └─ bootstrap.py
└─ tests/
├─ test_health.py
└─ test_pages_registration.py
```
### Conceptual boundaries for the base structure
- `main.py`: application entrypoint only; wires `create_app()` and process startup concerns.
- `bootstrap.py`: app composition layer; owns app factory, router registration, page registration, and lifespan wiring.
- `config.py`: configuration boundary; centralizes settings parsing and typed config objects.
- `logging.py`: observability boundary; centralizes logging format/levels/handlers so modules do not configure logging ad hoc.
- `api/`: transport boundary for HTTP endpoints; validate/shape request-response objects and delegate business work to `services/`.
- `services/`: use-case/business boundary; orchestrates domain behavior and dependencies, independent of UI rendering.
- `ui/pages/`: route-level UI boundary; one module per page, focused on layout/event handling for that page.
- `ui/components/`: reusable presentation boundary; shared UI widgets/composition utilities with no business side effects.
- `tests/`: behavior boundary; verify public behavior (health endpoint, page registration, service outcomes), not private implementation details.
### Dependency direction to keep clear
- Prefer this dependency flow:
- `main/bootstrap` -> `config/logging` + `api` + `ui/pages` + `services`
- `api` -> `services`
- `ui/pages` -> `ui/components` + `services`
- `services` -> pure helpers/clients (and later `db/` if enabled)
- Avoid reverse imports (for example, `services` importing from `ui/pages` or `api`).
- Keep page modules and API handlers as thin adapters; keep business decisions in `services/`.
## Extending This Pattern with a Database (Optional)
If database access is needed, extend with:
```text
.
├─ alembic.ini
├─ alembic/
│ ├─ env.py
│ └─ versions/
├─ src/
│ └─ app/
│ └─ db/
│ ├─ __init__.py
│ ├─ base.py
│ ├─ session.py
│ ├─ models/
│ │ ├─ __init__.py
│ │ └─ example.py
│ └─ repositories/
│ ├─ __init__.py
│ └─ example_repo.py
└─ tests/
└─ test_db_session_dependency.py
```
### Recommended database layering
- Keep `db/` focused on persistence primitives:
- `session.py`: engine + session factory + dependency helpers
- `models/`: ORM table mappings only
- `repositories/`: query/persistence operations only
- Keep transaction orchestration in `services/`, not in UI pages.
- Keep `ui/pages/` free of SQLAlchemy details; pages call services.
- Keep API handlers thin and delegate data work to services/repositories.
### Session and transaction pattern to request
- Use one engine and one sessionmaker per process, initialized at app startup.
- Use a `get_db_session()` dependency with `yield` for request-scoped sessions.
- In write flows, always use context managers for commit/rollback safety.
- In read-only flows, avoid unnecessary transactions and keep queries narrowly scoped.
- Do not share a session across concurrent tasks; open a new session per task/unit of work.
### Migration and schema workflow
- Treat Alembic migrations as the source of truth for schema evolution.
- Prefer:
- `alembic revision --autogenerate -m "..."`
- review migration script
- `alembic upgrade head`
- Avoid relying on `metadata.create_all()` for production schema management.
- Include a lightweight startup check that logs current migration state (without mutating schema).
### Configuration and runtime concerns
- Read `DATABASE_URL` from settings (`pydantic-settings`) and keep secrets out of source control.
- Configure pool options appropriate for environment (for example: `pool_pre_ping`, timeout/recycle tuning).
- Keep SQL echo/debug logging disabled in production by default.
- Consider a readiness probe (`/readyz`) that verifies DB connectivity when your deployment needs it.
### Testing guidance for DB-enabled projects
- Unit test repositories against a disposable test database.
- Integration test `get_db_session()` lifecycle and rollback behavior on failures.
- Add migration tests that validate model changes are represented in Alembic revisions.
- Add API/service tests for critical read/write paths (including uniqueness and constraint errors).
- Keep DB tests isolated and deterministic (fresh schema + transactional cleanup per test module/session).
## Extending This Pattern with LangGraph (Optional)
If your app needs multi-step AI workflows, tool-calling loops, or human-in-the-loop approvals, a clean extension is to add a dedicated LangGraph domain layer.
### Recommended architecture shape
- Keep LangGraph logic out of `ui/pages/` and out of HTTP route handlers.
- Add an `ai/` package (or similar) and keep graph definition, state schema, tools, and orchestration there.
- Call the graph from `services/` so your UI and API both use the same orchestration entry points.
- Continue using FastAPI lifespan for shared resources (models, clients, stores/checkpointers).
### Suggested project extension
```text
.
└─ src/
└─ app/
├─ ai/
│ ├─ __init__.py
│ ├─ state.py # TypedDict / Pydantic state schemas + reducers
│ ├─ nodes/
│ │ ├─ __init__.py
│ │ ├─ llm.py
│ │ ├─ tools.py
│ │ └─ review.py # optional interrupt/human-review nodes
│ ├─ graphs/
│ │ ├─ __init__.py
│ │ └─ assistant_graph.py
│ ├─ runtime.py # compile() + checkpointer/store wiring
│ └─ contracts.py # input/output DTOs between services and graph
├─ services/
│ └─ ai_service.py # invoke/stream/resume wrappers
└─ api/
└─ ai.py # optional HTTP endpoints for run/stream/resume
```
### Idiomatic LangGraph practices to request
- Define explicit graph state schema (`TypedDict` or Pydantic) and use reducers for append/merge behavior where needed.
- Compile graphs with persistence primitives appropriate to environment:
- dev/testing: in-memory checkpointer/store
- production: durable checkpointer/store
- Always pass a stable `thread_id` in `configurable` for resumable sessions and conversation continuity.
- For interactive UX, prefer event streaming APIs and project-specific streaming adapters in service code.
- Use `interrupt()` for human approvals/reviews; resume with `Command(resume=...)` using the same `thread_id`.
- Keep interrupt payloads JSON-serializable.
- Place non-idempotent side effects after interrupts (or isolate them in separate nodes), because interrupted nodes re-run from the start.
- If using tools, prefer LangGraph’s `ToolNode` (or an equivalent centralized tool-execution node) for consistent execution/error handling.
- Keep graph nodes deterministic and narrow in scope (single responsibility per node).
- Add observability with LangSmith tracing for graph runs, transitions, and latency debugging.
### Integration guidance for NiceGUI + FastAPI
- UI pages should call `ai_service` methods, not graph internals.
- If the UX needs live token/progress updates, expose streaming from service -> UI in a transport-appropriate way.
- For approval workflows, surface interrupt payloads in UI, collect user response, then resume via service with `Command(resume=...)`.
- Keep graph invocation boundaries typed (request/response contracts) so changes in graph internals do not leak into page modules.
### Testing recommendations for LangGraph additions
- Unit test node functions as pure transformations where possible.
- Integration test graph routes (happy path, tool path, interrupt/resume path).
- Add tests ensuring `thread_id` reuse resumes correctly and new IDs start fresh sessions.
- Add regression tests for state-schema evolution and serialization compatibility.
## Extending This Pattern with a Static Docs Site via Zensical (Optional)
If the app should also host a static documentation site, mount the generated docs output directory under a configurable route (default: `/docs`).
### Recommended docs workflow
- Initialize docs in the project root:
- `uv run zensical new .`
- Keep source markdown in Zensical's `docs_dir` (default: `docs/`).
- Build docs as part of release or startup pipeline:
- `uv run zensical build`
- Serve the generated static output from Zensical's `site_dir` (default: `site/`).
### Config to include in app settings
- `docs_enabled: bool = true`
- `docs_mount_path: str = "/docs"`
- `docs_site_dir: str = "site"`
- Optional for local/dev convenience:
- `docs_require_build: bool = false` (if true, fail startup when `site/` is missing)
### FastAPI/NiceGUI integration pattern
- Keep docs mounting in the app composition layer (`bootstrap.py`), not in page modules.
- Use FastAPI static serving to mount the built directory (for example via `StaticFiles(..., html=True)`).
- Ensure `docs_mount_path` is normalized (leading slash, no trailing slash) and does not conflict with app/API routes.
- If docs are disabled or build artifacts are missing, log a clear warning and continue (unless `docs_require_build=true`).
### Suggested project additions
```text
.
├─ zensical.toml
├─ docs/
│ ├─ index.md
│ └─ ...
├─ site/ # generated by `uv run zensical build`
└─ src/
└─ app/
├─ config.py # docs_enabled/docs_mount_path/docs_site_dir
└─ bootstrap.py # mount static docs route
```
### Deployment notes for docs mounting
- In CI/CD, run `uv run zensical build` before packaging/deploying the app image.
- If `project.site_dir` in `zensical.toml` is changed, keep `docs_site_dir` in app settings aligned.
- If hosting behind a reverse proxy with a path prefix, verify docs links and static assets with the final external base path.
- Add a test asserting requests to `docs_mount_path` return the built index page when docs are enabled.
## Implementation Notes
- Prefer an explicit page registration function pattern, for example:
- `register_pages()` in `ui/pages/__init__.py`
- Each page module exports `register_page()`
- Keep imports one-way to avoid circular dependencies.
- Keep page modules cohesive: route declaration + page layout for that route.
- Prefer FastAPI lifespan hooks where appropriate for startup/shutdown behavior.
- Prefer type hints throughout.
### Styling architecture notes
- Prefer class-first UI composition for structure and layout using normal NiceGUI mechanics (`.classes(...)` on containers/components).
- Keep structural concerns in Python page/component modules (layout grids, spacing systems, responsive breakpoints, alignment).
- Keep cosmetic concerns in static CSS files (colors, gradients, shadows, border polish, typography fine-tuning, transitions).
- Avoid large inline `style(...)` strings except for one-off dynamic values that must be computed at runtime.
- Centralize CSS entrypoints in a small, predictable set (for example `ui/static/css/base.css`, `ui/static/css/theme.css`, `ui/static/css/components.css`).
- Include CSS once at app bootstrap/startup so pages share the same style contract; avoid per-page ad hoc includes.
- Prefer semantic class names for reusable patterns (`app-shell`, `page-section`, `card-surface`) and utility classes only for local layout tweaks.
- If using design tokens, define them as CSS custom properties in `:root` and reference them from component classes.
- Keep page modules focused on structure and behavior; reusable visual patterns should live in shared UI components plus shared CSS.
### Database-specific notes (only if your app needs a DB)
- Prefer settings via `pydantic-settings` and read `DATABASE_URL` from environment/dotenv.
- Configure the SQLAlchemy engine once at app setup level; avoid creating engine/sessionmaker in endpoint functions.
- Provide `get_db_session()` via `yield` so sessions are consistently closed.
- Prefer a repository/service boundary to keep SQL details out of page modules.
- Prefer Alembic for schema changes and include commands for `revision --autogenerate` and `upgrade head`.
- Avoid `metadata.create_all()` in production startup flow; reserve it for optional local/dev bootstrap paths.
- Consider a light DB readiness check in health reporting (or a dedicated `/readyz`) when relevant.
- Ensure logs do not leak secrets (for example, avoid unsafe SQL echo in production).
## Output Format
The goal of the output is to produce an output
Return:
- A concise, high-level architecture explanation.
- An explanation of how the different parts of the concept will fit into this structure
- What are the core services?
- What are the main ui pages?
- What are the main ui components?
- Whether a database will be involved and whether the app owns the database
- Whether any AI will be used and what the workflow looks like
- A concrete implementation plan in the form of a checklist, organized into sections by concept which should roughly mirror the structure of sub-packages.
- Key functions/classes
- Configuration/settings available
- Migration or rollout notes (if relevant)
## Guardrails
- Do not put all pages in a single file.
- Never use globals, implicit or otherwise.
- Keep code minimal but production-minded.
- Being clear and concise is a higher priority than being verbose.
- Prefer clarity and maintainability over clever abstractions.
## Source Documentation (recommended references)
- FastAPI lifespan events:
- https://fastapi.tiangolo.com/advanced/events/
- FastAPI settings and environment variables:
- https://fastapi.tiangolo.com/advanced/settings/
- FastAPI dependencies with `yield` (session lifecycle pattern):
- https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/
- FastAPI SQL databases tutorial (when using a DB):
- https://fastapi.tiangolo.com/tutorial/sql-databases/
- SQLAlchemy engine configuration and pooling (when using a DB):
- https://docs.sqlalchemy.org/en/20/core/engines.html
- SQLAlchemy session basics and lifecycle guidance (when using a DB):
- https://docs.sqlalchemy.org/en/20/orm/session_basics.html
- Alembic tutorial and migration environment (when using a DB):
- https://alembic.sqlalchemy.org/en/latest/tutorial.html
- Pydantic settings management:
- https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/
- 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 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 (checkpointer vs store):
- 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 / human-in-the-loop:
- https://docs.langchain.com/oss/python/langgraph/interrupts