Repository Conventions

Lombok is a Bun workspace monorepo.

It is not organized as a single application with one src/ directory. Instead, it is split into packages and support directories that follow Lombok’s runtime boundaries and responsibilities.

This page gives contributors a practical map of the repository so you can quickly answer questions like:

where does this kind of code live?
which package should I inspect first?
what top-level directories matter for development and release work?

Top-level structure

At a high level, the main repository includes:

root workspace configuration and scripts
packages/ for application and runtime packages
docker/ and compose files for development and deployment
deploy/ for release and build scripts
cmd/ and dx for developer workflows

Why Lombok uses a monorepo

Lombok spans multiple concerns that need to evolve together:

backend APIs
web frontend
worker runtime
app platform SDKs
shared contracts and utilities
deployment and release tooling

A monorepo makes it easier to:

share types across runtime boundaries
keep frontend and backend contracts aligned
evolve the app platform together with the core product
run development and validation workflows consistently

Main runtime packages

The most important runtime split to remember is:

API in packages/api
UI in packages/ui
worker runtime in packages/core-worker

If you know those three anchors, most of the repository becomes easier to navigate.

Important supporting packages

The inspected docs reference additional packages including:

packages/types
packages/utils
packages/auth-utils
packages/sdk
packages/app-worker-sdk
packages/app-browser-sdk
packages/ui-toolkit
packages/worker-utils
packages/demo-apps

These packages support shared contracts, SDK surfaces, UI systems, worker helpers, and example app-platform implementations.

Practical routing guide

When deciding where to look first:

backend logic, auth, storage, tasks, sockets, and platform services → packages/api
frontend routes, authenticated shells, and app UI rendering → packages/ui
worker execution and background processing → packages/core-worker
shared contracts and schemas → packages/types
typed platform client surface → packages/sdk
app extension surfaces → packages/app-worker-sdk and packages/app-browser-sdk
reusable UI building blocks → packages/ui-toolkit

Tooling conventions

The repository is supported by:

./dx for common development operations
Docker-based local development
shared linting, formatting, and type-check workflows
root-level workspace configuration

As a contributor, ./dx is the main entrypoint for common tasks. For the full local loop, see Local Development with dx.

Deployment and release areas

Not all important repository areas live under packages/.

The inspected docs also point to:

docker/ and compose files for development and deployment shapes
deploy/ for release and image-build scripts
cmd/ and dx for workflow automation

Those directories matter when you are working on operations, release flow, or environment setup rather than application code alone.

How to use this page

Use this page as a navigation aid, not as a package-by-package API reference.

If you are:

setting up your environment → start with Local Development with dx
trying to understand system boundaries → read Runtime Boundaries
trying to understand package responsibilities in more detail → read Package Map
working on app-platform features → read App Platform Overview

Important correction

Older docs sometimes described Lombok like a conventional single-app repository.

That mental model is misleading.

The inspected codebase documentation consistently points to a runtime-oriented monorepo with separate API, UI, worker, SDK, and deployment concerns. Contributors should use that mental model when deciding where to make changes.