Architecture

NKZ OS is a FIWARE-native multi-tenant platform for digital twins in agriculture, industry, and environment. It runs on Kubernetes with a polyrepo module system — each domain (weather, LiDAR, robotics, ERP) is an independent Git repository deployed as a federated remote.

Core services

┌─────────────────────────────────────────────────────────┐
│                    INGRESS (Traefik)                     │
│  nekazari.example.com   api.example.com   auth.example.com │
└────┬──────────────┬──────────────┬──────────────────────┘
     │              │              │
     ▼              ▼              ▼
┌─────────┐  ┌──────────┐  ┌──────────┐
│ frontend│  │   API    │  │ Keycloak │
│  host   │  │ gateway  │  │  OIDC    │
│ (React) │  │ (Flask)  │  │ 26.4.7   │
└─────────┘  └────┬─────┘  └──────────┘
                  │
     ┌────────────┼──────────────┐
     ▼            ▼              ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐
│Orion-LD │ │  Entity  │ │ Timeseries   │
│NGSI-LD  │ │ Manager  │ │ Reader       │
│Context  │ │(FastAPI) │ │(FastAPI)     │
│Broker   │ └──────────┘ └──────┬───────┘
└───┬─────┘                     │
    │                           │
    ▼                           ▼
┌─────────┐              ┌──────────────┐
│ MongoDB │              │ PostgreSQL   │
│(entity  │              │ + TimescaleDB│
│registry)│              │ (telemetry)  │
└─────────┘              └──────────────┘

Data flow

1. Ingress (Traefik) terminates TLS and routes by Host header
2. API Gateway (Flask) validates JWT, injects X-Tenant-ID, proxies to services
3. Orion-LD is the single source of truth for all NGSI-LD entities
4. Entity Manager (FastAPI) provides CRUD, marketplace, module lifecycle
5. TimescaleDB stores time-series telemetry via NGSI-LD subscriptions

Auth flow

• Keycloak 26 OIDC with RS256 (JWKS)
• Auth token: httpOnly cookie nkz_token (no localStorage)
• Gateway extracts tenant from tenant_id user attribute
• Module backends use nkz-platform-sdk require_auth() — never implement JWKS validation locally

Multi-tenancy

• One Keycloak realm, one Orion-LD instance
• Tenant isolation: Keycloak user attribute tenant_id → NGSI-LD ?tenant= query param
• TimescaleDB: tenant column on all hypertables, RLS not used (TimescaleDB limitation)
• Tenant quotas enforced by tenant-webhook against admin_platform.tenant_limits

Module system (Module Federation 2.0)

Host (React 18 + Vite 5)
 │
 ├── @nekazari/module-kit    ◀── SDK for module authors
 ├── @nekazari/ui-kit         ◀── Design system components
 ├── @nekazari/viewer-kit     ◀── CesiumJS viewer components
 │
 └── loadRemote() at runtime  ◀── @module-federation/runtime
      │
      ├── vegetation-prime    (remoteEntry.js from MinIO)
      ├── crop-health         (remoteEntry.js from MinIO)
      ├── lidar               (remoteEntry.js from MinIO)
      └── ... (15 modules)

Each module is an independent repo with its own package.json, k8s/, CI/CD, and ArgoCD Application. The host loads them at runtime — no rebuild needed.

Module anatomy

nkz-module-<name>/
  src/Module.tsx        → defineModule({ id, slots, route, i18n, ... })
  src/slots/            → slot widgets (map-layer, context-panel, timeline, ...)
  src/main.tsx          → dev entry (wraps module in MockProvider)
  backend/              → FastAPI (optional) with nkz-platform-sdk
  k8s/                  → Deployment, Service, Ingress
  package.json          → nkz.moduleId field

Key packages:

• @nekazari/module-kit (Apache-2.0) — defineModule(), hooks, mock layer
• @nekazari/module-builder — Vite preset, emits mf-manifest.json + remoteEntry.js
• nkz-platform-sdk (Apache-2.0) — require_auth(), OrionClient(tenant_id)

Data model (NGSI-LD)

All entities follow FIWARE Smart Data Models vocabulary. Canonical types:

Type	Description
AgriParcel	Agricultural parcel
AgriCrop	Crop on a parcel
AgriSoil	Soil properties
AgriSensor	IoT sensor device
WeatherObserved	Weather observation
WeatherStation	Weather station
ManufacturingMachine	Tractor / implement
AutonomousMobileRobot	Autonomous field robot

Relationships use ref + target type: refAgriParcel, refAgriFarm, refDeviceProfile.

Repository map

Repo	Purpose
nkz-os/nkz	Platform monorepo (host, API gateway, core services)
nkz-os/nkz-gitops-starter	Production deployment starter kit
nkz-os/gitops-config	Private production overlays
nkz-os/nkz-module-*	Individual module repos (15+)
nkz-os/nkz-mobile	React Native field app

Tech stack summary

Layer	Technology
Frontend	React 18, TypeScript 5, Vite 5, Tailwind, CesiumJS
Backend	Python (Flask sync, FastAPI async)
Context	FIWARE Orion-LD (NGSI-LD 1.6)
Databases	PostgreSQL/TimescaleDB, MongoDB
Cache/Queue	Redis (Celery, RQ, rate limiting)
Auth	Keycloak 26 (OIDC RS256)
Infra	K3s, Traefik, cert-manager, MinIO, Mosquitto
GitOps	ArgoCD (App-of-Apps pattern)
i18n	react-i18next (es, en, ca, eu, fr, pt)