---
name: nicegui
description: 'Design and scaffold a production-ready NiceGUI + FastAPI application architecture. Use for multi-page app planning, package boundaries, optional DB/LangGraph/docs integration, and implementation checklists.'
argument-hint: 'What should this app include (pages, DB, AI, docs, constraints)?'
---

# NiceGUI

Design a production-minded NiceGUI + FastAPI architecture with clear boundaries, optional extensions, and a concrete implementation checklist.

## When to Use

- You need a reusable architecture plan before implementing a NiceGUI app.
- You want FastAPI app-factory structure and lifespan wiring.
- You need optional guidance for database, LangGraph workflows, or mounted static docs.
- You want output that is concise, structured, and implementation-ready.

## Inputs to Collect

Collect these inputs up front. If not provided, make safe defaults and state assumptions.

- Product scope and primary user journeys.
- Required pages and route map.
- Whether persistent data is required.
- Whether AI orchestration (multi-step, streaming, approvals) is required.
- Whether generated docs should be mounted in-app.
- Runtime/deployment constraints (single service vs split services, environment requirements).

## Outcome

Produce:

- A concise architecture explanation.
- How core services, UI pages, and UI components fit together.
- Explicit decision on DB ownership or involvement.
- Explicit decision on AI workflow (or no AI).
- A checklist implementation plan organized by package and domain.

## Procedure

1. Frame the baseline architecture.
2. Choose optional extensions (DB, AI, docs) using decision points below.
3. Map modules, dependencies, and key boundaries.
4. Define key functions/classes and configuration surfaces.
5. Produce phased checklist with rollout or migration notes when relevant.
6. Run completion checks before returning.

### 1) Baseline architecture

Use a src-layout with FastAPI as the ASGI app and NiceGUI registered via composition.

- App factory pattern: `create_app()`.
- Lifespan for startup and shutdown resource management.
- `api/` for HTTP handlers, `services/` for business logic.
- `ui/pages/` for page modules, `ui/components/` for shared UI.
- Health endpoint on FastAPI side: `/healthz`.

Recommended base shape:

```text
.
├─ pyproject.toml
├─ .env.example
├─ README.md
├─ src/
│  └─ app/
│     ├─ __init__.py
│     ├─ main.py
│     ├─ bootstrap.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
```

### 2) Decision points

#### Database needed?

- If no: keep `services/` pure and skip persistence layers.
- If yes: add `db/` package with engine/session/model/repository layering.
- Prefer one process-level engine and request-scoped sessions via `yield`.
- Prefer Alembic migrations for schema changes.

#### AI workflow needed?

- If no: keep `services/` focused on app logic only.
- If yes: add `ai/` package (state, nodes, graph, runtime, contracts).
- Keep graph internals out of `ui/pages/` and API handlers.
- Use stable thread/session IDs for resumable flows.

#### Mounted docs needed?

- If no: skip docs mounting.
- If yes: mount generated static site under configurable route (default `/docs`).
- Keep docs mounting in composition layer, not page modules.

### 3) Page and component registration

- Require at minimum page modules for `/`, `/dashboard`, `/about`.
- Prefer explicit registration pattern:
  - `ui/pages/__init__.py` exports `register_pages()`.
  - Each page module exports `register_page()`.
- Shared shell components (header/nav/drawer) live in `ui/components/`.

### 4) Dependency direction rules

Prefer:

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

Avoid reverse imports from services into API or UI modules.

### 5) Testing minimums

- Test FastAPI health route behavior.
- Test page registration wiring.
- If DB enabled: session lifecycle and rollback behavior tests.
- If AI enabled: graph happy path and interrupt/resume coverage.
- If docs enabled: mounted docs route returns index page.

### 6) Styling architecture

- Keep structure and layout in Python modules using NiceGUI class composition.
- Keep visual polish in shared CSS files, loaded once at startup.
- Prefer semantic reusable classes over ad hoc per-page styling.

## Completion Checks

- Uses app factory and FastAPI lifespan.
- Pages are modularized (not single-file UI).
- Health endpoint exists on FastAPI side.
- Dependency direction is clean and one-way.
- Optional DB/AI/docs decisions are explicit and reflected in structure.
- Output includes architecture summary and package-organized checklist.

## Output Contract

Return:

- Concise high-level architecture.
- How core services, pages, and shared components fit.
- DB involvement and ownership stance.
- AI workflow stance and runtime flow.
- Checklist plan by package and domain:
  - key functions/classes
  - settings/config surfaces
  - rollout/migration notes (when relevant)

## Guardrails

- Do not collapse all pages into one file.
- Do not use globals or implicit global side effects.
- Keep code minimal but production-minded.
- Prefer clarity and maintainability over clever abstractions.

## References

- Architecture and integration details: [NiceGUI architecture reference](./references/architecture.md)
- Source documentation links: [NiceGUI source documentation](./references/source-documentation.md)