# 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
│     ├─ 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.

## 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](./styling-and-customization.md).

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