move

docs/skills/nicegui/references/architecture.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.

docs/skills/nicegui/references/source-documentation.md

@@ -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