prompts/skills/nicegui/references/architecture.md

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:

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:

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.