Constellation Gateway — Portal as Unified Nervous System

--- ring: constellation-gateway onyx: constellation-gateway-doc pearl: Portal as unified nervous system — mesh node architecture and DB-based constellation sync citrine: state: complete ---

# Constellation Gateway — Portal as Unified Nervous System

Portal is the nervous system of the HEXCRAFT constellation. Every node runs Portal, and all nodes share state through the same PostgreSQL Things schema.

## Node Topology

| Node | Domain | Role | |---|---|---| | hexlet | portal.hex-os.dev | Production — live traffic | | hexperiment | portal.hexperiment.dev | Development — test here first | | hexpass | mesh node | Passthrough / routing | | web-vessel instances | dynamic | Client vessel nodes |

## How Mesh Sync Works

Mesh nodes are Things in the `mesh-node` ring. Each node carries:

- `onyx` — node name (hexlet, hexperiment, hexpass) - `sapphire` — category (mesh-node) - `ruby` — domain + upstream routing config - `obsidian.ring` → mesh-node ring UUID

Portal loads all mesh nodes at startup from the Things table. Domain-based routing uses this config to proxy requests across the constellation.

## DB-Based Coordination

No message bus. No service discovery daemon. The database IS the mesh registry:

```sql SELECT gem_values->>'onyx' as name, gem_values->>'ruby' as config FROM things WHERE gem_values->'obsidian'->>'ring' = '<mesh-node-ring-id>'; ```

Any Portal instance with database access sees the full constellation.

## Request Flow

``` Client → Cloudflare → hexlet:Portal ↓ things table lookup mesh-node ring members domain match → proxy to target ```

## Status

Fully operational. hexlet and hexperiment route independently via Cloudflare tunnels. Mesh node Things are the authoritative registry. The constellation scales by inserting rows into the things table — no config files, no restarts.