How xregistry/server works
Purpose and Entry Points
This Go repository implements the xRegistry specification: a metadata registry for discovery, validation, and versioned resource management. It exposes a server, a management CLI, and supporting generators/linting tools. Primary binaries are cmds/xrserver/xrserver.go (registry server), cmds/xr/xr.go (CLI), cmds/xrlint/main.go, and cmds/genspecattrs/main.go.
Server Composition and Transport Boundary
xrserver initializes registry state, database access, and loading/bootstrap behavior before serving requests. Server-specific orchestration is in cmds/xrserver/xrserver.go, cmds/xrserver/db.go, and cmds/xrserver/loader.go. The reusable registry HTTP layer is registry/httpStuff.go, with UI/static handling in registry/ui.go and registry/ui_static.go. This separates deployment setup from protocol/resource handling.
Registry Domain Model and Operations
The registry package is the core domain engine. It models the registry, groups, resources, entities, and versions in registry/registry.go, registry/group.go, registry/resource.go, registry/entity.go, and registry/version.go. Requests flow from HTTP routing into these model operations, which enforce hierarchy, metadata, versioning, and persistence-facing behavior. registry/model.go represents registry model definitions; registry/info.go and registry/capabilities.go-adjacent common definitions support introspection.
Persistence and Database Boundary
Database-backed state is abstracted through registry/db.go; schema initialization is in registry/init.sql. Server startup owns connection/configuration concerns via cmds/xrserver/db.go. Deployment artifacts indicate MySQL as the material database runtime: misc/mysql.yaml, misc/sql, and container/deployment files under misc/. Registry code should remain the boundary between domain operations and SQL/database behavior.
Models, Validation, and Format Conversion
Registry models describe allowed resource structures and constraints, while format modules translate registry content to/from external schema representations. Core handling is in registry/model.go and registry/format_jsonstructure.go; supported format adapters include registry/format_jsonschema.go, registry/format_avro.go, registry/format_proto.go, and registry/format_xmlschema.go. This is a key interoperability boundary: external schema documents are normalized into registry model/content semantics.
CLI Control Plane
The xr binary maps user commands to remote registry operations and local formatting/conformance behavior. Command handlers include cmds/xr/create.go, cmds/xr/get.go, cmds/xr/set.go, cmds/xr/delete.go, cmds/xr/import.go, cmds/xr/download.go, and cmds/xr/conform.go. Shared client/registry resolution is in cmds/xr/ct_registry.go and cmds/xr/xrlib/registry.go. The CLI is an API client/control-plane boundary rather than a separate domain implementation.
Shared Contracts and UI
Cross-cutting types, constants, error conventions, paths, and capability definitions live in common/const.go, common/error.go, common/proppath.go, and common/capabilities.go. The server can also serve a browser UI from registry/ui/index.html, registry/ui/app.js, and registry/ui/style.css; fixture-like UI registry paths under registry/ui/xreg/ reflect the HTTP resource hierarchy. Containers for server, CLI, all-in-one, and development use misc/Dockerfile-xrserver, misc/Dockerfile-xr, misc/Dockerfile-all, and misc/Dockerfile-dev.
Main entry points: registry.go Registry domain · httpStuff.go Registry HTTP API · xrserver.go xrserver · create.go CLI commands
Components 17
Server runtime
- xrserver · Bootstraps state and serves the registry.
cmds/xrserver/xrserver.go - Server DB setup
cmds/xrserver/db.go - Bootstrap loader
cmds/xrserver/loader.go - Registry HTTP API
registry/httpStuff.go - Browser UI
registry/ui.go
Registry core
- Registry domain · Manages hierarchy, metadata, entities, and versions.
registry/registry.go - Model definitions
registry/model.go - Format adapters · Normalizes external schema formats into registry semantics.
registry/format_jsonstructure.go - Shared contracts
common/const.go
Clients and tools
- xr CLI · Control-plane client for remote registry operations.
cmds/xr/xr.go - CLI commands
cmds/xr/create.go - CLI registry client
cmds/xr/ct_registry.go - xrlint
cmds/xrlint/main.go - genspecattrs
cmds/genspecattrs/main.go
Persistence
- Persistence abstraction
registry/db.go - MySQL
misc/mysql.yaml - Database schema
registry/init.sql
Connections 19
- xrserver → Server DB setup: configures
- xrserver → Bootstrap loader: loads
- xrserver → Registry HTTP API: serves
- Server DB setup → Persistence abstraction: connects
- Bootstrap loader → Registry domain: initializes
- Registry HTTP API → Registry domain: routes requests
- Registry HTTP API → Browser UI: serves
- Registry domain → Model definitions: applies
- Registry domain → Format adapters: imports and exports
- Registry domain → Persistence abstraction: persists through
- Registry domain → Shared contracts: uses
- Persistence abstraction → MySQL: stores state
- Database schema → MySQL: initializes
- xr CLI → CLI commands: dispatches
- CLI commands → CLI registry client: uses
- CLI commands → Format adapters: imports and conforms
- CLI registry client → Registry HTTP API: calls
- xrlint → Model definitions: validates
- genspecattrs → Model definitions: generates attributes for