137 lines
4.1 KiB
Markdown
137 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
.
|
|
├─ pyproject.toml
|
|
├─ .env.example
|
|
├─ 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
|
|
```
|
|
|
|
## 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](./fastapi-uvicorn-startup.md).
|
|
|
|
## 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.
|
|
|
|
## Optional Persistence
|
|
|
|
Use only when the product requires durable data.
|
|
|
|
```text
|
|
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.
|
|
|
|
```text
|
|
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. |