Architecture Overview

Lombok is best understood as a self-hosted storage and compute platform built from several cooperating runtime layers.

The “planes” used on this page are an editorial mental model for understanding the codebase, not a source term used by Lombok itself.

At a high level, Lombok combines:

a control plane for API, identity, tasks, and platform logic
a storage plane for S3-compatible object storage
a compute plane for worker execution and app runtime behavior
a presentation plane for the main web UI and embedded app UIs

The four planes

Control plane

The control plane is centered on the NestJS API in packages/api.

It is responsible for platform concerns such as:

authentication and users
folders and object metadata
app installation and app configuration
event handling
task orchestration
storage configuration
Docker integration
Socket.io gateways and realtime updates
comments, search, notifications, and MCP support

Storage plane

The storage plane is built around S3-compatible storage backends.

Lombok separates:

platform/application state stored in PostgreSQL
object data stored in S3-compatible storage

That split is one of the core ideas behind the platform architecture.

Compute plane

The compute plane is centered on Lombok’s worker runtime.

The primary execution path is:

app tasks resolving to runtime workers
runtime workers executing through the core worker runtime
worker execution happening in a sandboxed worker environment

Lombok also supports Docker-backed handler paths, but those are a distinct secondary execution mode rather than the default mental model for app execution.

Presentation plane

The presentation plane includes:

the main React web UI in packages/ui
embedded app UIs
browser-side SDKs and UI integrations

This is the layer users and app developers interact with most directly.

Simplified architecture map

Main UI / Embedded App UI
            ↓
        NestJS API
      ┌─────┼─────┐
      │     │     │
 PostgreSQL S3   Worker runtime
      │   storage     │
      └─────┴─────────┘
            ↓
   tasks, events, app execution

What makes Lombok architecturally distinct

Lombok is not only:

a file browser
a self-hosted sync app
a dashboard for S3

It is also an application platform.

That means the architecture has to support:

storage operations
event emission
task routing
worker execution
embedded app user interfaces
app-specific settings and contributions

Main codebase mapping

The most important packages for understanding Lombok are:

packages/api — control-plane backend
packages/ui — main web frontend
packages/core-worker — worker runtime
packages/types — shared contracts and types
packages/sdk — typed client SDK generated around the platform API surface
packages/app-worker-sdk — app worker SDK
packages/app-browser-sdk — browser SDK for embedded app UIs
packages/ui-toolkit — reusable UI component system
packages/worker-utils — worker-focused utilities, especially for media/file processing

Next steps

If you want a more codebase-oriented view next, continue to: