# fva-net/rexs-api-java architecture

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

- Interactive diagram: https://gitdiagram.com/fva-net/rexs-api-java
- Repository: https://github.com/fva-net/rexs-api-java

## Overview

#### Purpose and Modules
REXS-API is a Java 17 library for reading, writing, transforming, validating, and upgrading REXS engineering-model files. Maven root `pom.xml` coordinates two deliverables: reusable API library `api/pom.xml` and command-line application `cli/pom.xml`.

#### Public Entry Points
Library consumers primarily enter through file-format abstractions and model APIs:
- `api/src/main/java/info/rexs/io/RexsFileReader.java`
- `api/src/main/java/info/rexs/io/RexsFileWriter.java`
- `api/src/main/java/info/rexs/io/RexsFileUpgrader.java`

The executable entry point is `cli/src/main/java/info/rexs/cli/Application.java`; it exposes conversion and validation workflows over the API.

#### Canonical Domain Model
The central in-memory boundary is the REXS model: models contain components, attributes, relations, submodels, and load spectra. Typed value classes represent scalar, array, matrix, and Base64-encoded attribute payloads.
- `api/src/main/java/info/rexs/model/IRexsModel.java`
- `api/src/main/java/info/rexs/model/RexsModel.java`
- `api/src/main/java/info/rexs/model/RexsComponent.java`

This domain representation decouples callers from XML, JSON, and ZIP serialization details.

#### Format I/O and Transformation
Reader/writer implementations ingest or emit the canonical model in XML, JSON, or ZIP-packaged forms. Abstract I/O bases and `Resource` implementations establish the file/byte-array input-output boundary. Transformers map between the domain model and serialization-specific representations.
- `api/src/main/java/info/rexs/io/xml/RexsXmlFileReader.java`
- `api/src/main/java/info/rexs/io/json/RexsJsonFileWriter.java`
- `api/src/main/java/info/rexs/io/zip/RexsZipFileReader.java`
- `api/src/main/java/info/rexs/model/transformer/RexsModelXmlTransformer.java`

Typical flow: resource/file → format reader → format-specific representation/transformer → `IRexsModel`; writing reverses this path.

#### Versioned Schema Resolution
Schema registries and resolvers provide version-aware metadata for REXS attributes, component types, relations, units, and value types. Embedded schema XML files are runtime resources, not remote services.
- `api/src/main/java/info/rexs/schema/RexsSchemaRegistry.java`
- `api/src/main/java/info/rexs/schema/RexsSchemaResolver.java`
- `api/src/main/resources/info/rexs/schema/rexs_schema_2.0.0.xml`

Constants under `schema/constants` provide strongly typed identifiers and standard vocabulary; schema resolution is the key boundary between generic model objects and a particular REXS version.

#### Validation Pipeline
Validation operates at file, model, component, relation, and attribute levels, returning structured results/messages. Standard validators enforce REXS rules; modelling-guideline validators add quasistatic-specific checks.
- `api/src/main/java/info/rexs/validation/DefaultRexsFileValidator.java`
- `api/src/main/java/info/rexs/validation/DefaultRexsModelValidator.java`
- `api/src/main/java/info/rexs/validation/RexsStandardFileValidator.java`

The CLI validation command invokes this layer rather than embedding independent validation rules.

#### Upgrade and CLI Orchestration
Upgrade logic resolves chained version migrations, applies model upgraders, and uses embedded changelog resources to move files from REXS 1.0 through 2.0. CLI conversion combines read, optional upgrade/version targeting, and write; validation reads then validates.
- `api/src/main/java/info/rexs/upgrade/RexsUpgrader.java`
- `api/src/main/java/info/rexs/upgrade/upgraders/UpgradeResolver.java`
- `api/src/main/resources/info/rexs/upgrade/upgraders/changelog/rexs_changelog_1.7_to_2.0.0.xml`
- `cli/src/main/java/info/rexs/cli/convert/ConvertCommandServiceImpl.java`
- `cli/src/main/java/info/rexs/cli/validate/ValidateCommandServiceImpl.java`

CI/release automation is provided by GitHub Actions in `.github/workflows/build.yml` and `.github/workflows/release.yml`; no deployed infrastructure or external runtime service is indicated.

Main entry points: [`api/src/main/java/info/rexs/upgrade/RexsUpgrader.java`](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/upgrade/RexsUpgrader.java) (Upgrade pipeline), [`cli/src/main/java/info/rexs/cli/convert/ConvertCommandServiceImpl.java`](https://github.com/fva-net/rexs-api-java/blob/main/cli/src/main/java/info/rexs/cli/convert/ConvertCommandServiceImpl.java) (Convert command), [`api/src/main/java/info/rexs/io/RexsFileReader.java`](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/RexsFileReader.java) (File reader API), [`api/src/main/java/info/rexs/model/IRexsModel.java`](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/IRexsModel.java) (REXS model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Library"]
  node_file_reader["File reader API<br/>I/O abstraction"]
  node_file_writer["File writer API<br/>I/O abstraction"]
  node_file_upgrader["File upgrader API<br/>I/O abstraction"]
  node_format_io["XML, JSON and ZIP I/O<br/>format adapters"]
  node_transformers["Model transformers<br/>serialization mapping"]
  node_rexs_model[("REXS model<br/>canonical domain model<br/>[IRexsModel.java]")]
  node_model_implementation["Model implementation<br/>domain implementation<br/>[RexsModel.java]"]
  node_components["Components and values<br/>domain entities<br/>[RexsComponent.java]"]
  node_schema_registry["Schema registry<br/>version metadata"]
  node_schema_resolver["Schema resolver<br/>version resolver"]
  node_file_validation["File validation<br/>validation facade"]
  node_model_validation["Model validation<br/>validation rules"]
  node_upgrade_pipeline["Upgrade pipeline<br/>version migration<br/>[RexsUpgrader.java]"]
  node_upgrade_resolver["Upgrade resolver<br/>migration resolver"]
end

subgraph group_cli["CLI Application"]
  node_cli_application{{"CLI application<br/>executable<br/>[Application.java]"}}
  node_convert_command["Convert command<br/>command service"]
  node_validate_command["Validate command<br/>command service"]
end

subgraph group_resources["Embedded Metadata"]
  node_schema_xml["Embedded schema XML<br/>runtime resource"]
  node_changelog_xml["Embedded changelogs<br/>runtime resource"]
end

node_library_clients(("Library consumers<br/>caller"))

node_library_clients -->|"read"| node_file_reader
node_library_clients -->|"write"| node_file_writer
node_library_clients -->|"upgrade"| node_file_upgrader
node_cli_application -->|"runs"| node_convert_command
node_cli_application -->|"runs"| node_validate_command
node_convert_command -->|"reads"| node_file_reader
node_convert_command -->|"optional upgrade"| node_file_upgrader
node_convert_command -->|"writes"| node_file_writer
node_validate_command -->|"reads"| node_file_reader
node_validate_command -->|"validates"| node_file_validation
node_file_reader -->|"selects format"| node_format_io
node_format_io -->|"parses or serializes"| node_transformers
node_transformers -->|"maps to/from"| node_rexs_model
node_file_writer -->|"selects format"| node_format_io
node_rexs_model -.->|"implemented by"| node_model_implementation
node_model_implementation -->|"contains"| node_components
node_schema_registry -->|"uses"| node_schema_resolver
node_schema_resolver -->|"loads"| node_schema_xml
node_model_validation -->|"checks"| node_rexs_model
node_model_validation -->|"uses rules"| node_schema_registry
node_file_validation -->|"delegates"| node_model_validation
node_file_upgrader -->|"delegates"| node_upgrade_pipeline
node_upgrade_pipeline -->|"resolves chain"| node_upgrade_resolver
node_upgrade_resolver -->|"loads"| node_changelog_xml
node_upgrade_pipeline -->|"migrates"| node_rexs_model
node_upgrade_pipeline -->|"targets version"| node_schema_registry

click node_cli_application "https://github.com/fva-net/rexs-api-java/blob/main/cli/src/main/java/info/rexs/cli/Application.java"
click node_convert_command "https://github.com/fva-net/rexs-api-java/blob/main/cli/src/main/java/info/rexs/cli/convert/ConvertCommandServiceImpl.java"
click node_validate_command "https://github.com/fva-net/rexs-api-java/blob/main/cli/src/main/java/info/rexs/cli/validate/ValidateCommandServiceImpl.java"
click node_file_reader "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/RexsFileReader.java"
click node_file_writer "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/RexsFileWriter.java"
click node_file_upgrader "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/RexsFileUpgrader.java"
click node_format_io "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/xml/RexsXmlFileReader.java"
click node_transformers "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/transformer/RexsModelXmlTransformer.java"
click node_rexs_model "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/IRexsModel.java"
click node_model_implementation "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/RexsModel.java"
click node_components "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/RexsComponent.java"
click node_schema_registry "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/schema/RexsSchemaRegistry.java"
click node_schema_resolver "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/schema/RexsSchemaResolver.java"
click node_file_validation "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/validation/DefaultRexsFileValidator.java"
click node_model_validation "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/validation/DefaultRexsModelValidator.java"
click node_upgrade_pipeline "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/upgrade/RexsUpgrader.java"
click node_upgrade_resolver "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/upgrade/upgraders/UpgradeResolver.java"
click node_schema_xml "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/resources/info/rexs/schema/rexs_schema_2.0.0.xml"
click node_changelog_xml "https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/resources/info/rexs/upgrade/upgraders/changelog/rexs_changelog_1.7_to_2.0.0.xml"

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_file_reader,node_file_writer,node_file_upgrader,node_format_io,node_transformers,node_rexs_model,node_model_implementation,node_components,node_schema_registry,node_schema_resolver,node_file_validation,node_model_validation,node_upgrade_pipeline,node_upgrade_resolver toneBlue
class node_cli_application,node_convert_command,node_validate_command toneAmber
class node_schema_xml,node_changelog_xml toneMint
class node_library_clients toneNeutral
```

## Components

### API Library

Reusable Java 17 REXS library.

- [File reader API](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/RexsFileReader.java): I/O abstraction · Public model-reading boundary. · `api/src/main/java/info/rexs/io/RexsFileReader.java`
- [File writer API](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/RexsFileWriter.java): I/O abstraction · Public model-writing boundary. · `api/src/main/java/info/rexs/io/RexsFileWriter.java`
- [File upgrader API](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/RexsFileUpgrader.java): I/O abstraction · Public file-upgrade boundary. · `api/src/main/java/info/rexs/io/RexsFileUpgrader.java`
- [XML, JSON and ZIP I/O](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/io/xml/RexsXmlFileReader.java): format adapters · Format readers and writers use resource-backed input and output. · `api/src/main/java/info/rexs/io/xml/RexsXmlFileReader.java`
- [Model transformers](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/transformer/RexsModelXmlTransformer.java): serialization mapping · Maps format representations to and from the domain model. · `api/src/main/java/info/rexs/model/transformer/RexsModelXmlTransformer.java`
- [REXS model](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/IRexsModel.java): canonical domain model · Components, attributes, relations, submodels, and load spectra. · `api/src/main/java/info/rexs/model/IRexsModel.java`
- [Model implementation](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/RexsModel.java): domain implementation · `api/src/main/java/info/rexs/model/RexsModel.java`
- [Components and values](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/model/RexsComponent.java): domain entities · Typed component attributes and payload values. · `api/src/main/java/info/rexs/model/RexsComponent.java`
- [Schema registry](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/schema/RexsSchemaRegistry.java): version metadata · Resolves attributes, types, relations, units, and value types by REXS version. · `api/src/main/java/info/rexs/schema/RexsSchemaRegistry.java`
- [Schema resolver](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/schema/RexsSchemaResolver.java): version resolver · `api/src/main/java/info/rexs/schema/RexsSchemaResolver.java`
- [File validation](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/validation/DefaultRexsFileValidator.java): validation facade · Validates files and returns structured results. · `api/src/main/java/info/rexs/validation/DefaultRexsFileValidator.java`
- [Model validation](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/validation/DefaultRexsModelValidator.java): validation rules · Applies model, component, relation, and attribute rules. · `api/src/main/java/info/rexs/validation/DefaultRexsModelValidator.java`
- [Upgrade pipeline](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/upgrade/RexsUpgrader.java): version migration · Resolves and applies chained model migrations. · `api/src/main/java/info/rexs/upgrade/RexsUpgrader.java`
- [Upgrade resolver](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/java/info/rexs/upgrade/upgraders/UpgradeResolver.java): migration resolver · `api/src/main/java/info/rexs/upgrade/upgraders/UpgradeResolver.java`

### CLI Application

Command workflows over the API.

- [CLI application](https://github.com/fva-net/rexs-api-java/blob/main/cli/src/main/java/info/rexs/cli/Application.java): executable · Conversion and validation entry point. · `cli/src/main/java/info/rexs/cli/Application.java`
- [Convert command](https://github.com/fva-net/rexs-api-java/blob/main/cli/src/main/java/info/rexs/cli/convert/ConvertCommandServiceImpl.java): command service · Reads, optionally upgrades, then writes files. · `cli/src/main/java/info/rexs/cli/convert/ConvertCommandServiceImpl.java`
- [Validate command](https://github.com/fva-net/rexs-api-java/blob/main/cli/src/main/java/info/rexs/cli/validate/ValidateCommandServiceImpl.java): command service · Reads files and invokes API validation. · `cli/src/main/java/info/rexs/cli/validate/ValidateCommandServiceImpl.java`

### Embedded Metadata

Versioned schema and upgrade resources.

- [Embedded schema XML](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/resources/info/rexs/schema/rexs_schema_2.0.0.xml): runtime resource · Schema metadata packaged with the library. · `api/src/main/resources/info/rexs/schema/rexs_schema_2.0.0.xml`
- [Embedded changelogs](https://github.com/fva-net/rexs-api-java/blob/main/api/src/main/resources/info/rexs/upgrade/upgraders/changelog/rexs_changelog_1.7_to_2.0.0.xml): runtime resource · Migration definitions for version upgrades. · `api/src/main/resources/info/rexs/upgrade/upgraders/changelog/rexs_changelog_1.7_to_2.0.0.xml`

### Other components

- **Library consumers**: caller

## Connections

- Library consumers → File reader API: read
- Library consumers → File writer API: write
- Library consumers → File upgrader API: upgrade
- CLI application → Convert command: runs
- CLI application → Validate command: runs
- Convert command → File reader API: reads
- Convert command → File upgrader API: optional upgrade
- Convert command → File writer API: writes
- Validate command → File reader API: reads
- Validate command → File validation: validates
- File reader API → XML, JSON and ZIP I/O: selects format
- XML, JSON and ZIP I/O → Model transformers: parses or serializes
- Model transformers → REXS model: maps to/from
- File writer API → XML, JSON and ZIP I/O: selects format
- REXS model → Model implementation: implemented by
- Model implementation → Components and values: contains
- Schema registry → Schema resolver: uses
- Schema resolver → Embedded schema XML: loads
- Model validation → REXS model: checks
- Model validation → Schema registry: uses rules
- File validation → Model validation: delegates
- File upgrader API → Upgrade pipeline: delegates
- Upgrade pipeline → Upgrade resolver: resolves chain
- Upgrade resolver → Embedded changelogs: loads
- Upgrade pipeline → REXS model: migrates
- Upgrade pipeline → Schema registry: targets version