# itplr-kosit/validator architecture

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

- Interactive diagram: https://gitdiagram.com/itplr-kosit/validator
- Repository: https://github.com/itplr-kosit/validator

## Overview

KoSIT Validator is a configurable XML validation engine, exposed as a Java API, CLI, and HTTP daemon with a browser UI. Its principal workflow loads scenario configuration and repository resources, accepts an XML document, identifies its format, applies schema and Schematron validation, generates a report and acceptance status, then returns or displays the result. The README documents these stages and usage modes; source excerpts confirm key API, daemon, input, and UI behavior. Several validation internals are represented from the tree and README, so their unverified links are dashed.

Main entry points: [`src/main/java/de/kosit/validationtool/api/Check.java`](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Check.java) (Check API), [`src/main/java/de/kosit/validationtool/daemon/CheckHandler.java`](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/CheckHandler.java) (Check endpoint), [`src/main/java/de/kosit/validationtool/cmd/Validator.java`](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/cmd/Validator.java) (CLI), [`src/main/java/de/kosit/validationtool/impl/tasks/SchemaValidationAction.java`](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/SchemaValidationAction.java) (Schema validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_scenario["Scenario config"]
  node_configuration_api["Configuration API<br/>[Configuration.java]"]
  node_repository["Content repository"]
end

subgraph group_validation["Validation engine"]
  node_input["Input factory<br/>[InputFactory.java]"]
  node_input_types["Input handling<br/>[SourceInput.java]"]
  node_check_api["Check API<br/>[Check.java]"]
  node_scenario_select["Format selection"]
  node_document_parse["Document parsing"]
  node_schema_validate["Schema validation"]
  node_schematron_validate["Schematron validation"]
  node_report["Report generation"]
  node_acceptance["Acceptance status"]
  node_result["Validation result<br/>[Result.java]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[Validator.java]"]
  node_daemon["HTTP daemon<br/>[Daemon.java]"]
  node_routing["HTTP routing"]
  node_check_handler["Check endpoint<br/>[CheckHandler.java]"]
  node_health["Health endpoint<br/>[HealthHandler.java]"]
  node_ui_upload["XML upload UI<br/>[Upload.tsx]"]
  node_request["HTTP request hook<br/>[useRequest.ts]"]
  node_xml_view["XML result view<br/>[XmlView.tsx]"]
end

subgraph group_support["Runtime support"]
  node_error_events["Error collection"]
  node_conversion["XML conversion"]
  node_engine_info["Engine metadata"]
end

node_user(("User"))

node_user -->|"runs validation"| node_cli
node_user -->|"uploads XML"| node_ui_upload
node_user -->|"embeds API"| node_check_api
node_user -->|"uses HTTP"| node_daemon
node_configuration_api -->|"builds scenarios"| node_scenario
node_configuration_api -->|"loads resources"| node_repository
node_scenario -.->|"configures resources"| node_repository
node_cli -->|"loads config"| node_configuration_api
node_cli -->|"creates inputs"| node_input
node_cli -->|"checks inputs"| node_check_api
node_input -->|"creates input"| node_input_types
node_input_types -.->|"supplies document"| node_check_api
node_check_api -.->|"identifies format"| node_scenario_select
node_scenario_select -.->|"parses document"| node_document_parse
node_document_parse -.->|"validates schema"| node_schema_validate
node_schema_validate -.->|"applies rules"| node_schematron_validate
node_check_api -.->|"generates report"| node_report
node_check_api -.->|"computes status"| node_acceptance
node_report -.->|"produces report"| node_result
node_acceptance -.->|"sets acceptance"| node_result
node_daemon -.->|"registers routes"| node_routing
node_routing -->|"routes checks"| node_check_handler
node_routing -.->|"routes health"| node_health
node_check_handler -->|"creates input"| node_input
node_check_handler -->|"checks document"| node_check_api
node_check_handler -->|"serializes report"| node_result
node_ui_upload -->|"posts XML"| node_request
node_request -.->|"sends HTTP"| node_check_handler
node_ui_upload -.->|"shows report"| node_xml_view
node_health -->|"serializes health"| node_conversion
node_health -->|"reads metadata"| node_engine_info
node_schema_validate -.->|"collects errors"| node_error_events
node_repository -->|"collects errors"| node_error_events

click node_scenario "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/config/ScenarioBuilder.java"
click node_configuration_api "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Configuration.java"
click node_repository "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/ContentRepository.java"
click node_input "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/InputFactory.java"
click node_input_types "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/input/SourceInput.java"
click node_check_api "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Check.java"
click node_scenario_select "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/ScenarioSelectionAction.java"
click node_document_parse "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/DocumentParseAction.java"
click node_schema_validate "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/SchemaValidationAction.java"
click node_schematron_validate "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/SchematronValidationAction.java"
click node_report "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/CreateReportAction.java"
click node_acceptance "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/ComputeAcceptanceAction.java"
click node_result "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Result.java"
click node_cli "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/cmd/Validator.java"
click node_daemon "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/Daemon.java"
click node_routing "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/RoutingHandler.java"
click node_check_handler "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/CheckHandler.java"
click node_health "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/HealthHandler.java"
click node_ui_upload "https://github.com/itplr-kosit/validator/blob/main/server/ui/src/components/Upload/Upload.tsx"
click node_request "https://github.com/itplr-kosit/validator/blob/main/server/ui/src/components/util/useRequest.ts"
click node_xml_view "https://github.com/itplr-kosit/validator/blob/main/server/ui/src/components/XmlView/XmlView.tsx"
click node_error_events "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/CollectingErrorEventHandler.java"
click node_conversion "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/ConversionService.java"
click node_engine_info "https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/EngineInformation.java"

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_scenario,node_configuration_api,node_repository,node_user toneBlue
class node_input,node_input_types,node_check_api,node_scenario_select,node_document_parse,node_schema_validate,node_schematron_validate,node_report,node_acceptance,node_result toneAmber
class node_cli,node_daemon,node_routing,node_check_handler,node_health,node_ui_upload,node_request,node_xml_view toneMint
class node_error_events,node_conversion,node_engine_info toneRose
```

## Components

### Configuration

- [Scenario config](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/config/ScenarioBuilder.java): `src/main/java/de/kosit/validationtool/config/ScenarioBuilder.java`
- [Configuration API](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Configuration.java): `src/main/java/de/kosit/validationtool/api/Configuration.java`
- [Content repository](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/ContentRepository.java): `src/main/java/de/kosit/validationtool/impl/ContentRepository.java`

### Validation engine

- [Input factory](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/InputFactory.java): `src/main/java/de/kosit/validationtool/api/InputFactory.java`
- [Input handling](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/input/SourceInput.java): `src/main/java/de/kosit/validationtool/impl/input/SourceInput.java`
- [Check API](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Check.java): `src/main/java/de/kosit/validationtool/api/Check.java`
- [Format selection](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/ScenarioSelectionAction.java): `src/main/java/de/kosit/validationtool/impl/tasks/ScenarioSelectionAction.java`
- [Document parsing](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/DocumentParseAction.java): `src/main/java/de/kosit/validationtool/impl/tasks/DocumentParseAction.java`
- [Schema validation](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/SchemaValidationAction.java): `src/main/java/de/kosit/validationtool/impl/tasks/SchemaValidationAction.java`
- [Schematron validation](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/SchematronValidationAction.java): `src/main/java/de/kosit/validationtool/impl/tasks/SchematronValidationAction.java`
- [Report generation](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/CreateReportAction.java): `src/main/java/de/kosit/validationtool/impl/tasks/CreateReportAction.java`
- [Acceptance status](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/tasks/ComputeAcceptanceAction.java): `src/main/java/de/kosit/validationtool/impl/tasks/ComputeAcceptanceAction.java`
- [Validation result](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/api/Result.java): `src/main/java/de/kosit/validationtool/api/Result.java`

### User interfaces

- [CLI](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/cmd/Validator.java): `src/main/java/de/kosit/validationtool/cmd/Validator.java`
- [HTTP daemon](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/Daemon.java): `src/main/java/de/kosit/validationtool/daemon/Daemon.java`
- [HTTP routing](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/RoutingHandler.java): `src/main/java/de/kosit/validationtool/daemon/RoutingHandler.java`
- [Check endpoint](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/CheckHandler.java): `src/main/java/de/kosit/validationtool/daemon/CheckHandler.java`
- [Health endpoint](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/daemon/HealthHandler.java): `src/main/java/de/kosit/validationtool/daemon/HealthHandler.java`
- [XML upload UI](https://github.com/itplr-kosit/validator/blob/main/server/ui/src/components/Upload/Upload.tsx): `server/ui/src/components/Upload/Upload.tsx`
- [HTTP request hook](https://github.com/itplr-kosit/validator/blob/main/server/ui/src/components/util/useRequest.ts): `server/ui/src/components/util/useRequest.ts`
- [XML result view](https://github.com/itplr-kosit/validator/blob/main/server/ui/src/components/XmlView/XmlView.tsx): `server/ui/src/components/XmlView/XmlView.tsx`

### Runtime support

- [Error collection](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/CollectingErrorEventHandler.java): `src/main/java/de/kosit/validationtool/impl/CollectingErrorEventHandler.java`
- [XML conversion](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/ConversionService.java): `src/main/java/de/kosit/validationtool/impl/ConversionService.java`
- [Engine metadata](https://github.com/itplr-kosit/validator/blob/main/src/main/java/de/kosit/validationtool/impl/EngineInformation.java): `src/main/java/de/kosit/validationtool/impl/EngineInformation.java`

### Other components

- **User**

## Connections

- User → CLI: runs validation
- User → XML upload UI: uploads XML (evidence: `server/ui/src/components/Upload/Upload.tsx`)
- User → Check API: embeds API
- User → HTTP daemon: uses HTTP
- Configuration API → Scenario config: builds scenarios (evidence: `src/main/java/de/kosit/validationtool/api/Configuration.java`)
- Configuration API → Content repository: loads resources (evidence: `src/main/java/de/kosit/validationtool/api/Configuration.java`)
- Scenario config → Content repository: configures resources (evidence: `src/main/java/de/kosit/validationtool/config/ScenarioBuilder.java`)
- CLI → Configuration API: loads config (evidence: `src/main/java/de/kosit/validationtool/cmd/Validator.java`)
- CLI → Input factory: creates inputs (evidence: `src/main/java/de/kosit/validationtool/cmd/Validator.java`)
- CLI → Check API: checks inputs (evidence: `src/main/java/de/kosit/validationtool/cmd/Validator.java`)
- Input factory → Input handling: creates input (evidence: `src/main/java/de/kosit/validationtool/api/InputFactory.java`)
- Input handling → Check API: supplies document
- Check API → Format selection: identifies format
- Format selection → Document parsing: parses document
- Document parsing → Schema validation: validates schema
- Schema validation → Schematron validation: applies rules
- Check API → Report generation: generates report
- Check API → Acceptance status: computes status
- Report generation → Validation result: produces report
- Acceptance status → Validation result: sets acceptance
- HTTP daemon → HTTP routing: registers routes
- HTTP routing → Check endpoint: routes checks (evidence: `src/main/java/de/kosit/validationtool/daemon/RoutingHandler.java`)
- HTTP routing → Health endpoint: routes health
- Check endpoint → Input factory: creates input (evidence: `src/main/java/de/kosit/validationtool/daemon/CheckHandler.java`)
- Check endpoint → Check API: checks document (evidence: `src/main/java/de/kosit/validationtool/daemon/CheckHandler.java`)
- Check endpoint → Validation result: serializes report (evidence: `src/main/java/de/kosit/validationtool/daemon/CheckHandler.java`)
- XML upload UI → HTTP request hook: posts XML (evidence: `server/ui/src/components/Upload/Upload.tsx`)
- HTTP request hook → Check endpoint: sends HTTP
- XML upload UI → XML result view: shows report
- Health endpoint → XML conversion: serializes health (evidence: `src/main/java/de/kosit/validationtool/daemon/HealthHandler.java`)
- Health endpoint → Engine metadata: reads metadata (evidence: `src/main/java/de/kosit/validationtool/daemon/HealthHandler.java`)
- Schema validation → Error collection: collects errors
- Content repository → Error collection: collects errors (evidence: `src/main/java/de/kosit/validationtool/impl/ContentRepository.java`)
