# 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.