John Lancaster
92 lines
2.3 KiB
Markdown
92 lines
2.3 KiB
Markdown
# 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. |