QNTX Architecture Documentation

Based on the arc42 template. This document is an entrypoint — it links to existing docs where content lives and fills gaps inline.

1. Introduction and Goals

Requirements Overview

QNTX stores and retrieves attestations — structured claims of the form:

[Subject] = [Predicate] ∈ [Context] ⌬ [Actor] ✦ [Time]

Building blocks: + (as/assert), = (is/identity), ∈ (of/membership), ⌬ (by/actor), ✦ (at/temporal).

Current subsystems:

• ATS — Attestation Type System: attest your own types, store and retrieve them (⋈ ax/ask)
• ꩜ Pulse — provides async execution with resource-aware scheduling
• Glyphs ⧉ — persistent interactive UI primitive
• Plugins — domain logic via gRPC, isolated from core (e.g. local AI via Ollama/ONNX)

Quality Goals

See Design Philosophy.

Stakeholders

The intent is public good. Governance is centralized now, with decentralized stakeholdership as a future direction.

2. Architecture Constraints

Constraints are expressed as axioms — invariants that throw at runtime if violated.

• Element Axiom — a glyph is exactly one DOM element for its entire lifetime; reparented, never cloned
• One-Per-Side Axiom — each side of a glyph accepts at most one meld connection
• DAG Axiom — compositions are DAGs; cycles cannot form
• One attestation, one execution — downstream fires once per incoming attestation, not batched
• Everything is an attestation — the unit of flow through the DAG is always an attestation
• Subscriptions compile eagerly — meld edges activate on assembly, not on play

Full definitions: AXIOMS.md

3. System Scope and Context

Business Context

  Browser ──▶ QNTX node ◀──▶ QNTX node ◀── Browser
  Phone ────▶     │                │     ◀── Phone
              Plugins          Plugins
              (gRPC)           (gRPC)
                  │                │
                  └──── sync ──────┘
                   Merkle / symmetric
                   no coordinator

              any transport:
              TCP, WebSocket, LoRa, satellite, serial

• Browsers, phones, satellites — anything that runs a node
• Any number of clients can connect to any node
• Any number of nodes can sync with each other
• Plugins attach per-node via gRPC

Every node generates a did:key identity (ed25519) on first boot. No authority issues it.

Current: WebSocket sync between known peers, nodes identified by DID. Vision: Reticulum — transport-agnostic, delay-tolerant, self-routing. Node DID and Reticulum destination converge to the same keypair.

See sync.md, vision/reticulum.md, vision/identity.md.

Technical Context

┌──────────── Core ─────────────┐
│  ATS (attestation type system) │
│  ⊔ DB (SQLite, migrations)    │
│  ≡ am (configuration)         │
│  ꩜ Pulse (async execution)    │
│  ⋈ ax (query)                 │
└───────┬──────────┬────────────┘
        │          │
  gRPC (plugins)  WebSocket + REST (browser)
        │          │
  ┌─────┴───┐  ┌──┴──────────────┐
  │ Domain  │  │ Web UI           │
  │ plugins │  │  CodeMirror (ATS)│
  │         │  │  Canvas (⧉)     │
  └─────────┘  │  WASM (qntx-core)│
               └──────────────────┘

See Understanding QNTX.

4. Solution Strategy

Key technical decisions and why:

• Attestations as the primitive — not documents, not rows, not objects. Structured claims that compose, sync, and verify.
• Local-first — SQLite on your machine, Ollama on your machine. Cloud is opt-in, not required.
• Core is minimal — ATS, DB, ≡ am, ꩜ Pulse, ⋈ ax. Everything else is a plugin over gRPC.
• Rust/WASM for cross-runtime logic — parser, fuzzy engine, Merkle tree. One implementation, three runtimes (server via wazero, browser via wasm-bindgen, native tests via cargo). See Design Philosophy and Distribution Strategy.

5. Building Block View

┌──────────────────── Core ────────────────────┐
│  ats/       Attestation Type System          │
│  db/        SQLite + migrations              │
│  am/        Configuration (5-layer precedence)│
│  pulse/     Async execution + scheduling     │
│  server/    HTTP, WebSocket, LSP             │
│  sync/      Merkle reconciliation            │
└──────────────────────────────────────────────┘
         │                    │
    gRPC (plugins)      WASM (qntx-core)
         │                    │
┌────────┴────────┐  ┌───────┴────────────────┐
│ Domain plugins  │  │ Rust crates            │
│ (Go, Python,    │  │  qntx-core (parser,    │
│  Rust)          │  │   fuzzy, sync, merkle) │
│                 │  │  qntx-proto (types)    │
│                 │  │  qntx-wasm (bindings)  │
└─────────────────┘  └────────────────────────┘

Architecture deep-dives:

• Bounded Storage
• Config System
• Pulse Async
• Two-Phase Jobs
• Resource Coordination
• Client State
• Budget System
• Plugin-Pulse Integration Phases

Type system: types/

6. Runtime View

Key runtime flows:

Attestation lifecycle: assert → store → index → notify watchers → trigger downstream glyphs

꩜ Pulse execution: schedule tick → resource check → job dispatch → worker execution → result → budget tracking

Glyph meld DAG: meld detection → edge creation → subscription activates → attestation arrives → downstream glyph fires

Node-to-node sync: hello (root hash) → group hashes → need → attestations → done

Browser ↔ Server: WebSocket: semantic tokens, LSP protocol, ꩜ Pulse updates. REST: CRUD, sync triggers, status.

Detailed flows:

• Glyph Attestation Flow
• Grace: Opening & Closing (✿ PulseOpen / ❀ PulseClose)
• API Reference

7. Deployment View

Single Go binary, embedded web UI. Zero configuration required.

Same binary everywhere:

• Raspberry Pi — personal node
• Desktop — development or team use
• Server — always-on sync peer

Clients:

• Browser (any) — connects via WebSocket + REST
• Tauri — desktop/mobile wrapper around the web UI
• CLI

WASM (qntx-core) runs in both server (wazero) and browser (wasm-bindgen) — same Rust logic, two runtimes.

Development: make dev (Go on :877, TS hot-reload on :8820)

See Installation, Nix Development, Distribution Strategy.

8. Cross-cutting Concepts

SEG / Sym / Glyph

Every operator has three layers:

• seg — the grammatical unit (what it IS)
• sym — the visual expression (how it LOOKS)
• glyph — the interactive manifestation (how you INTERACT with it)

This is the conceptual framework that runs through everything — backend, frontend, documentation, UI.

Full definitions: GLOSSARY.md

Continuous Intelligence

A system that is always ingesting (⨳), always processing (꩜), always queryable (⋈).

See vision/continuous-intelligence.md.

Sync and Convergence

Attestations are append-only. Sync is set union — commutative, idempotent, convergent. No vector clocks, no conflict resolution. Two claims about the same subject aren't a conflict — they're two claims.

See sync.md, vision/reticulum.md.

Vision Documents

• Glyphs — persistent interactive UI primitive
• Fractal Workspace — nested canvas navigation
• Glyph Melding — reactive DAG composition
• Time-Travel — attestation state across time
• Identity — decentralized identity via did:key, short-lived delegations
• Reticulum — cryptographic mesh networking
• Clusters — spatial organization
• Mobile — mobile-native experience

Other

• Embeddings — vector search (⊨ se)
• Security: SSRF Protection

9. Architecture Decisions

10. Quality Requirements

Privacy / Local-first
├── Local inference, local storage, no mandatory cloud
├── No telemetry, no phone-home
└── Your data on your machine

Data visibility
├── Information density over visual polish
├── No text truncation (no ellipsis, ever)
└── Functional color only — color conveys status, not beauty

Performance
├── System fonts, minimal dependencies
├── Real-time updates via WebSocket
└── Efficient rendering, no decorative overhead

Semantic clarity
├── Symbols as visual grep — scan and know the domain
└── Consistent patterns for entity relationships

Extensibility
├── Plugin architecture via gRPC
├── Attestable glyphs — plugins attest new UI elements
└── WASM for cross-platform core logic

See Design Philosophy.

11. Risks and Technical Debt

12. Glossary

See GLOSSARY.md.