# GUI Architecture Overview

Niamoto GUI is the interactive layer used to configure, inspect, and operate a
Niamoto project.

It combines:

- a Python backend built with FastAPI
- a React frontend built with Vite
- an optional desktop runtime through Tauri

## Main responsibilities

### Backend

The backend is responsible for:

- resolving the active project instance
- exposing configuration and data APIs
- orchestrating import, transform, preview, build, and deploy jobs
- serving the built frontend in packaged mode

Key entry points:

- `src/niamoto/gui/api/app.py`
- `src/niamoto/gui/api/context.py`

### Frontend

The frontend is responsible for:

- import and auto-configuration review
- dataset and reference exploration
- group configuration
- site editing and layout work
- build and deployment workflows
- desktop onboarding and project switching

The frontend uses a feature-oriented structure:

- `src/niamoto/gui/ui/src/app`
- `src/niamoto/gui/ui/src/features`
- `src/niamoto/gui/ui/src/shared`

Some root folders still hold compatibility code, but they are no longer the
default extension points:

- `src/niamoto/gui/ui/src/hooks`: compatibility façades for hooks that are being moved into `src/features` or `src/shared`
- `src/niamoto/gui/ui/src/lib/api`: compatibility façades for feature APIs that are being moved closer to their domain
- `src/niamoto/gui/ui/src/components`: shared UI primitives plus cross-feature components that have not moved into a feature yet

Current architecture guardrails:

- new domain logic should land in a feature folder first
- only truly cross-feature code should land in `src/shared`
- route modules should be imported by leaf path instead of feature barrels to preserve lazy chunk boundaries
- feature APIs and query keys should live next to the feature they serve
- large optional editors or third-party modules should remain behind lazy boundaries

## Main GUI domains

- `dashboard`: home route and project hub
- `import`: file upload, auto-configuration, import execution, enrichment entry points
- `collections`: collection and widget configuration, still routed under `/groups`
- `site`: page, navigation, and appearance editing
- `publish`: build and deploy workflows
- `tools`: utility screens such as preview, explorer, plugins, settings
- `welcome`: desktop onboarding and project selection

## Code entry points

For the concrete route map and backend wiring, inspect:

- `src/niamoto/gui/ui/src/app/router.tsx`
- `src/niamoto/gui/api/app.py`