# xregistry/server architecture

> Architecture diagram of the GitHub repository xregistry/server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xregistry/server
- Repository: https://github.com/xregistry/server

## Overview

#### 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/registry.go`](https://github.com/xregistry/server/blob/master/registry/registry.go) (Registry domain), [`registry/httpStuff.go`](https://github.com/xregistry/server/blob/master/registry/httpStuff.go) (Registry HTTP API), [`cmds/xrserver/xrserver.go`](https://github.com/xregistry/server/blob/master/cmds/xrserver/xrserver.go) (xrserver), [`cmds/xr/create.go`](https://github.com/xregistry/server/blob/master/cmds/xr/create.go) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server runtime"]
  node_xrserver["xrserver<br/>Go server binary<br/>[xrserver.go]"]
  node_server_db["Server DB setup<br/>startup wiring<br/>[db.go]"]
  node_loader["Bootstrap loader<br/>startup loader<br/>[loader.go]"]
  node_http["Registry HTTP API<br/>HTTP transport<br/>[httpStuff.go]"]
  node_ui["Browser UI<br/>static UI<br/>[ui.go]"]
end

subgraph group_core["Registry core"]
  node_domain{{"Registry domain<br/>domain engine<br/>[registry.go]"}}
  node_models["Model definitions<br/>schema model<br/>[model.go]"]
  node_formats["Format adapters<br/>schema conversion"]
  node_contracts["Shared contracts<br/>common types<br/>[const.go]"]
end

subgraph group_clients["Clients and tools"]
  node_xr_cli["xr CLI<br/>Go CLI binary<br/>[xr.go]"]
  node_cli_commands["CLI commands<br/>command handlers<br/>[create.go]"]
  node_cli_client["CLI registry client<br/>API client resolution<br/>[ct_registry.go]"]
  node_xrlint["xrlint<br/>lint binary<br/>[main.go]"]
  node_genspecattrs["genspecattrs<br/>generator binary<br/>[main.go]"]
end

subgraph group_storage["Persistence"]
  node_db_boundary["Persistence abstraction<br/>database interface<br/>[db.go]"]
  node_mysql[("MySQL<br/>database runtime<br/>[mysql.yaml]")]
  node_schema["Database schema<br/>SQL initialization<br/>[init.sql]"]
end

node_xrserver -->|"configures"| node_server_db
node_xrserver -->|"loads"| node_loader
node_xrserver -->|"serves"| node_http
node_server_db -->|"connects"| node_db_boundary
node_loader -->|"initializes"| node_domain
node_http -->|"routes requests"| node_domain
node_http -->|"serves"| node_ui
node_domain -->|"applies"| node_models
node_domain -->|"imports and exports"| node_formats
node_domain -->|"persists through"| node_db_boundary
node_domain -->|"uses"| node_contracts
node_db_boundary -->|"stores state"| node_mysql
node_schema -->|"initializes"| node_mysql
node_xr_cli -->|"dispatches"| node_cli_commands
node_cli_commands -->|"uses"| node_cli_client
node_cli_commands -->|"imports and conforms"| node_formats
node_cli_client -->|"calls"| node_http
node_xrlint -->|"validates"| node_models
node_genspecattrs -->|"generates attributes for"| node_models

click node_xrserver "https://github.com/xregistry/server/blob/master/cmds/xrserver/xrserver.go"
click node_server_db "https://github.com/xregistry/server/blob/master/cmds/xrserver/db.go"
click node_loader "https://github.com/xregistry/server/blob/master/cmds/xrserver/loader.go"
click node_http "https://github.com/xregistry/server/blob/master/registry/httpStuff.go"
click node_ui "https://github.com/xregistry/server/blob/master/registry/ui.go"
click node_domain "https://github.com/xregistry/server/blob/master/registry/registry.go"
click node_models "https://github.com/xregistry/server/blob/master/registry/model.go"
click node_formats "https://github.com/xregistry/server/blob/master/registry/format_jsonstructure.go"
click node_contracts "https://github.com/xregistry/server/blob/master/common/const.go"
click node_db_boundary "https://github.com/xregistry/server/blob/master/registry/db.go"
click node_mysql "https://github.com/xregistry/server/blob/master/misc/mysql.yaml"
click node_schema "https://github.com/xregistry/server/blob/master/registry/init.sql"
click node_xr_cli "https://github.com/xregistry/server/blob/master/cmds/xr/xr.go"
click node_cli_commands "https://github.com/xregistry/server/blob/master/cmds/xr/create.go"
click node_cli_client "https://github.com/xregistry/server/blob/master/cmds/xr/ct_registry.go"
click node_xrlint "https://github.com/xregistry/server/blob/master/cmds/xrlint/main.go"
click node_genspecattrs "https://github.com/xregistry/server/blob/master/cmds/genspecattrs/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_xrserver,node_server_db,node_loader,node_http,node_ui toneBlue
class node_domain,node_models,node_formats,node_contracts toneAmber
class node_xr_cli,node_cli_commands,node_cli_client,node_xrlint,node_genspecattrs toneMint
class node_db_boundary,node_mysql,node_schema toneRose
```

## Components

### Server runtime

- [xrserver](https://github.com/xregistry/server/blob/master/cmds/xrserver/xrserver.go): Go server binary · Bootstraps state and serves the registry. · `cmds/xrserver/xrserver.go`
- [Server DB setup](https://github.com/xregistry/server/blob/master/cmds/xrserver/db.go): startup wiring · `cmds/xrserver/db.go`
- [Bootstrap loader](https://github.com/xregistry/server/blob/master/cmds/xrserver/loader.go): startup loader · `cmds/xrserver/loader.go`
- [Registry HTTP API](https://github.com/xregistry/server/blob/master/registry/httpStuff.go): HTTP transport · `registry/httpStuff.go`
- [Browser UI](https://github.com/xregistry/server/blob/master/registry/ui.go): static UI · `registry/ui.go`

### Registry core

- [Registry domain](https://github.com/xregistry/server/blob/master/registry/registry.go): domain engine · Manages hierarchy, metadata, entities, and versions. · `registry/registry.go`
- [Model definitions](https://github.com/xregistry/server/blob/master/registry/model.go): schema model · `registry/model.go`
- [Format adapters](https://github.com/xregistry/server/blob/master/registry/format_jsonstructure.go): schema conversion · Normalizes external schema formats into registry semantics. · `registry/format_jsonstructure.go`
- [Shared contracts](https://github.com/xregistry/server/blob/master/common/const.go): common types · `common/const.go`

### Clients and tools

- [xr CLI](https://github.com/xregistry/server/blob/master/cmds/xr/xr.go): Go CLI binary · Control-plane client for remote registry operations. · `cmds/xr/xr.go`
- [CLI commands](https://github.com/xregistry/server/blob/master/cmds/xr/create.go): command handlers · `cmds/xr/create.go`
- [CLI registry client](https://github.com/xregistry/server/blob/master/cmds/xr/ct_registry.go): API client resolution · `cmds/xr/ct_registry.go`
- [xrlint](https://github.com/xregistry/server/blob/master/cmds/xrlint/main.go): lint binary · `cmds/xrlint/main.go`
- [genspecattrs](https://github.com/xregistry/server/blob/master/cmds/genspecattrs/main.go): generator binary · `cmds/genspecattrs/main.go`

### Persistence

- [Persistence abstraction](https://github.com/xregistry/server/blob/master/registry/db.go): database interface · `registry/db.go`
- [MySQL](https://github.com/xregistry/server/blob/master/misc/mysql.yaml): database runtime · `misc/mysql.yaml`
- [Database schema](https://github.com/xregistry/server/blob/master/registry/init.sql): SQL initialization · `registry/init.sql`

## Connections

- 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