> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer overview

> How the Otter Shell monorepo is laid out and how components connect.

Otter Shell is a Wayland desktop in Zig. Apps share the same libraries for rendering, Wayland, config, and desktop services.

## Repository structure

The [otter-shell](https://git.pika-os.com/otter-shell) organization has **one git repo per component**. The monorepo folder on disk is a checkout layout, not one repo. Commit and push **per component**.

| Repository                                     | Type                                  |
| ---------------------------------------------- | ------------------------------------- |
| `otter-bar`, `otter-launcher`, `otter-term`, … | Applications                          |
| `otter-ui`, `otter-render`, `otter-wayland`, … | Shared libraries                      |
| `otter-zenith`                                 | Debian packaging and release assembly |

[otter-zenith](https://git.pika-os.com/otter-shell/otter-zenith) clones tagged component releases and builds `.deb` packages for PikaOS.

## Architecture

```
┌─────────────────────────────────────────────┐
│  Applications (otter-bar, otter-launcher,   │
│  otter-term, otter-settings, …)             │
├─────────────────────────────────────────────┤
│  otter-ui (Surface Description, widgets)    │
├──────────┬──────────┬──────────┬────────────┤
│ otter-   │ otter-   │ otter-   │ otter-     │
│ render   │ wayland  │ desktop  │ theme      │
├──────────┴──────────┴──────────┴────────────┤
│  otter-conf, otter-config-types,           │
│  otter-tools-core, otter-vte,              │
│  otter-geo, otter-utils                    │
└─────────────────────────────────────────────┘
```

UI apps share one rendering path:

1. Describe layout with **otter-ui** Surface Description nodes
2. Emit draw commands into a **CommandList** (otter-render)
3. Rasterize with **quad\_renderer** to Wayland SHM buffers (otter-wayland)

## Requirements

* **Zig 0.16.0**: required by all Otter packages
* System dev libraries: `libwayland-dev`, `libfontconfig-dev`, `libfreetype-dev`, `libxkbcommon-dev`
* Optional: `libpam0g-dev` (lock/greeter), `libghostty-vt-dev-git` (terminal), FFmpeg dev (recorder)
* A wlroots-based compositor with `zwlr_layer_shell_v1` for most UI apps

## Config convention

Apps read `~/.config/otter-shell/<app>.conf`. Shared styling is in `~/.config/otter-shell/theme.conf`. See [Configuration overview](/configuration/overview).

## Workspace-only components

In the source tree but **not packaged** in `otter-shell` or `otter-shell-extras`:

* `otter-dock`: application dock with magnification
* `otter-hypr`: Hyprland layout and titlebar companion

Otter Assistant packages (`otter-assist`, `otter-assistant`, `otter-assist-data`) ship in `otter-shell-extras`.

## Next steps

* [Building from source](/developers/building): compile any component locally
* [Creating an app](/developers/creating-an-app): start a new app with Otter libraries
* [Libraries overview](/developers/libraries): stack diagram and compile flags
* Individual library pages under **Libraries** in the sidebar