Architecture

nivq is a single self-contained Java 25 service that handles LLM orchestration in one process, backed by PostgreSQL + pgvector and Redis. It is deliberately a single deployable unit — simpler to run on-prem and to audit.

The request path

User ──▶ Agent (chat) ──▶ LLM provider ──▶ SQL draft
                                              │
                                       ┌──────▼──────┐
                                       │  SQL guard  │  read-only validation
                                       └──────┬──────┘
                                              ▼
                                   Your data source (read)
                                              │
                                              ▼
                         Result ──▶ chart / table   +   audit log entry

A user asks in natural language; the agent's LLM drafts SQL; a guard validates it (only reads pass); nivq executes against your data source and renders the result. Every validation, execution, and denial is written to the audit log.

Governed-agentic by design

nivq reasons across multiple tool calls and learns from past queries, but it is read-only at the baseline. Any mutation — or any new pattern the agent wants to remember — is parked in a human approval queue. A person approves before anything is applied or learned. This is the line between governed agentic AI and the autonomous kind that acts without per-step approval.

Multi-tenant isolation

Workspaces are isolated at five layers:

1. Auth — every request is scoped to a workspace and role (OWNER > ADMIN > MEMBER), read from a signed token.
2. Routing — the active workspace is resolved per request and carried through the call.
3. Query — data access is filtered by workspace; cross-tenant reads are structurally impossible.
4. Storage — credentials and secrets are encrypted at rest (AES-256).
5. Audit — the audit log is partitioned per workspace.

Bring your own LLM

Each agent binds to its own LLM provider, so different agents can use different models — OpenAI, Anthropic, Azure, or a local Ollama. A separate platform-managed provider handles lightweight internal tasks. Nothing forces your data through a single vendor model.

MCP-native mode

Where policy forbids any vendor-initiated database connection, nivq runs in an MCP-native mode: instead of nivq opening a connection to your database, your side exposes data through the Model Context Protocol, and nivq consumes it. No direct DB connection from the platform.

Licensing module

Licensing is a first-class, unconditional module: every deployment runs under a signed licence that nivq verifies offline against an embedded key, stores in its own database as the source of truth, and tracks through a clear lifecycle (valid → expiring → grace → locked). See Licensing & activation.

Compliance posture

The architecture is built to be KVKK / BDDK / GDPR / EU AI Act compatible: data residency (on-prem / your cloud), read-only-by-design with human approval, comprehensive audit, encryption, and identity via OIDC/SSO.