nicegui consolidation

docs/skills/nicegui/references/architecture.md

@@ -1,32 +1,75 @@
-# NiceGUI Architecture Reference
+# NiceGUI Application Architecture
 
-This reference expands the workflow in the main skill file and is loaded only when needed.
+Load this reference for application composition, package boundaries, and optional subsystem decisions.
 
-## Baseline package boundaries
+## 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.
+- `main.py`: process entry point and app factory exposure.
+- `bootstrap.py`: app composition, router wiring, page registration, and lifespan orchestration.
+- `config.py`: typed settings and environment parsing.
 - `logging.py`: centralized logging setup.
-- `api/`: HTTP transport layer; delegates to services.
-- `services/`: business/use-case logic.
+- `api/`: HTTP transport that delegates to services.
+- `services/`: business and use-case logic.
 - `ui/pages/`: route-level NiceGUI pages.
-- `ui/components/`: shared UI building blocks.
+- `ui/components/`: shared presentation building blocks.
 
-## Required baseline behavior
+Recommended base shape:
+
+```text
+.
+├─ pyproject.toml
+├─ .env.example
+├─ 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
+```
+
+## 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.
+- `create_app()` composes routes, resources, and NiceGUI.
+- Lifespan owns startup and shutdown resources.
+- NiceGUI pages are modular and explicitly registered.
+- FastAPI exposes a health route such as `/healthz`.
+- Imports do not trigger runtime global side effects.
 
-## Optional extension: Database
+## Dependency Direction
 
-Use only if persistence is required.
+Prefer:
 
-Suggested additions:
+- `main/bootstrap` -> `config/logging` + `api` + `ui/pages` + `services`
+- `api` -> `services`
+- `ui/pages` -> `ui/components` + `services`
+- `services` -> helpers, clients, and `db/` when enabled
+
+Avoid imports from services back into API or UI modules.
+
+## Optional Persistence
+
+Use only when the product requires durable data.
 
 ```text
 src/app/db/
@@ -37,19 +80,15 @@ src/app/db/
 └─ repositories/
 ```
 
-Guidelines:
+- Create one engine and sessionmaker per process.
+- Provide request- or operation-scoped sessions with `yield`.
+- Keep transaction boundaries explicit in service or repository flows.
+- Never share sessions across concurrent tasks.
+- Use Alembic as the schema migration source of truth.
 
-- 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 LangGraph AI
 
-## Optional extension: LangGraph AI
-
-Use only for multi-step AI orchestration or human-in-the-loop workflows.
-
-Suggested additions:
+Use only for multi-step orchestration, resumable work, streaming, or human approval.
 
 ```text
 src/app/ai/
@@ -60,33 +99,37 @@ src/app/ai/
 └─ 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 graph internals outside API and UI modules.
+- Invoke graphs through a service such as `services/ai_service.py`.
+- Use stable thread or session IDs for resumable flows.
 - Keep interrupt payloads JSON-serializable.
 
-## Optional extension: Mounted static docs
+## Optional Mounted Docs
 
-Use only when generated docs should be served in-app.
+Use only when generated docs must be served by the application.
 
 Suggested settings:
 
 - `docs_enabled`
 - `docs_mount_path`
 - `docs_site_dir`
-- `docs_require_build` (optional)
+- `docs_require_build`
 
-Guidelines:
+Mount docs in the composition layer, normalize the mount path, avoid route conflicts, and define behavior for missing build artifacts.
 
-- Mount docs in composition layer (`bootstrap.py`).
-- Normalize mount path and avoid route conflicts.
-- Warn on missing build artifacts unless strict mode is enabled.
+## Async And Responsiveness
 
-## Suggested output quality criteria
+- Use `async def` where a handler or service path performs I/O.
+- Prefer non-blocking clients and libraries.
+- Offload CPU-heavy work to worker or background execution.
+- Define progress, cancellation, timeout, completion, and error states for long actions.
+- Stream or chunk results when workflows are long-running or multi-step.
 
-- Clear architecture summary with assumptions.
-- Explicit decisions for DB, AI, and docs.
-- Package-scoped implementation checklist.
-- Minimal test plan aligned to enabled features.
+## Testing Minimums
+
+- Test the FastAPI health route.
+- Test page registration wiring.
+- If persistence is enabled, test session lifecycle and rollback behavior.
+- If AI is enabled, test happy paths and interrupt/resume behavior.
+- If docs are enabled, test the mounted index route.
+- For long actions, test loading, completion, and error states.