NiceGUI Application Architecture

Load this reference for application composition, package boundaries, and optional subsystem decisions.

Baseline Package Boundaries

main.py: process entry point and app factory exposure.
bootstrap.py: app composition, router wiring, page registration, and lifespan orchestration.
config.py: typed settings and environment parsing.
logging.py: centralized logging setup.
api/: HTTP transport that delegates to services.
services/: business and use-case logic.
ui/pages/: route-level NiceGUI pages.
ui/components/: shared presentation building blocks.

Recommended base shape:

.
├─ pyproject.toml
├─ .env.example
├─ src/
│  └─ app/
│     ├─ __init__.py
│     ├─ main.py
│     ├─ config.py
│     ├─ logging.py
│     ├─ api/
│     │  ├─ __init__.py
│     │  └─ health.py
│     ├─ services/
│     │  ├─ __init__.py
│     │  └─ example_service.py
│     └─ ui/
│        ├─ __init__.py
│        ├─ components/
│        │  ├─ __init__.py
│        │  └─ nav.py
│        └─ pages/
│           ├─ __init__.py
│           ├─ home.py
│           ├─ dashboard.py
│           └─ about.py
└─ tests/
   ├─ test_health.py
   └─ test_pages_registration.py

Required Baseline Behavior

FastAPI is the base ASGI app.
create_app() composes routes, resources, and NiceGUI.
Lifespan owns startup and shutdown resources.
NiceGUI pages are modular and explicitly registered.
FastAPI exposes a health route such as /healthz.
Imports do not trigger runtime global side effects.

For the ownership relationship between a caller-created FastAPI app, nicegui.app, ui.run_with(), Uvicorn, and a packaged startup command, load FastAPI and Uvicorn startup.

Dependency Direction

Prefer:

main/bootstrap -> config/logging + api + ui/pages + services
api -> services
ui/pages -> ui/components + services
services -> helpers, clients, and db/ when enabled

Avoid imports from services back into API or UI modules.

Page And Component Ownership

Page modules compose routes from presentation components and service calls. They should not own domain rules, persistence, or long-running synchronous work.

Extract a presentation pattern to ui/components/ when it appears on two or more pages or owns a meaningful interaction boundary. Keep one-off route composition in the page module. Reusable components should accept data and event callbacks instead of importing page state or business services implicitly.

For page composition, responsive layout, Quasar props, and CSS customization, load styling and customization.

Optional Persistence

Use only when the product requires durable data.

src/app/db/
├─ __init__.py
├─ base.py
├─ session.py
├─ models/
└─ repositories/

Create one engine and sessionmaker per process.
Provide request- or operation-scoped sessions with yield.
Keep transaction boundaries explicit in service or repository flows.
Never share sessions across concurrent tasks.
Use Alembic as the schema migration source of truth.

Optional LangGraph AI

Use only for multi-step orchestration, resumable work, streaming, or human approval.

src/app/ai/
├─ state.py
├─ nodes/
├─ graphs/
├─ runtime.py
└─ contracts.py

Keep graph internals outside API and UI modules.
Invoke graphs through a service such as services/ai_service.py.
Use stable thread or session IDs for resumable flows.
Keep interrupt payloads JSON-serializable.

Optional Mounted Docs

Use only when generated docs must be served by the application.

Suggested settings:

docs_enabled
docs_mount_path
docs_site_dir
docs_require_build

Mount docs in the composition layer, normalize the mount path, avoid route conflicts, and define behavior for missing build artifacts.

Async And Responsiveness

Use async def where a handler or service path performs I/O.
Prefer non-blocking clients and libraries.
Offload CPU-heavy work to worker or background execution.
Define progress, cancellation, timeout, completion, and error states for long actions.
Stream or chunk results when workflows are long-running or multi-step.

Testing Minimums

Test the FastAPI health route.
Test page registration wiring.
If persistence is enabled, test session lifecycle and rollback behavior.
If AI is enabled, test happy paths and interrupt/resume behavior.
If docs are enabled, test the mounted index route.
For long actions, test loading, completion, and error states.

4.7 KiB Raw Blame History