Lowdefy Monorepo Overview

A configuration-driven web framework built on Next.js. Write YAML, get React apps.

What Lowdefy Is

Lowdefy lets developers build web applications using YAML/JSON configuration instead of code. Users define:

Pages with layouts and UI components (blocks)
Connections to databases and APIs
Requests that query those connections
Actions triggered by user events
Operators for dynamic logic within config

The framework compiles this config into a Next.js application at build time.

Architecture at a Glance

┌─────────────────────────────────────────────────────────────────────┐
│                          User's YAML Config                          │
│    (lowdefy.yaml, pages/*.yaml, connections, requests, etc.)        │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         @lowdefy/build                               │
│  - Parses YAML/JSON                                                  │
│  - Validates against schema                                          │
│  - Resolves _ref imports                                             │
│  - Evaluates build-time operators                                    │
│  - Generates build artifacts                                         │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     Next.js Server (runtime)                         │
│  ┌─────────────────────┐    ┌────────────────────────────────────┐  │
│  │   @lowdefy/api      │    │         @lowdefy/client            │  │
│  │  - API routes       │    │  - React rendering                 │  │
│  │  - Request exec     │    │  - Block mounting                  │  │
│  │  - Connection mgmt  │    │  - Event handling                  │  │
│  │  - Auth context     │    │  - @lowdefy/engine (state)         │  │
│  └─────────────────────┘    │  - @lowdefy/layout (grid)          │  │
│                              └────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                          Browser / End User

Core Packages

Package	Role	Key Responsibility
lowdefy (cli)	Entry point	Commands: init, dev, build, start
@lowdefy/build	Compiler	YAML → build artifacts
@lowdefy/api	Server	API routes, request execution
@lowdefy/client	Client	React rendering, page context
@lowdefy/engine	Runtime	State management, actions
@lowdefy/layout	Layout	Grid system, block positioning
@lowdefy/operators	Logic	Operator parsing and evaluation

Plugin System

Lowdefy is extensible via npm packages. Everything the user sees or interacts with comes from plugins.

Plugin Types

Type	What It Does	Examples
Blocks	UI components	Button, TextInput, Table, Chart
Connections	Data source configs	MongoDB, PostgreSQL, REST API
Operators	Logic functions	`_if`, `_get`, `_sum`, `_date`
Actions	Event handlers	SetState, Request, Navigate
Agents	AI chat providers	Anthropic, OpenAI, Google, AI Gateway
Auth Providers	Authentication	Google, Auth0, Credentials

Default Plugins

These ship with Lowdefy and don't need explicit installation:

@lowdefy/blocks-antd - Primary UI components (Ant Design based)
@lowdefy/blocks-antd-x - AI chat components (AgentChat, AgentConversations)
@lowdefy/blocks-basic - HTML primitives
@lowdefy/operators-js - Core JavaScript operators
@lowdefy/actions-core - Standard actions
@lowdefy/connection-anthropic - Anthropic Claude models
@lowdefy/connection-openai - OpenAI GPT models
@lowdefy/connection-google - Google Gemini models
@lowdefy/connection-ai-gateway - Vercel AI Gateway (multi-provider routing)
@lowdefy/connection-mcp - MCP server connections

See Plugin System Architecture for internals.

Key Concepts

Build vs Runtime

Phase	When	What Happens
Build	`lowdefy build`	Config parsed, validated, compiled to artifacts
Runtime	User visits page	Artifacts loaded, operators evaluated, requests executed

This separation is why Lowdefy apps are fast - heavy YAML parsing happens once at deploy time.

Operators

Operators are functions prefixed with _ that make config dynamic:

yaml

# Static value
title: Welcome

# Dynamic value using operator
title:
  _if:
    test:
      _eq:
        - _state: user.role
        - admin
    then: Admin Dashboard
    else: User Dashboard

Operators can run at:

Build time (in @lowdefy/build) - for config composition
Runtime client (in @lowdefy/engine) - for UI reactivity
Runtime server (in @lowdefy/api) - for request logic

State Management

Each page has isolated state managed by @lowdefy/engine:

state - Form values and user input
urlQuery - URL query parameters
input - Data passed when navigating to page
_request - Cached request responses
_global - Shared across pages (sparingly used)

Agents

Agents add AI chat capabilities to Lowdefy apps. Defined as a top-level agents: config key, they follow the same type + connectionId + properties pattern as requests. Agents reference connections for AI provider credentials, use API endpoints as tools, and stream responses to the AgentChat block.

See Agent System Architecture for the complete data flow.

Requests

Requests are server-side data operations:

Client triggers request via action
@lowdefy/client sends to API route
@lowdefy/api executes against connection
Response returned and cached in state

Server Variants

Server	Use Case
`server`	Production Next.js server for deployments
`server-dev`	Local development server with hot reload

File Structure

lowdefy/
├── packages/
│   ├── api/              # Server-side API
│   ├── build/            # Config compiler
│   ├── cli/              # CLI tool
│   ├── client/           # React client
│   ├── engine/           # State management
│   ├── layout/           # Grid layout
│   ├── operators/        # Operator framework
│   ├── plugins/          # Plugin packages
│   │   ├── actions/
│   │   ├── blocks/
│   │   ├── connections/
│   │   ├── operators/
│   │   └── plugins/
│   ├── servers/          # Server implementations
│   └── utils/            # Shared utilities
├── packages/docs/        # docs.lowdefy.com content
└── packages/website/     # lowdefy.com content

Where to Go Next

Architecture Deep Dives

Agent System - AI agent orchestration, tools, and streaming
Build Pipeline - How YAML becomes a Next.js app
Request Lifecycle - Data flow from action to database
State Management - Page state and reactivity
Plugin System - How plugins are loaded and registered
Auth System - Authentication integration
Operator System - Operator evaluation at build/runtime

Plugin Documentation

Blocks - UI components (Ant Design, AG Grid, Charts)
Connections - Data sources (MongoDB, SQL, REST)
Operators - Logic functions (JS, MQL, Moment)
Actions - Event handlers (Core, PDF)
Plugins - Auth and utilities (NextAuth, AWS, CSV)

Servers

Servers Overview - Next.js server architecture
Production Server - Deployment server
Development Server - Hot reload and file watching

Utilities

Utils Overview - Shared utility packages
Helpers - Core helper functions (get, set, type)
Block Utils - CSS generation, error boundaries

Core Packages

CLI - Command line interface
Build - Configuration compiler
API - Server-side API
Client - React rendering
Engine - State management
Layout - Grid system
Operators - Operator framework