High-Level Design (HLD)

Vinxi Kernel — High-Level Design (HLD)

This is the live High-Level Design for the Vinxi kernel. The HLD is deliberately not a monolithic document — the design lives in the architecture room, each part owned by one authoritative doc. This page presents that design in the standard SDLC-HLD shape (system context → components → data flows → technology → data model), pointing into the canon rather than duplicating it, so there is one home for each fact.

It supersedes HLD (Historical), which is preserved only as the original candidate stack study (now the Scale reference profile) and must not be implemented from. The corresponding low-level detail is the Low-Level Design.

1. Purpose & scope

The HLD covers the Vinxi kernel — the domain-agnostic system-of-record-and-action that Lepton’s products (NetworkAccess, Trafficure, SmartMarket, SmartBuild) are built on. It consolidates the architecture-concern analysis (data model, services/APIs, topology, integration, multi-tenancy & security, deployment). Product-specific structure — the modules × network types view — sits a layer above and is framed in §8, not detailed here.

2. System context

The kernel mediates all interaction between the outside world — userland programs, agents, drivers/connectors, control-plane UI, and Lepton products — and governed reality. The seam is the only door: every interaction is one of six verbs, and no component reaches a store directly.

• Triggers: Subscribe (react to changes/streams), Schedule (time-trigger a job/workflow).
• Effects: Query (read through policy gates), Act (internal state transition/decision), Assert (record observation/evidence/claim), Call (external side-effect via the egress gateway).

→ Authoritative: The Seam (what the kernel is), Architecture Overview (namespace & verbs at a glance).

3. Major components & responsibilities

The kernel is organized as five planes and a set of kernel-owned ports (P0–P26) with swappable adapters:

Plane	Responsibility
Process	Actions, decisions, workflows, retries, call intents
Truth	Immutable logs, statements, schemas, policies, evidence
World	Resolved current interpretation of reality
Serving	Fast projections; truth of nothing
Materialization	Pipelines, jobs, transforms, indexes, rebuild machinery

Ports are the permanent contracts (storage & data planes, compute & execution, governance & identity, boundary, contract & SDK, runtime & delivery); adapters are the implementation choices resolved per profile.

→ Authoritative: Ports & Adapters (P0–P26 + the interface catalog), Low-Level Design (port-by-port depth, shared types, the five planes).

4. Key data flows

• Read path — Query resolves through policy/queryability gates into the Query IR, served from Serving projections with declared truth tiers, consistency, and offline reads.
• Write path — Act appends to the ordered log (Truth), which materializes into World (resolved current state) and Serving (projections); atomicity is idempotent replay, not distributed transactions.
• Ingest — Assert records observations/claims (statement-backed where opted in).
• Egress — Call performs external side-effects through the P16 egress gateway, credential injected at the crossing.

→ Authoritative: Data Plane (read side), LLD (five planes + walkthroughs), ADR-0013 (atomicity via idempotent replay).

5. Technology choices

Concrete adapters are resolved as three reference profiles — Lean (the honest first build: Postgres/PostGIS + MinIO + DuckDB + a custom Rust materializer), Scale (Jio-scale), and Air-gapped (self-hosted, offline verification). Rows (the ports) are permanent; columns (the adapters) move, graduating on measured evidence per port.

• First build & graduation discipline → ADR-0007.
• Greenfield kernel; legacy SmartInventory is a connector, not a base → ADR-0008.
• Deployment & environments — the deployment factory (sites pull governed packages; config, not forks) → ADR-0024.
• Error model & observability → ADR-0014.

→ Authoritative: Ports & Adapters §3 (the profile matrix).

6. High-level data model

Reality is modeled as an entity–trait–link ontology: entities carry traits (typed facets) and are connected by links; kinds and links are declared, not hard-coded. Series/time-series are traits with a declared temporality class. Statement-backing is tiered and opt-in.

• Kinds & links, the ontology depth → LLD (§20 kinds, §27 links).
• Temporality / series → ADR-0015.
• Statement-backing: opt-in ResolvedValue → ADR-0011; the sealed evidence tier → ADR-0023.
• Multi-tenancy & isolation — Tenant ⊃ Universe ⊃ Realm, physical Cell shards → ADR-0020.

7. Cross-cutting concerns

• Security & authorization — authority acquired at the seam as scoped capability tokens; agents authenticate via the MCP standard → ADR-0021.
• Credentials & secrets — a governed reference; the kernel is plaintext-blind → ADR-0018.
• Standards interop — TMF SID/Open-API conformance lives at the edge → ADR-0022.
• Automation triggers & scheduling — patterns over two verbs; poll for the push-less → ADR-0019.
• Surface (UI) platform — one interpreter over a Surface IR → Surface Platform.

8. Modules × network types (the product layer)

The ticket asks for an HLD “across all modules and network types (Oil & Gas / Telco/FTTx / Electrical).” That view is deliberately absent from the kernel: the kernel names zero domain types (ADR-0008). Modules (Planner / Inventory / Projects / Ops) and verticals (O&G / Telco / Electrical) are product-layer reality-package definitions composed on top of the kernel — data, not code branches (ADR-0020: forks→config). A given product selects the ontology kinds, workflows, surfaces, and profiles it needs; the same kernel serves every module × vertical without change.

→ Product home: Products → NetworkAccess (the kernel’s pilot). A NetworkAccess product HLD (the concrete module × vertical map) is a product-layer deliverable, tracked separately from this kernel HLD.

9. From HLD to LLD

This HLD fixes the shape; the Low-Level Design details it into implementable specifics — port internals, schemas, interface contracts, sequence walkthroughs, and error handling.