# suesxm/villa-session-bridge architecture

> Architecture diagram of the GitHub repository suesxm/villa-session-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suesxm/villa-session-bridge
- Repository: https://github.com/suesxm/villa-session-bridge

## Overview

Villa Bridge connects a mobile web client to one persistent local AI session through a controller that enforces single-writer leases. The main flow is browser request → HTTP server/security checks → controller queue and turn processing → selected bridge adapter → existing local runtime; controller events return through server-sent events to the browser. The README also documents recovery, message lifecycle, idempotency, and persistent queue state. Edges reflect explicit README statements or shown calls; adapter protocol details are documented, while browser event and controller wiring are only partly excerpted.

Main entry points: [`src/controller.js`](https://github.com/suesxm/villa-session-bridge/blob/main/src/controller.js) (Session controller), [`src/server.js`](https://github.com/suesxm/villa-session-bridge/blob/main/src/server.js) (HTTP server), [`public/app.js`](https://github.com/suesxm/villa-session-bridge/blob/main/public/app.js) (Web interface), [`src/adapters/http.js`](https://github.com/suesxm/villa-session-bridge/blob/main/src/adapters/http.js) (HTTP bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile web"]
  node_web["Web interface<br/>[app.js]"]
  node_browserstate[("Browser key storage<br/>[app.js]")]
end

subgraph group_service["Bridge service"]
  node_server["HTTP server<br/>[server.js]"]
  node_security["Request security<br/>[security.js]"]
end

subgraph group_session["Session control"]
  node_controller["Session controller<br/>[controller.js]"]
  node_turns["Queue and turns<br/>[controller.js]"]
end

subgraph group_adapters["Bridge adapters"]
  node_http["HTTP bridge<br/>[http.js]"]
  node_mock["Demo bridge<br/>[mock.js]"]
end

subgraph group_state["Persistent state"]
  node_store[("JSON state store<br/>[store.js]")]
end

node_user(("Phone user"))
node_runtime["Local session runtime"]

node_user -->|"uses"| node_web
node_web -->|"sends API requests"| node_server
node_server -->|"checks requests"| node_security
node_server -->|"routes actions"| node_controller
node_controller -->|"queues turns"| node_turns
node_controller -->|"persists state"| node_store
node_controller -->|"dispatches turns"| node_http
node_controller -->|"selects demo adapter"| node_mock
node_http -->|"calls local protocol"| node_runtime
node_mock -->|"simulates replies"| node_runtime
node_controller -->|"emits events"| node_server
node_server -->|"streams events"| node_web
node_web -->|"stores access key"| node_browserstate

click node_web "https://github.com/suesxm/villa-session-bridge/blob/main/public/app.js"
click node_server "https://github.com/suesxm/villa-session-bridge/blob/main/src/server.js"
click node_security "https://github.com/suesxm/villa-session-bridge/blob/main/src/security.js"
click node_controller "https://github.com/suesxm/villa-session-bridge/blob/main/src/controller.js"
click node_turns "https://github.com/suesxm/villa-session-bridge/blob/main/src/controller.js"
click node_http "https://github.com/suesxm/villa-session-bridge/blob/main/src/adapters/http.js"
click node_mock "https://github.com/suesxm/villa-session-bridge/blob/main/src/adapters/mock.js"
click node_store "https://github.com/suesxm/villa-session-bridge/blob/main/src/store.js"
click node_browserstate "https://github.com/suesxm/villa-session-bridge/blob/main/public/app.js"

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_web,node_browserstate,node_user toneBlue
class node_server,node_security toneAmber
class node_controller,node_turns toneMint
class node_http,node_mock toneRose
class node_store,node_runtime toneIndigo
```

## Components

### Mobile web

- [Web interface](https://github.com/suesxm/villa-session-bridge/blob/main/public/app.js): `public/app.js`
- [Browser key storage](https://github.com/suesxm/villa-session-bridge/blob/main/public/app.js): `public/app.js`

### Bridge service

- [HTTP server](https://github.com/suesxm/villa-session-bridge/blob/main/src/server.js): `src/server.js`
- [Request security](https://github.com/suesxm/villa-session-bridge/blob/main/src/security.js): `src/security.js`

### Session control

- [Session controller](https://github.com/suesxm/villa-session-bridge/blob/main/src/controller.js): `src/controller.js`
- [Queue and turns](https://github.com/suesxm/villa-session-bridge/blob/main/src/controller.js): `src/controller.js`

### Bridge adapters

- [HTTP bridge](https://github.com/suesxm/villa-session-bridge/blob/main/src/adapters/http.js): `src/adapters/http.js`
- [Demo bridge](https://github.com/suesxm/villa-session-bridge/blob/main/src/adapters/mock.js): `src/adapters/mock.js`

### Persistent state

- [JSON state store](https://github.com/suesxm/villa-session-bridge/blob/main/src/store.js): `src/store.js`

### Other components

- **Phone user**
- **Local session runtime**

## Connections

- Phone user → Web interface: uses (evidence: `README.md`)
- Web interface → HTTP server: sends API requests (evidence: `public/app.js`)
- HTTP server → Request security: checks requests (evidence: `src/server.js`)
- HTTP server → Session controller: routes actions (evidence: `src/server.js`)
- Session controller → Queue and turns: queues turns (evidence: `src/controller.js`)
- Session controller → JSON state store: persists state (evidence: `README.md`)
- Session controller → HTTP bridge: dispatches turns (evidence: `src/server.js`)
- Session controller → Demo bridge: selects demo adapter (evidence: `src/server.js`)
- HTTP bridge → Local session runtime: calls local protocol (evidence: `README.md`)
- Demo bridge → Local session runtime: simulates replies (evidence: `src/adapters/mock.js`)
- Session controller → HTTP server: emits events (evidence: `src/server.js`)
- HTTP server → Web interface: streams events (evidence: `src/server.js`)
- Web interface → Browser key storage: stores access key (evidence: `public/app.js`)