docs: describe the migrated architecture

Author: dnlblasco

README.md

@@ -26,35 +26,62 @@ The plugin is the source of truth. Menu files stay under `plugins/BlueMenu/menus
 
 ## How a session works
 
-1. A player runs `/bm editor` in game. The plugin opens a session against `wss://menu.blueva.net/ws` and hands the player a link.
-2. Opening the link binds that browser window to the session. Each window carries its own verification id, so a leaked link does not grant access on its own.
-3. If `require-confirmation` is on in `settings.yml`, the plugin waits for `/bm confirm` in game before the session becomes editable.
-4. The editor requests the menu list, loads a menu, and saves changes back through the same socket. With `auto-save` and `auto-reload` enabled, the plugin writes the YAML and reloads the menu immediately.
+1. A player runs `/bm editor` in game. The plugin asks the editor to open a session and hands the player a link.
+2. Opening the link registers that browser window and gives it its own verification id, so a leaked link does not grant access on its own.
+3. If `require-confirmation` is on in `settings.yml`, the plugin waits for `/bm confirm <id>` in game before the session becomes editable.
+4. From then on the browser edits over plain HTTP. Every operation that needs the server is forwarded to the plugin and answered by it.
 
-Sessions expire on their own, and the plugin rejects any message whose session is unknown, consumed or unconfirmed.
+Sessions expire on their own, and the editor rejects any request whose session is unknown, consumed or unconfirmed.
+
+## How the plugin is reached
+
+The plugin is not a client the editor can call directly, so requests travel to it over a broadcast channel and come back over HTTP:
+
+- The server registers once and stores its credentials in `webeditor-credentials.yml`.
+- It subscribes to its own private Reverb channel and keeps itself marked as reachable with a heartbeat.
+- A browser request that needs the server publishes an RPC request on that channel and waits; the plugin performs the operation and posts the answer back to `/api/plugin/rpc-response`.
+
+That wait happens **inside** the browser's request while the answer arrives on a **different** request, so the web process must serve more than one request at a time. With a single worker the waiting request starves the one that would release it:
+
+```bash
+PHP_CLI_SERVER_WORKERS=6 php artisan serve --host=0.0.0.0 --port=8000 --no-reload
+```
+
+`artisan serve` only honours `PHP_CLI_SERVER_WORKERS` together with `--no-reload`.
+
+## Demo mode
+
+Opening the site without a session shows the editor running on the example menus the plugin ships. Everything renders and every editor works; only saving is unavailable, because there is no server behind it.
 
 ## Stack
 
-- Laravel 13 on PHP 8.3+
+- Laravel 13 on PHP 8.3+, with Laravel Reverb for the channel the plugin listens on
 - React 19 with TypeScript 7, mounted from a Blade shell
+- CodeMirror 6 for the YAML editor, `yaml` for the document model
 - Vite 8 with the Laravel plugin, Tailwind 4 and Bunny Fonts
 - SQLite by default, MySQL in production
-- PHPUnit for tests
+- PHPUnit for the backend, Vitest for the editor
 
 ## Project Layout
 
 ```
 app/
-├── Http/Controllers/   HTTP entry points
-├── Models/             Eloquent models
-└── Providers/          service providers
+├── Enums/                    domain vocabularies
+├── Events/                   broadcast events, including the plugin RPC request
+├── Http/Controllers/Api/     browser endpoints
+├── Http/Controllers/Api/Plugin/  endpoints the plugin calls
+├── Models/                   servers, sessions, verifications, settings
+└── Services/                 session lifecycle, RPC bridge, maintenance, admin console
 resources/
-├── css/app.css         Tailwind entry
-├── js/                 React application, entry at app.tsx
-└── views/              Blade shell that mounts React
-routes/web.php          web routes
-database/migrations/    schema
-tests/                  PHPUnit feature and unit tests
+├── demo/                     the sample menus the plugin ships
+├── js/editor/                menu model, yaml codec, validator, materials
+├── js/components/            editor chassis
+├── js/components/visual/     canvas, item editor, form builder, animator
+└── views/                    Blade shells that mount React
+routes/web.php                browser routes
+routes/plugin.php             plugin routes
+routes/channels.php           private channel authorisation
+public/editor/items/          item sprites, one folder per Minecraft version
 ```
 
 ## Requirements
@@ -65,6 +92,7 @@ tests/                  PHPUnit feature and unit tests
 | Composer | 2+ |
 | Node | 20+ |
 | Database | SQLite for local work, MySQL 8+ in production |
+| Reverb | Started with `php artisan reverb:start` |
 
 ## Getting Started
 
@@ -96,15 +124,17 @@ composer dev
 ```bash
 npm run dev          # Vite dev server with hot reload
 npm run typecheck    # tsc --noEmit
+npm test             # Vitest, covering the yaml codec and the editor logic
 npm run build        # production assets
 composer test        # clears config, then runs PHPUnit
+php artisan reverb:start
 ```
 
 Run the narrowest test set that covers a change, for example `php artisan test --compact --filter=SomeTest`.
 
 ## Deployment
 
-`.github/workflows/deploy.yml` typechecks, builds and runs the test suite on every push and pull request. On `main` it then pulls, installs production dependencies, rebuilds the assets, migrates and warms the caches on the host.
+`.github/workflows/deploy.yml` typechecks, builds and runs both test suites on every push and pull request. On `main` it then pulls, installs production dependencies, rebuilds the assets, migrates and warms the caches on the host.
 
 ## Authors