Alephex

Alephex (AH-leff-eks) is named after the aleph. In Borges' story the Aleph is a single point in space that contains every other point, a place you can look into and see everything at once. That is what this UI is for: one console to watch and manage a whole field of connected systems and the servers behind them, instead of hopping between them one at a time.

Now ironically currently this only support one server at a time :) So we will treat the name as aspirational for now

VS Code + Vue (Official) (and disable Vetur).

• Chromium-based browsers (Chrome, Edge, Brave, etc.):
  • Vue.js devtools
  • Turn on Custom Object Formatter in Chrome DevTools
• Firefox:
  • Vue.js devtools
  • Turn on Custom Object Formatter in Firefox DevTools

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need Volar to make the TypeScript language service aware of .vue types.

See Vite Configuration Reference.

pnpm install

The production image serves the Vite bundle with Caddy and falls back to index.html for Vue Router routes, including the OIDC callback.

To publish the default multi-platform image (linux/amd64 and linux/arm64), authenticate to the registry and run:

docker login docker.monogatari.dev
./buildx.sh

The default target is docker.monogatari.dev/connected-systems/alephex:latest. The script creates and uses an alephex-multiarch BuildKit builder, so it works even if Docker Desktop's selected builder uses the single-platform docker driver. Set BUILDER, TAG, IMAGE, PLATFORMS, or CS_API_CLIENT_DIR to override it, for example:

TAG=2026.08.16 ./buildx.sh

The build requires BuildKit because cs-api-client is supplied as a named local build context. To build and load an amd64 image locally without pushing:

docker buildx build --load --platform linux/amd64 \
  --build-context cs-api-client=../../../connected-systems/cs-api-client \
  --tag alephex:local .

From this directory, launch the UI at http://localhost:8080:

docker compose up --build

The Compose build expects the sibling cs-api-client repository at its usual relative location. If yours lives elsewhere, supply its path when starting:

CS_API_CLIENT_DIR=/path/to/cs-api-client docker compose up --build

Set ALEPHEX_PORT to use a port other than 8080.

Compose supplies the Connected Systems and MQTT settings when the container starts, so the same image can be promoted between environments. Copy the example to .env, set the production values, and restart the service:

cp .env.example .env
docker compose up --build -d

VITE_CS_MQTT_URL must be a browser-reachable WebSocket URL, such as wss://mqtt.example.com/mqtt. These values are written to /runtime-config.js and delivered to every browser, so MQTT credentials are not secrets; use a broker account restricted to the minimum required access.

The Live events dashboard view combines three OGC API - Connected Systems Part 3 message categories in one in-memory feed:

• full System Event Resource Data messages;
• CloudEvents Resource Events for individual resource lifecycle changes; and
• Batch Resource Events for aggregated lifecycle changes.

After the HTTP resources load, Alephex follows the API landing page's service-desc links and uses the first valid AsyncAPI description to discover incoming channels. AsyncAPI channel parameters are converted to MQTT + wildcards. Alephex prefers the parameterized System Event channel, a global Resource Event channel when one exists (otherwise the broadest non-overlapping collection channels), and every distinct Batch Resource Event channel. These are application discovery rules, not a normative Part 3 MQTT channel layout or flow-control mechanism.

If AsyncAPI discovery cannot be completed, Alephex keeps listening for System Event Resource Data on systems/+/events and marks lifecycle streams as unavailable. The browser continues to use the runtime VITE_CS_MQTT_URL; an AsyncAPI broker URL does not override it.

Create and update Resource Events include a View resource action. Alephex uses the event type to select the resource editor, resolves resource and parent IDs from the CloudEvent subject, reloads the current representation over HTTP, and opens it in a read-only side panel. Delete events remain visible in the feed but are marked as deleted because their subjects no longer resolve. Batch events describe collections and therefore do not expose a single-resource action. The feed retains only the newest 100 messages for the current connection and is cleared on reconnect, mode changes, and sign-out.

pnpm dev

pnpm build

pnpm test:unit

# Install browsers for the first run
npx playwright install

# When testing on CI, must build the project first
pnpm build

# Runs the end-to-end tests
pnpm test:e2e
# Runs the tests only on Chromium
pnpm test:e2e --project=chromium
# Runs the tests of a specific file
pnpm test:e2e tests/example.spec.ts
# Runs the tests in debug mode
pnpm test:e2e --debug

pnpm lint