Visual architecture diagram showing how ObjectStack's protocol layers connect — Data, UI, System, Automation, AI, API, and Security

Protocol Relationship Diagram

ObjectStack is composed of seven protocol layers that work together to form a complete application platform. This page provides visual diagrams showing how these layers connect and how data flows through the system.

Architecture Principle: Each layer is defined as pure Zod schemas in packages/spec/src/. Layers communicate through well-defined contracts, never by direct coupling.

Layer Overview

Layer	Package Path	Purpose
Data (ObjectQL)	`src/data/`	Objects, Fields, Queries, Hooks, State Machines
UI (ObjectUI)	`src/ui/`	Views, Apps, Dashboards, Reports, Actions
System (ObjectOS)	`src/system/`	Manifest, Datasources, Plugins, Kernel
Automation	`src/automation/`	Flows, Workflows, Triggers, Approvals
AI	`src/ai/`	Agents, RAG Pipelines, Model Registry
API	`src/api/`	REST, GraphQL, WebSocket, Realtime
Security	`src/security/`	Permissions, Roles, Sharing, RLS

Protocol Relationship Map

The following diagram shows how each protocol layer references and depends on the others.

graph TB
    subgraph "Client Layer"
        CLIENT[Client App / SDK]
    end

    subgraph "API Layer"
        REST[REST Endpoints]
        GQL[GraphQL]
        WS[WebSocket / Realtime]
    end

    subgraph "Security Layer"
        PERM[Permissions]
        ROLES[Roles & Profiles]
        SHARING[Sharing Rules]
        RLS[Row-Level Security]
    end

    subgraph "UI Layer (ObjectUI)"
        APPS[Apps & Navigation]
        VIEWS[Views - List / Form]
        DASH[Dashboards]
        REPORTS[Reports]
        ACTIONS[Actions & Buttons]
    end

    subgraph "Automation Layer"
        FLOWS[Flows]
        WF[Workflows & Approvals]
        TRIGGERS[Triggers]
    end

    subgraph "AI Layer"
        AGENTS[Agents]
        RAG[RAG Pipelines]
        MODELS[Model Registry]
    end

    subgraph "System Layer (ObjectOS)"
        MANIFEST[Manifest]
        KERNEL[Kernel]
        PLUGINS[Plugins]
        DS[Datasources]
    end

    subgraph "Data Layer (ObjectQL)"
        OBJECTS[Objects]
        FIELDS[Fields]
        QUERIES[Queries]
        HOOKS[Hooks]
        SM[State Machines]
        DRIVERS[Drivers]
    end

    subgraph "Storage"
        DB[(Database)]
    end

    %% Client to API
    CLIENT --> REST
    CLIENT --> GQL
    CLIENT --> WS

    %% API references Data
    REST --> KERNEL
    GQL --> KERNEL
    WS --> KERNEL

    %% Security enforced at Kernel
    KERNEL --> PERM
    KERNEL --> RLS
    PERM --> ROLES
    PERM --> SHARING

    %% UI references Data objects
    VIEWS -->|"references"| OBJECTS
    DASH -->|"queries"| OBJECTS
    REPORTS -->|"aggregates"| OBJECTS
    ACTIONS -->|"operates on"| OBJECTS
    APPS -->|"contains"| VIEWS

    %% Automation operates on Data
    FLOWS -->|"reads/writes"| OBJECTS
    WF -->|"state transitions"| SM
    TRIGGERS -->|"watches"| HOOKS

    %% AI interacts with Data
    AGENTS -->|"queries"| OBJECTS
    RAG -->|"indexes"| FIELDS
    AGENTS -->|"uses"| MODELS

    %% System orchestrates everything
    MANIFEST -->|"declares"| OBJECTS
    MANIFEST -->|"declares"| VIEWS
    MANIFEST -->|"declares"| FLOWS
    KERNEL -->|"loads"| PLUGINS
    KERNEL -->|"connects"| DS

    %% Data to Storage
    QUERIES --> DRIVERS
    HOOKS -->|"intercepts"| QUERIES
    DRIVERS --> DB

Key Relationships:

UI → Data: Views, Dashboards, and Reports reference Objects and Fields by name.
Automation → Data: Flows read/write Objects; Workflows drive State Machines; Triggers fire on Hooks.
API → Kernel → Data: All API requests pass through the Kernel, which enforces Security before reaching Data.
AI → Data: Agents query Objects; RAG indexes Field content for retrieval.

Request Flow Diagram

This sequence diagram shows how a typical API request flows through the ObjectStack layers.

sequenceDiagram
    participant C as Client
    participant API as API Layer
    participant SEC as Security
    participant K as Kernel
    participant H as Hooks
    participant D as Driver
    participant DB as Database

    C->>API: HTTP Request (REST / GraphQL)
    API->>K: Parsed Operation

    K->>SEC: Check Permissions
    SEC-->>K: Allowed / Denied

    alt Permission Denied
        K-->>API: 403 Forbidden
        API-->>C: Error Response
    end

    K->>H: Before Hook (validate, transform)
    H-->>K: Modified Record

    K->>D: Execute Query
    D->>DB: SQL / NoSQL Operation
    DB-->>D: Raw Result
    D-->>K: Typed Result

    K->>H: After Hook (side effects)
    H-->>K: Final Result

    K->>SEC: Apply Row-Level Security (filter)
    SEC-->>K: Filtered Result

    K-->>API: Response Payload
    API-->>C: JSON Response

Write Flow Detail

The write path includes validation, hook execution, and security enforcement at multiple stages.

sequenceDiagram
    participant C as Client
    participant API as API Layer
    participant K as Kernel
    participant V as Validation
    participant BH as Before Hooks
    participant D as Driver
    participant AH as After Hooks
    participant T as Triggers
    participant WS as WebSocket

    C->>API: POST /api/v1/data/task
    API->>K: create(task, data)

    K->>V: Validate against ObjectSchema
    V-->>K: Validation Result

    alt Validation Failed
        K-->>API: 400 Validation Error
        API-->>C: Error Response
    end

    K->>BH: beforeCreate hooks
    BH-->>K: Transformed data

    K->>D: INSERT record
    D-->>K: Created record

    K->>AH: afterCreate hooks
    AH-->>K: Side effects complete

    K->>T: Fire triggers
    T-->>WS: Broadcast change event

    K-->>API: Created record
    API-->>C: 201 Created + JSON

Metadata Resolution Flow

How defineStack() configuration becomes runtime metadata available to the Kernel and IDE.

flowchart LR
    A["defineStack()"] -->|"compile"| B[Manifest]
    B -->|"register"| C[Schema Registry]
    C -->|"generate"| D[JSON Schema]
    D -->|"feed"| E[IDE Autocomplete]
    C -->|"load"| F[Kernel]
    F -->|"serve"| G[Metadata API]
    G -->|"discover"| H[Client SDK]

Stage	Description
`defineStack()`	Developer declares objects, fields, views in `objectstack.config.ts` (array or map format)
Manifest	Compiled configuration package with all metadata
Schema Registry	In-memory registry of all object and field definitions
JSON Schema	Generated JSON Schema files for IDE validation
Kernel	Runtime engine that serves data using registered schemas
Metadata API	`GET /api/v1/meta/objects` endpoint for client discovery

Layer Dependency Rules

These rules ensure clean architecture and prevent circular dependencies.

Rule	Description
Data is foundational	All other layers depend on Data; Data depends on nothing
UI is presentation-only	UI references Data objects by name but contains no business logic
Security is cross-cutting	Enforced at the Kernel level, transparent to other layers
Automation is reactive	Automation responds to Data events; it does not define data structures
AI is a consumer	AI reads from Data and Automation; it can trigger Flows but not bypass Security
API is a gateway	API exposes Kernel operations; it never accesses Drivers directly
System is the orchestrator	Manifest and Kernel wire all layers together at boot time

See also:

Data Flow Guide for detailed sequence diagrams
Kernel Services for runtime architecture
API Protocol for endpoint contracts

Protocol Relationship Diagram

Protocol Relationship Diagram

Layer Overview

Protocol Relationship Map

Request Flow Diagram

Write Flow Detail

Metadata Resolution Flow

Layer Dependency Rules

On this page