Control Plane Daemon — Teaching Demo

A minimal working example of a control plane: a daemon watches UI actions, routes them through a rules engine, and pushes back components to render.

See SPEC.md for the full protocol specification.

make build        # build all Docker images
make all          # start the registry
make stack        # interactively choose a daemon + renderer

Then open http://localhost:3000 (React renderer) or http://localhost:8081 (HTML renderer).

Once the stack is running, post a FORM component:

make form

A form appears in the renderer. Submit it (click "Send Message") and watch:

• The action travels from renderer → daemon → registry
• The registry rules engine evaluates the action against registered rules
• The form-submit rule fires and generates a CARD component with the submitted data
• The new CARD appears in the renderer — no page refresh needed

This is the core teaching pattern: renderer sends an action, the rules engine decides what to render next.

┌─────────────┐  subscription   ┌─────────────┐  subscription   ┌─────────────┐
│  Registry   │ ──────────────► │    Daemon   │ ──────────────► │  Renderer   │
│  :4000      │                 │    :3001    │                 │  :3000/8081 │
│             │ ◄────────────── │             │ ◄────────────── │             │
│  Rules +    │  handleMessage  │  Middleware │  sendMessage    │  UI         │
│  State      │  mutation       │  + State    │  mutation       │             │
└─────────────┘                 └─────────────┘                 └─────────────┘

All connections use the graphql-transport-ws subprotocol over WebSocket.

Client (curl)       Registry             Daemon               Renderer
  | POST /render --> |                    |                    |
  |                  | store component    |                    |
  |                  | publish sub event  |                    |
  |                  | ── subscription ──►|                    |
  |                  |                    | cache & forward    |
  |                  |                    | ── subscription ──►| render

1. A component is created via POST /render, a GraphQL mutation, or a rule firing.
2. Registry publishes a componentUpdate subscription event.
3. Daemon's persistent subscription receives the event and caches the component state.
4. Daemon broadcasts the component over its own subscription to all connected renderers.
5. Renderer updates the UI.

Renderer          Daemon                    Registry            Daemon (sub)     Renderer
  | sendMessage ──►| cache action           |                   |                |
  |                | open mutation WS ─────►|                   |                |
  |                | connection_init        |                   |                |
  |                | ◄─ connection_ack ─────|                   |                |
  |                | handleMessage ────────►| run rules         |                |
  |                |                        | publish ──────────►sub event ─────►| render

1. User interacts with a component (submit form, click button).
2. Renderer sends an ACTION envelope to the daemon via sendMessage mutation.
3. Daemon caches the action and opens a short-lived WebSocket to call handleMessage on the registry.
   • A separate WS per mutation isolates failures and ensures graphql-transport-ws handshake.
4. Registry loads component state, evaluates all registered rules.
5. Matching rules generate new component(s); registry publishes them — Component Flow resumes.

Action envelope shape:

{
  "direction": "ACTION",
  "payload": {
    "id": "action-<ts>",
    "componentId": "<component-id>",
    "actionType": "SUBMIT",
    "data": { "name": "Alice", "email": "alice@example.com" },
    "timestamp": "2025-08-16T12:34:56.000Z"
  },
  "metadata": { "acknowledged": false, "correlationId": "...", "error": null }
}

Rules live in ComponentRegistry as a Map<string, Rule> where each rule is:

{
  condition: (state, action) => boolean,  // should this rule fire?
  generate:  (state, action) => ComponentSpec  // what component to create?
}

Default rules:

Run the unit tests to see them in isolation:

make test
# or: cd component-system/registry && npm test

# Step 1: post a FORM component
make form

# Step 2: get the FORM component id
curl -s -X POST http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query { components { id type } }"}' \
  | jq -r '.data.components[] | select(.type=="FORM") | .id'

# Step 3: send a SUBMIT action (replace <id> with the value above)
make action FORM_ID=<id>

Or use the make action shortcut which builds the full envelope automatically.

# Terminal 1 — registry rule evaluation
make rules-logs

# Terminal 2 — all services
make logs

Expected log sequence for a SUBMIT action:

1. Daemon: Received ACTION message
2. Daemon: Mutation WS connected for handleMessage
3. Registry: Handling message → Processing action
4. Registry: Evaluating rules → Rule 'form-submit' triggered
5. Registry: Publishing new component <new-id>
6. Daemon: Received component from registry: <new-id>
7. Renderer: new CARD appears

# CARD with clickable buttons
curl -X POST http://localhost:4000/render \
  -H "Content-Type: application/json" \
  -d '{"type":"CARD","data":{"title":"Hello","content":"A card component","buttons":[{"text":"Click me"}]}}'

# NOTIFICATION
curl -X POST http://localhost:4000/render \
  -H "Content-Type: application/json" \
  -d '{"type":"NOTIFICATION","data":{"status":"SUCCESS","title":"It works","message":"Component flow is operational"}}'

{
  "type": "CARD",
  "data": {
    "title": "Card Title",
    "content": "Description text",
    "buttons": [{ "text": "Button Label", "action": "ACTION_NAME" }]
  }
}

{
  "type": "NOTIFICATION",
  "data": {
    "status": "SUCCESS | ERROR | WARNING | INFO",
    "title": "Notification Title",
    "message": "Notification message"
  }
}

{
  "type": "FORM",
  "data": {
    "title": "Form Title",
    "fields": [
      { "name": "fieldName", "label": "Field Label", "type": "text | email | password" }
    ],
    "submitText": "Submit"
  }
}

Both daemons bind to port 3001 inside Docker. The docker-compose.yml maps the Rust daemon to host port 3001 and the Node daemon to host port 3002, so you can run both simultaneously — they just serve from different host ports.