Architecture¶

This section describes the current Niamoto architecture.

The main entry point is the runtime and system notes below. ADRs remain in the folder as background material for a few older decisions, but they are no longer the primary way to understand the codebase.

Start here¶

system-overview.md: current platform layers and runtime flow
plugin-system.md: plugin types, registry, and loading cascade
gui-overview.md: GUI backend and frontend split
gui-runtime.md: development, packaged, and desktop runtime modes
gui-preview-system.md: widget preview rendering path

Current architecture¶

Historical decision notes¶

The adr/ directory is still kept for a small set of decisions that explain why some parts of the runtime look the way they do, especially the move to DuckDB and the generic import transition. They are optional background reading, not the recommended entry point for new readers.

Core principles¶

Plugin-first. Loaders, transformers, exporters, and widgets are all plugins. Deployers extend the same system for publication targets.
Configuration-driven. YAML controls the pipeline.
DuckDB-centric. Analytics, recursive CTEs, spatial extension.
Type-safe. Pydantic models on every plugin boundary.
Deterministic IDs. Hash-based IDs make re-imports stable (configurable via id_strategy in import.yml).

Three-layer model¶

┌────────────────────────────────┐
│  Presentation                  │
│  Desktop (Tauri) · CLI · API   │
├────────────────────────────────┤
│  Services & plugins            │
│  Loaders · transformers · widgets · exporters · deployers │
├────────────────────────────────┤
│  Data                          │
│  DuckDB · EntityRegistry       │
└────────────────────────────────┘