Feat v0.6.5 renderer pipeline (#40)

Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>

docs/ARCHITECTURE.md

@@ -25,6 +25,32 @@ package installer. Surfaces (UI pages), tools, filters, triggers, and
 providers are all packages. The editor, chat, and admin UI will themselves
 be installable surface packages.
 
+## System Architecture Overview
+
+```mermaid
+graph TD
+    Browser["Browser (Preact + htm)"]
+    Server["Go Server (Gin)"]
+    DB["Database (SQLite / Postgres)"]
+
+    Browser -->|HTTP / WebSocket| Server
+
+    subgraph Server Layers
+        Handlers["HTTP Handlers"]
+        Sandbox["Starlark Sandbox"]
+        Store["Store Interface"]
+        EventBus["Event Bus"]
+    end
+
+    Server --> Handlers
+    Handlers --> Store
+    Handlers --> Sandbox
+    Sandbox --> Store
+    Handlers --> EventBus
+    Store --> DB
+    EventBus -->|SSE / WS| Browser
+```
+
 ## Kernel Components
 
 ### Identity & Auth
@@ -36,6 +62,31 @@ permissions, settings, and data against.
 Auth modes: `builtin` (password), `mtls` (client cert), `oidc` (Keycloak
 et al.). Mode is set at deploy time via `AUTH_MODE` env var.
 
+### Request Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant CORS as CORS Middleware
+    participant Auth as Auth Middleware
+    participant H as Handler
+    participant S as Store
+    participant DB as Database
+
+    C->>CORS: HTTP Request
+    CORS->>Auth: Pass through
+    Auth->>Auth: Validate token / session
+    alt Unauthorized
+        Auth-->>C: 401 JSON error
+    end
+    Auth->>H: Authenticated context
+    H->>S: Store method call
+    S->>DB: SQL query
+    DB-->>S: Rows
+    S-->>H: Typed result
+    H-->>C: JSON response
+```
+
 ### Teams & Groups
 
 Teams provide horizontal isolation — users see only their team's resources.
@@ -63,6 +114,26 @@ The unified registry for all installable content. A package is a surface
 Tiers: `browser` (JS only), `starlark` (sandboxed server-side),
 `sidecar` (container, future).
 
+#### Extension Lifecycle
+
+```mermaid
+graph TD
+    Upload["Package Upload (.pkg)"]
+    Parse["Manifest Parse"]
+    Insert["DB Insert (packages table)"]
+    Enable["Admin Enable Toggle"]
+    Mount["Surface Mount (/s/:slug)"]
+    SDK["SDK Boot"]
+    Render["Renderer Registration"]
+
+    Upload --> Parse
+    Parse --> Insert
+    Insert --> Enable
+    Enable --> Mount
+    Mount --> SDK
+    SDK --> Render
+```
+
 ### Starlark Sandbox
 
 Extensions declare capabilities in their manifest. The admin grants or
@@ -128,6 +199,27 @@ Server-sent events to WebSocket clients. Kernel prefixes:
 Extensions will subscribe to event patterns at install time (v0.2.0).
 Match expressions start as exact strings, grow to globs later.
 
+#### Realtime Event Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant WS as WebSocket Hub
+    participant PG as PG LISTEN/NOTIFY
+    participant Other as Other Node
+
+    C->>WS: WS connect + subscribe
+    Note over WS: Local fan-out to subscribers
+    WS-->>C: Event push
+
+    Other->>PG: NOTIFY channel, payload
+    PG->>WS: LISTEN callback
+    WS-->>C: Fan-out to local subscribers
+
+    WS->>PG: NOTIFY channel, payload
+    PG->>Other: LISTEN callback
+```
+
 ### Storage & Notifications
 
 **Object storage**: PVC (local disk) or S3-compatible. Used by extensions
@@ -156,6 +248,26 @@ SQLite parity rules: `boolToInt` for boolean binding, `store.NewID()` for
 INSERT RETURNING, no `NULLS FIRST`, no boolean literals, no `$N` reuse,
 `database.ST()`/`database.SNT()` wrappers for time scanning.
 
+## Settings Cascade
+
+```mermaid
+graph TD
+    Global["Global Scope (admin)"]
+    Team["Team Override"]
+    User["User Override"]
+    RBAC{"RBAC Gate: who can set at what scope?"}
+    Flag{"user_overridable flag"}
+    Effective["Effective Value"]
+
+    Global --> RBAC
+    RBAC -->|allowed| Team
+    RBAC -->|denied| Effective
+    Team --> Flag
+    Flag -->|true| User
+    Flag -->|false| Effective
+    User --> Effective
+```
+
 ## Frontend
 
 Preact (3KB) + htm (tagged template literals). No build step, no bundler
@@ -174,3 +286,25 @@ with DaemonSet DinD runners testing both PG and SQLite pipelines.
 
 Registry: `registry.gobha.me:5000/xcaliber/switchboard-core`
 Namespace: `gobha-ai-chat`
+
+### Cluster Topology
+
+```mermaid
+graph TD
+    N1["Node 1"]
+    N2["Node 2"]
+    N3["Node 3"]
+    PG["PG UNLOGGED Table (cluster_nodes)"]
+    Sweep["Stale Sweep Goroutine"]
+    Notify["PG LISTEN/NOTIFY"]
+
+    N1 -->|heartbeat INSERT/UPDATE| PG
+    N2 -->|heartbeat INSERT/UPDATE| PG
+    N3 -->|heartbeat INSERT/UPDATE| PG
+
+    Sweep -->|DELETE nodes not seen| PG
+    PG -->|join/leave events| Notify
+    Notify --> N1
+    Notify --> N2
+    Notify --> N3
+```