# external-mirrors/phoenix architecture

> Architecture diagram of the GitHub repository external-mirrors/phoenix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/external-mirrors/phoenix
- Repository: https://github.com/external-mirrors/phoenix

## Overview

1. **What this repo is**
   Phoenix is an X server written in Zig. The architecture is split between an X11 protocol engine and a host-platform backend layer. The current operational target is nested execution inside an existing X server, with the backend abstraction already prepared for other display/input/graphics implementations later.

2. **Process entry and top-level orchestration**
   `src/main.zig` and `src/phoenix.zig` are the likely bootstrap points that assemble the server, choose backends, initialize protocol state, and enter the main event loop. This is the process boundary where client connections, backend events, and rendering work are coordinated.

3. **Backend boundary: display, input, graphics**
   `src/backend/display`, `src/backend/input`, and `src/backend/graphics` form the host integration layer. The abstract interfaces in `Display.zig`, `Input.zig`, and `Graphics.zig` separate Phoenix’s internal X11 state from platform-specific implementations such as `DisplayX11.zig`, `InputLinux.zig`, and `GraphicsEgl.zig`. This is the main portability seam in the design.

4. **Current host integration mode**
   The repo is explicitly built for nested operation first. `DisplayX11.zig` suggests the server can create and manage its visible surface through an existing X server, while `GraphicsEgl.zig` provides hardware-accelerated rendering. The README also indicates future backends may target DRM/GBM or Wayland, but those are not the current primary path.

5. **Client transport and server I/O**
   `src/net` contains the client/server communication plumbing: `Server.zig`, `Client.zig`, `message.zig`, `fifo.zig`, and `utils.zig`. This layer is responsible for accepting connections, buffering request/reply/event traffic, and framing protocol messages before they reach the protocol dispatcher.

6. **X11 protocol parsing and dispatch**
   `src/protocol` is the core protocol engine. It is organized into `request.zig`, `reply.zig`, `event.zig`, `error.zig`, and `opcode.zig`, with handlers under `src/protocol/handlers`. The handler split shows a clear boundary between connection setup, per-request context, core protocol handling, and extension-specific logic.

7. **Extension-centric protocol architecture**
   The extension handlers are first-class modules: `Dri3`, `Glx`, `Present`, `Randr`, `Render`, `MitShm`, `Sync`, `Xfixes`, `Xkb`, `Xwayland`, and `GenericEvent`. This indicates Phoenix is organized around the modern X11 feature set needed by real applications, rather than trying to implement the entire historical protocol surface.

8. **Server object model**
   `src/resource` contains the server-owned X11 objects: `Window`, `Pixmap`, `Drawable`, `Cursor`, `Colormap`, `Counter`, `Fence`, `ShmSegment`, `EventContext`, `GlxContext`, `GlxDrawable`, and the common base in `resource.zig`. These are the authoritative objects that protocol requests operate on, and they are the main units of state passed between protocol handlers and the backend.

9. **Global managers and ownership rules**
   `src/manager` centralizes cross-cutting server state: `ClientManager`, `AtomManager`, `ResourceIdBaseManager`, and `SelectionOwnerManager`. These modules likely enforce per-client resource ownership, ID allocation, atom interning, and selection ownership, which are key boundaries for connection isolation and security policy.

10. **Display model and monitor-facing state**
   `src/display` contains monitor and screen-related structures such as `Crtc.zig` and `ScreenResources.zig`. Together with `src/internal_resource/Visual.zig` and `Atom.zig`, this is where backend-derived output information becomes X11-visible state such as visuals, monitor resources, and per-screen metadata.

11. **Input and keyboard flow**
   `src/backend/input/InputLinux.zig` is the host input source, while `src/keyboard/keysym.zig` and `src/misc/InputFocus.zig` represent how host key events are translated into X11 key symbols and routed to the focused client. The `Xkb` protocol extension ties this into keyboard layout and keymap handling.

12. **Support utilities and shared types**
   `src/misc` provides the shared building blocks used across the server: geometry, fixed-point math, time, versioning, refcounting, and pattern helpers. These are the low-level types that keep protocol, resource, and backend code aligned on common representations.

13. **Where rendering meets protocol**
   Rendering-related extensions and resources form a second major data path: clients submit drawable/GL/SHM-related operations through protocol handlers, those operations map onto `Pixmap`, `Drawable`, `GlxContext`, `GlxDrawable`, `Fence`, and `Present` state, and the backend graphics layer presents the results to the host display. This is the path that enables the current “simple applications with hardware acceleration” goal.

14. **External dependencies that matter to the architecture**
   The design is explicitly tied to Zig and to modern graphics/input stacks: X11 client compatibility, EGL/OpenGL for acceleration, and libxkbcommon for keyboard handling. The backend abstraction exists so the server can later target DRM/GBM or other host display systems without rewriting the protocol or resource layers.

Main entry points: [`src/phoenix.zig`](https://github.com/external-mirrors/phoenix/blob/master/src/phoenix.zig) (Phoenix), [`src/protocol/handlers`](https://github.com/external-mirrors/phoenix/tree/master/src/protocol/handlers) (Handlers), [`src/resource/resource.zig`](https://github.com/external-mirrors/phoenix/blob/master/src/resource/resource.zig) (Resources), [`src/misc`](https://github.com/external-mirrors/phoenix/tree/master/src/misc) (Shared Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.zig]"]
  node_phoenix["Phoenix<br/>orchestrator<br/>[phoenix.zig]"]
  node_server["Server<br/>[Server.zig]"]
  node_client["Client<br/>connection<br/>[Client.zig]"]
end

subgraph group_grp_backend["Backend"]
  node_display_iface["Display API<br/>backend iface<br/>[Display.zig]"]
  node_display_x11["X11 Display<br/>nested display<br/>[DisplayX11.zig]"]
  node_input_iface["Input API<br/>backend iface<br/>[Input.zig]"]
  node_input_linux["Linux Input<br/>host input<br/>[InputLinux.zig]"]
  node_graphics_iface["Graphics API<br/>backend iface<br/>[Graphics.zig]"]
  node_graphics_egl["EGL Graphics<br/>accelerated graphics<br/>[GraphicsEgl.zig]"]
end

subgraph group_grp_protocol["Protocol"]
  node_request["Request<br/>protocol codec<br/>[request.zig]"]
  node_reply["Reply<br/>protocol codec<br/>[reply.zig]"]
  node_event["Event<br/>protocol codec<br/>[event.zig]"]
  node_handlers["Handlers<br/>dispatcher"]
  node_extensions["Extensions"]
end

subgraph group_grp_state["State"]
  node_resource[("Resources<br/>x11 objects<br/>[resource.zig]")]
  node_managers["Managers<br/>global state"]
  node_display_state["Display State<br/>screen model"]
  node_internal_resource["Internal Types<br/>shared x11 types"]
end

subgraph group_grp_support["Support"]
  node_misc["Shared Utils<br/>common types"]
end

node_main -->|"start"| node_phoenix
node_phoenix -->|"serve"| node_server
node_phoenix -->|"select"| node_display_iface
node_phoenix -->|"select"| node_input_iface
node_phoenix -->|"select"| node_graphics_iface
node_display_iface -->|"impl"| node_display_x11
node_input_iface -->|"impl"| node_input_linux
node_graphics_iface -->|"impl"| node_graphics_egl
node_server -->|"accept"| node_client
node_server -->|"parse"| node_request
node_request -->|"dispatch"| node_handlers
node_handlers -->|"respond"| node_reply
node_handlers -->|"emit"| node_event
node_handlers -->|"route"| node_extensions
node_extensions -->|"mutate"| node_resource
node_managers -->|"own"| node_resource
node_display_state -->|"expose"| node_resource
node_internal_resource -->|"feed"| node_display_state
node_misc -.->|"support"| node_request
node_misc -.->|"support"| node_resource
node_misc -.->|"support"| node_graphics_egl
node_input_linux -->|"keysym"| node_internal_resource

click node_main "https://github.com/external-mirrors/phoenix/blob/master/src/main.zig"
click node_phoenix "https://github.com/external-mirrors/phoenix/blob/master/src/phoenix.zig"
click node_server "https://github.com/external-mirrors/phoenix/blob/master/src/net/Server.zig"
click node_client "https://github.com/external-mirrors/phoenix/blob/master/src/net/Client.zig"
click node_display_iface "https://github.com/external-mirrors/phoenix/blob/master/src/backend/display/Display.zig"
click node_display_x11 "https://github.com/external-mirrors/phoenix/blob/master/src/backend/display/DisplayX11.zig"
click node_input_iface "https://github.com/external-mirrors/phoenix/blob/master/src/backend/input/Input.zig"
click node_input_linux "https://github.com/external-mirrors/phoenix/blob/master/src/backend/input/InputLinux.zig"
click node_graphics_iface "https://github.com/external-mirrors/phoenix/blob/master/src/backend/graphics/Graphics.zig"
click node_graphics_egl "https://github.com/external-mirrors/phoenix/blob/master/src/backend/graphics/GraphicsEgl.zig"
click node_request "https://github.com/external-mirrors/phoenix/blob/master/src/protocol/request.zig"
click node_reply "https://github.com/external-mirrors/phoenix/blob/master/src/protocol/reply.zig"
click node_event "https://github.com/external-mirrors/phoenix/blob/master/src/protocol/event.zig"
click node_handlers "https://github.com/external-mirrors/phoenix/tree/master/src/protocol/handlers"
click node_extensions "https://github.com/external-mirrors/phoenix/tree/master/src/protocol/handlers/extension"
click node_resource "https://github.com/external-mirrors/phoenix/blob/master/src/resource/resource.zig"
click node_managers "https://github.com/external-mirrors/phoenix/tree/master/src/manager"
click node_display_state "https://github.com/external-mirrors/phoenix/blob/master/src/display/ScreenResources.zig"
click node_internal_resource "https://github.com/external-mirrors/phoenix/tree/master/src/internal_resource"
click node_misc "https://github.com/external-mirrors/phoenix/tree/master/src/misc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_phoenix,node_server,node_client toneBlue
class node_display_iface,node_display_x11,node_input_iface,node_input_linux,node_graphics_iface,node_graphics_egl toneAmber
class node_request,node_reply,node_event,node_handlers,node_extensions toneMint
class node_resource,node_managers,node_display_state,node_internal_resource toneRose
class node_misc toneIndigo
```

## Components

### Runtime

Process entry and top-level orchestration.

- [Main](https://github.com/external-mirrors/phoenix/blob/master/src/main.zig): entrypoint · Bootstraps the server process and enters the event loop. · `src/main.zig`
- [Phoenix](https://github.com/external-mirrors/phoenix/blob/master/src/phoenix.zig): orchestrator · Assembles subsystems and coordinates server execution. · `src/phoenix.zig`
- [Server](https://github.com/external-mirrors/phoenix/blob/master/src/net/Server.zig): network server · Owns client acceptance and request/reply transport. · `src/net/Server.zig`
- [Client](https://github.com/external-mirrors/phoenix/blob/master/src/net/Client.zig): connection · Represents a connected X11 client and its I/O state. · `src/net/Client.zig`

### Backend

Host display, input, and graphics integration.

- [Display API](https://github.com/external-mirrors/phoenix/blob/master/src/backend/display/Display.zig): backend iface · Abstract display boundary for host integration. · `src/backend/display/Display.zig`
- [X11 Display](https://github.com/external-mirrors/phoenix/blob/master/src/backend/display/DisplayX11.zig): nested display · Display backend for running inside an existing X server. · `src/backend/display/DisplayX11.zig`
- [Input API](https://github.com/external-mirrors/phoenix/blob/master/src/backend/input/Input.zig): backend iface · Abstract input boundary for host event sources. · `src/backend/input/Input.zig`
- [Linux Input](https://github.com/external-mirrors/phoenix/blob/master/src/backend/input/InputLinux.zig): host input · Host keyboard and pointer input implementation. · `src/backend/input/InputLinux.zig`
- [Graphics API](https://github.com/external-mirrors/phoenix/blob/master/src/backend/graphics/Graphics.zig): backend iface · Abstract rendering boundary for host graphics. · `src/backend/graphics/Graphics.zig`
- [EGL Graphics](https://github.com/external-mirrors/phoenix/blob/master/src/backend/graphics/GraphicsEgl.zig): accelerated graphics · EGL-based rendering backend for host presentation. · `src/backend/graphics/GraphicsEgl.zig`

### Protocol

X11 parsing, dispatch, and extensions.

- [Request](https://github.com/external-mirrors/phoenix/blob/master/src/protocol/request.zig): protocol codec · Parses incoming X11 requests into typed operations. · `src/protocol/request.zig`
- [Reply](https://github.com/external-mirrors/phoenix/blob/master/src/protocol/reply.zig): protocol codec · Builds X11 replies sent back to clients. · `src/protocol/reply.zig`
- [Event](https://github.com/external-mirrors/phoenix/blob/master/src/protocol/event.zig): protocol codec · Encodes server events for client delivery. · `src/protocol/event.zig`
- [Handlers](https://github.com/external-mirrors/phoenix/tree/master/src/protocol/handlers): dispatcher · Routes setup, core, and extension requests to implementations. · `src/protocol/handlers`
- [Extensions](https://github.com/external-mirrors/phoenix/tree/master/src/protocol/handlers/extension): protocol extensions · Feature modules for modern X11 and Xwayland support. · `src/protocol/handlers/extension`

### State

Server-owned objects and global managers.

- [Resources](https://github.com/external-mirrors/phoenix/blob/master/src/resource/resource.zig): x11 objects · Authoritative server-side X11 resource model. · `src/resource/resource.zig`
- [Managers](https://github.com/external-mirrors/phoenix/tree/master/src/manager): global state · Cross-cutting ownership, atoms, and resource ID policy. · `src/manager`
- [Display State](https://github.com/external-mirrors/phoenix/blob/master/src/display/ScreenResources.zig): screen model · Monitor, screen, and visual information exposed to X11. · `src/display/ScreenResources.zig`
- [Internal Types](https://github.com/external-mirrors/phoenix/tree/master/src/internal_resource): shared x11 types · Shared visual and atom definitions used across the server. · `src/internal_resource`

### Support

Shared utilities and low-level types.

- [Shared Utils](https://github.com/external-mirrors/phoenix/tree/master/src/misc): common types · Geometry, time, versioning, fixed-point, and refcount helpers. · `src/misc`

## Connections

- Main → Phoenix: start · Process bootstrap hands off to the server orchestrator.
- Phoenix → Server: serve · Orchestrator creates the client transport layer.
- Phoenix → Display API: select · Chooses the display backend abstraction.
- Phoenix → Input API: select · Chooses the input backend abstraction.
- Phoenix → Graphics API: select · Chooses the graphics backend abstraction.
- Display API → X11 Display: impl · Nested X11 display implementation.
- Input API → Linux Input: impl · Linux host input implementation.
- Graphics API → EGL Graphics: impl · EGL rendering implementation.
- Server → Client: accept · Server creates and manages client connections.
- Server → Request: parse · Incoming client traffic is decoded as requests.
- Request → Handlers: dispatch · Parsed requests are routed to protocol handlers.
- Handlers → Reply: respond · Handlers build replies for clients.
- Handlers → Event: emit · Handlers emit events to connected clients.
- Handlers → Extensions: route · Extension-specific operations are handled separately.
- Extensions → Resources: mutate · Extensions operate on server-owned X11 objects.
- Managers → Resources: own · Managers enforce identity, ownership, and allocation rules.
- Display State → Resources: expose · Screen and visual state is derived from resources and backend output.
- Internal Types → Display State: feed · Internal atoms and visuals support display-visible state.
- Shared Utils → Request: support · Shared low-level types support protocol decoding.
- Shared Utils → Resources: support · Common utilities support server object implementations.
- Shared Utils → EGL Graphics: support · Shared math and time types support backend rendering.
- Linux Input → Internal Types: keysym · Host input is translated into X11 keyboard symbols.
