reformatted to be more skill-like

2026-06-16 23:46:05 -05:00
parent c8906cef7b
commit 35a3a8dbed
3 changed files with 241 additions and 321 deletions
@@ -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.