Architecture

Purpose

This repository is a schema-driven, machine-readable inventory of the F5 Distributed Cloud (F5 XC) administration console UI. It maps API resources to their console locations, navigation paths, form structures, and step-by-step browser automation workflows.

The catalog is consumed by xcsh’s browser automation runtime to power:

• Sales demos — AI-assisted walkthroughs of console CRUD operations
• Training videos — reproducible browser recordings for YouTube and presentations
• UAT/QA automation — automated console interaction testing
• AI-assisted navigation — an AI assistant can look up where to create a resource and drive a browser there

Design Principles

1. Data-only — this repo contains manifests, schemas, and docs. No runtime code. The browser automation runtime lives in xcsh.
2. Schema-driven — every catalog entry validates against JSON Schema. CI enforces this on every PR.
3. Browser-first discovery — catalog entries are initially generated by xcsh crawling the console, then manually refined.
4. Layered model — four separate concerns, cross-referenced by string keys.

Four-Layer Model

┌─────────────────────────────────────────────────┐
│  Layer 1: Navigation Tree                        │
│  catalog/navigation/console-tree.yaml            │
│  What: Console menu structure (sitemap)          │
│  Maps to: Menu paths, submenu hierarchy          │
├─────────────────────────────────────────────────┤
│  Layer 2: Route Definitions                      │
│  catalog/routes/**/*.yaml                        │
│  What: Screen at a URL — layout, controls, table │
│  Maps to: Console URLs, breadcrumbs, operations  │
├─────────────────────────────────────────────────┤
│  Layer 3: Resource Mappings                      │
│  catalog/resources/*.yaml                        │
│  What: API resource → console traceability       │
│  Maps to: API kind, endpoints, form fields       │
├─────────────────────────────────────────────────┤
│  Layer 4: Automation Workflows                   │
│  catalog/workflows/**/*.yaml                     │
│  What: Step-by-step browser automation           │
│  Maps to: navigate, click, fill, assert          │
└─────────────────────────────────────────────────┘

How xcsh Consumes the Catalog

┌──────────────────┐     reads YAML      ┌──────────────────┐
│  console repo    │ ──────────────────▶  │  xcsh browser.ts │
│  (catalog data)  │                      │  + workflow       │
│                  │                      │    runner          │
│  routes/         │                      │                   │
│  resources/      │     CDP commands     │  Chrome instance  │
│  workflows/      │ ◀─────────────────── │  (user session)   │
│  navigation/     │     step results     │  port 9222        │
└──────────────────┘                      └──────────────────┘

1. User invokes xcsh console create http-load-balancer --name example-lb --namespace demo
2. xcsh loads the workflow YAML and resolves parameters
3. xcsh connects to Chrome via CDP (user’s existing browser session)
4. xcsh executes each step: navigate → click → fill → assert
5. Each step is observable — the human watches in real time

Session Sharing

Chrome is launched with --remote-debugging-port=9222 --user-data-dir=~/.config/xcsh/browser-profiles/xcsh. The user logs into the F5 XC console manually once. Cookies persist in the user-data-dir across sessions. xcsh connects to the running browser — no credential handling needed.

Integration Points

System	Integration
api-specs-enriched	Resource api.kind values match; cross-referenced by string key
xcsh browser.ts	Runtime consumer — reads YAML, executes via CDP
docs-control	Governance — managed files, CI workflows, branch protection
docs-theme	Documentation generation from catalog