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), = (is), ∈ (of), ⌬ (by), ✦ (at).

Current subsystems:

• ꩜ Pulse — provides async execution with resource-aware scheduling
• Elements ⧉ — persistent interactive UI primitive
• Plugins — domain logic via gRPC, isolated from core (e.g. local AI)

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 — an element is exactly one DOM element for its entire lifetime; reparented, never cloned
• One-Per-Side Axiom — each side of an element 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

Technical Context

┌──────────── Core ─────────────┐
│  ATS (attestation type system) │
│  ⊔ DB (storage)               │
│  ≡ config (configuration)     │
│  ꩜ Pulse (async execution)    │
│  ⋈ ax (query)                 │
└───────┬──────────┬────────────┘
        │          │
  gRPC (plugins)  WebSocket + REST (browser)
        │          │
  ┌─────┴───┐  ┌──┴──────────────┐
  │ Domain  │  │ Web UI           │
  │ plugins │  │  Canvas (⧉)      │
  └─────────┘  └──────────────────┘

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 — storage and inference on your machine. Cloud is opt-in, not required.
• Core is minimal — ATS (incl. ⋈ ax), DB, ≡ config, ꩜ Pulse. Everything else is a plugin over gRPC.
• One core for every runtime — parsing, filters, query resolution, watcher matching, identity and signing are implemented once, in Rust, and the node and the browser run the same code. See Design Philosophy and Release.

5. Building Block View

┌──────────────────── Core ────────────────────┐
│  ATS        Attestation Type System          │
│  ⊔ DB       Storage                          │
│  ≡ config   Configuration                    │
│  ꩜ Pulse    Async execution + scheduling     │
│  Server     HTTP, WebSocket                  │
└──────────────────────────────────────────────┘
         │                    │
    gRPC (plugins)       shared core
         │                    │
┌────────┴────────┐  ┌───────┴────────────────┐
│ Domain plugins  │  │ Rust core              │
│                 │  │  node and browser      │
└─────────────────┘  └────────────────────────┘

Architecture deep-dives:

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

6. Runtime View

Key runtime flows:

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

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

Element meld DAG: meld detection → edge creation → subscription activates → attestation arrives → downstream element fires

Browser ↔ node: live updates over WebSocket, requests over REST.

Detailed flows:

• Element Attestation Flow
• GRACE (❀ PulseClose)

7. Deployment View

A single binary with the web UI inside. 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
• Desktop and mobile app — a wrapper around the web UI
• CLI

See Installation, Nix Development, Release.

8. Cross-cutting Concepts

SEG / Sym / Element

Every operator has three layers:

• seg — the grammatical unit (what it IS)
• sym — the visual expression (how it LOOKS)
• element — 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.

Vision Documents

• Elements — persistent interactive UI primitive
• Fractal Workspace — nested canvas navigation
• Element Melding — composition through adjacency
• Time-Travel — attestation state across time
• Clusters — spatial organization
• Mobile — mobile-native experience, kept with the App

Other

• Embeddings — vector search (⊨ se)

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
└── 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 elements — plugins attest new UI elements
└── One core shared across platforms

See Design Philosophy.

11. Risks and Technical Debt

12. Glossary

See GLOSSARY.md.