Document Type: Architecture Specification

Context: Machine Interface Layer · API Engineering

Status: Public Standard

Validity: Aivis-OS Core Pipeline

Reference: Consumes Semantic Graph Engineering and exclusively exposes the Canonical Graph State.

1. Architectural Principle

The Website as an API

In the Aivis-OS architecture, the visual website (HTML for humans) is just one of several possible representations of organizational truth.

The Machine Interface Layer (MIL) primarily treats the domain as a public, read-only API for AI systems, crawlers, and retrieval pipelines.

The visual representation is secondary to the machine-readable exposure.

2nd Principle: Projection instead of Storage

The Machine Interface Layer stores no data of its own.

It projects data.

Specifically:

The MIL consumes the Canonical Graph State from the Semantic Graph Layer.
It serializes this state into standardized, machine-readable formats.
It creates no new truth, but a deterministic representation of existing truth.

Principle:
There must be no discrepancy between the visual statement (Human Interface) and the machine projection (Data Parity).

3. Technical Projection Rules

3.1 Strict Schema Compliance

Aivis-OS does not generate free-form projections.

Each projection must follow a recognized public vocabulary, primarily Schema.org.

Type safety (mandatory):

The typing defined in the graph is mandatory.
An entity must not be reduced to a more generic type in the projection to avoid complexity.

Example:

MedicalClinic must not be exposed as Organization.

3.2 ID Persistence

All defined in the Entity Inventory entity_ids must be persistently as @id exposed.

Goal:

Re-identifiability across crawls
Stability over time
Graph reconstruction by external systems

Forbidden:

volatile Blank Nodes
dynamically generated IDs for core entities

3.3 Scoped Serialization (Context Window Management)

The Semantic Graph can be extensive, but individual URLs cannot.

The Machine Interface Layer therefore projects in a contextually limited manner.

Standard strategy: Focus Node + 1 Hop

The URL defines a Focus Node.
All direct attributes of the Focus Node are projected.
Linked entities are referenced, not fully embedded.

Goal:

Avoidance of Token Bloat
Preservation of semantic clarity
Deterministic context boundaries

4. Implementation Standard: JSON-LD

Aivis-OS standardizes on JSON-LD as the primary exchange format, as it is natively supported by common ingestion and retrieval pipelines.

4.1 Syntax Isolation

Structured data is not mixed with visual markup.

Specification:

JSON-LD is delivered exclusively in isolated
<script type="application/ld+json"> blocks.
Placement preferred in <head>.

Microdata in the HTML body is not part of the Aivis-OS architecture.

4.2 Graph Object Pattern

Aivis-OS outputs structured data as a coherent @graph object.

Multiple isolated JSON-LD fragments are not permitted.

Goal:

explicit relationship encoding
no implicit assumptions by parser
complete reconstructability of the context

5. Interface Stability (Contract)

Since the website functions as an API, API-like stability rules apply.

5.1 No Silent Removal

Removing an entity or field from the projection without explicit labeling is not permitted.

Permitted Alternatives:

HTTP status signaling (404 / 410)
explicit marking (e.g. status: dissolved)

5.2 Format Fidelity

A data format once established must be kept stable.

Examples:

ISO-8601 date formats must not switch to free text.
Numerical values must not suddenly be output as strings.

6. Validation & Testing

The Machine Interface Layer is not checked against human readability, but against machine reliability.

Validation Pipeline

Syntactic Check
JSON is valid.
Schema Check
Schema.org compliance and relevant validators pass.
Parity Check
The projected values match the content extracted in the Transport-Safe Content Layer.

Deviation:
→ Cloaking suspicion
→ Trust devaluation

7. Summary

The Machine Interface Layer is the deterministic translation instance between the internal complexity of the Semantic Graph Layers and the limited absorption capacity of external AI systems.

It stores no data, interprets no meaning, and exclusively exposes canonical states. In doing so, it ensures that internal truth is transported externally in a standard-compliant, stable, and interpretation-free manner.

Architecture Overview

All Aivis-OS Core Architecture

Cluster-Level Entity Inventory Strategy

Context & Meaning Semantic Graph Engineering

Semantic Graph Layer

Semantic Graph Engineering