104 lines
6.1 KiB
Markdown
104 lines
6.1 KiB
Markdown
# Greenfield Architecture Analysis — for an Odoo 20 + JS/Python Wayland-to-HTML Compositor
|
|
|
|
> **Purpose of this bundle.** A deep, source-level architectural analysis of the
|
|
> Greenfield repository (https://github.com/udevbe/greenfield, commit `6c578f4`,
|
|
> `1.0.0-rc1`) written specifically for an engineering team that is about to build
|
|
> its own Wayland-to-HTML compositor. The target stack is **JavaScript (browser) +
|
|
> Python (host) + Odoo 20 addon shell**. Greenfield is treated purely as a
|
|
> reference implementation; the actual Greenfield UI shell (`packages/compositor-shell`)
|
|
> is **explicitly out of scope** — the user will supply their own Odoo 20 OWL shell.
|
|
|
|
## How to read this bundle
|
|
|
|
The bundle is split into 13 Markdown files. They are designed to be read in
|
|
order, but each file is self-contained and can be read alone if you only need
|
|
one layer. Files are organized from the highest-level view down to the
|
|
implementation-level details, then the porting blueprint, then pitfalls.
|
|
|
|
| # | File | What you'll find inside |
|
|
|---|------|-------------------------|
|
|
| 0 | `00-overview.md` | What Greenfield is, repo layout, package inventory, tech stack table, ASCII architecture diagram. |
|
|
| 1 | `01-architecture.md` | Layer-by-layer map from Wayland XML → generators → runtime → transport → rendering. |
|
|
| 2 | `02-wayland-protocol.md` | Protocol layer: 3 generators, wire format, object lifecycle, FD transport, custom `web-bitmapbuf` extension. |
|
|
| 3 | `03-html5-rendering.md` | Surface → canvas compositing pipeline: Surface state, damage, FrameLoop, WebGL shaders, multi-output. |
|
|
| 4 | `04-transport.md` | WebSocket + KCP-over-WebSocket, multi-channel design, message formats, FD virtualization, reconnection. |
|
|
| 5 | `05-input-handling.md` | Keyboard / pointer / touch / focus, xkbcommon WASM, keymap FD workaround, DOM → Wayland event mapping. |
|
|
| 6 | `06-data-clipboard.md` | `wl_data_device`, selection, drag-and-drop, MIME negotiation, XWayland bridge, primary-selection gap. |
|
|
| 7 | `07-native-app-bridge.md` | How real Linux apps get launched, the 3 native Node addons, XWayland bridge, app lifecycle & kill timers. |
|
|
| 8 | `08-app-lifecycle.md` | xdg-shell state machine, configure/ack round-trips, popup positioner math, subsurface sync, `UserShellApi`. |
|
|
| 9 | `09-hardware-accel.md` | GStreamer H.264 encoders, WASM FFmpeg fallback, WebCodecs preferred path, WebGL texture upload, alpha split. |
|
|
| 10 | `10-porting-to-odoo-js-python.md` | Concrete blueprint for porting each Greenfield layer to **JS browser compositor + Python host proxy + Odoo 20 OWL shell**. |
|
|
| 11 | `11-pitfalls.md` | 21 catalogued pitfalls + 12 design wins, with file references and what-to-do-instead for each. |
|
|
| 12 | `12-appendix.md` | Glossary, file-to-feature index, external references. |
|
|
|
|
## Recommended reading order
|
|
|
|
- **Architects / tech leads** — read `00` → `01` → `11` → `10`. You'll get the
|
|
lay of the land, what to copy, what to avoid, and the porting blueprint.
|
|
- **Browser-compositor engineers** — read `02` → `03` → `04` → `05` → `08` →
|
|
`09`. The core engine chapters, in dependency order.
|
|
- **Host-proxy engineers (Python)** — read `07` → `04` → `09` → `02` (proxy
|
|
generator section) → `10`. Most of the porting work is on your side.
|
|
- **Odoo 20 OWL shell engineers** — read `08` (especially the `UserShellApi`
|
|
section) → `01` → `10` (Odoo integration section). The shell is the
|
|
integration seam where Greenfield stops and your work begins.
|
|
- **Skip-it sections** — `06` (clipboard) is only needed if you care about
|
|
clipboard sync between browser and native apps.
|
|
|
|
## Scope & exclusions
|
|
|
|
**In scope** — every Greenfield package, lib, generator, native addon,
|
|
protocol file, transport channel, rendering path, encoding pipeline, and
|
|
the `UserShellApi` integration seam.
|
|
|
|
**Out of scope** — the actual `packages/compositor-shell` Preact+Tailwind
|
|
SPA. The user is building their own shell as an Odoo 20 addon. We only
|
|
describe the protocol-level integration point (`UserShellApi`) so the
|
|
Odoo shell knows what to consume.
|
|
|
|
**Not covered in depth** — the `sdk/` (Emscripten-based WASM app SDK for
|
|
browser-resident Wayland apps). Mentioned in `00-overview.md` and
|
|
`10-porting-to-odoo-js-python.md` but not analyzed layer-by-layer,
|
|
because the user's goal is running **real Linux apps** in the browser,
|
|
not browser-resident WASM apps.
|
|
|
|
## Conventions
|
|
|
|
- **File paths** are always relative to the repo root, e.g.
|
|
`packages/compositor/src/Surface.ts`.
|
|
- **ASCII diagrams** are used throughout — they render correctly in any
|
|
Markdown viewer, survive copy-paste, and work in code reviews.
|
|
- **No code excerpts** by user request. We describe algorithms in prose
|
|
and reference file paths so you can read the source yourself.
|
|
- **Cross-references** look like `(see §3 of `03-html5-rendering.md`)`.
|
|
|
|
## How this analysis was produced
|
|
|
|
This bundle was produced by 10 parallel research agents, each assigned to a
|
|
single layer of the Greenfield codebase:
|
|
|
|
- **Agent A** — top-level architecture
|
|
- **Agent B** — Wayland protocol layer (generators + runtime)
|
|
- **Agent C** — HTML5 rendering pipeline
|
|
- **Agent D** — transport layer (WebSocket + KCP)
|
|
- **Agent E** — input handling (keyboard / pointer / touch / xkbcommon)
|
|
- **Agent F** — data device & clipboard
|
|
- **Agent G** — native app bridge (process model + native addons)
|
|
- **Agent H** — xdg-shell / app lifecycle / `UserShellApi`
|
|
- **Agent I** — hardware acceleration / encoding / WASM
|
|
- **Agent J** — pitfalls, anti-patterns, design wins
|
|
|
|
Each agent read the relevant source files end-to-end, produced a stage
|
|
summary, and appended its findings to `/home/z/my-project/worklog.md`.
|
|
This bundle is the synthesis of those findings into a single readable
|
|
document set.
|
|
|
|
## License of the source
|
|
|
|
Greenfield's runtime packages (`compositor`, `compositor-proxy`,
|
|
`compositor-proxy-cli`, `compositor-shell`) are **AGPL-3.0-or-later**.
|
|
The lower-level libs (generators, `common`, `compositor-wasm`,
|
|
`compositor-ffmpeg-h264`, `xtsb`) are MIT or Apache-2.0. Anyone forking
|
|
or building on the runtime packages must respect AGPL — see
|
|
`11-pitfalls.md` §License for implications.
|