# op-ted/eforms-sdk architecture

> Architecture diagram of the GitHub repository op-ted/eforms-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/op-ted/eforms-sdk
- Repository: https://github.com/op-ted/eforms-sdk

## Overview

##### Project type and purpose
- This is an open-source SDK (library) providing all metadata and validation assets needed to build eForms applications for public procurement notices. It is not a standalone frontend/backend app, but a resource bundle and validation engine you import into your own tooling.

##### Key modules and their roles
- Codelists
- Controlled vocabularies (Genericode files) used in notices.
- Consumed by schemas and Schematron rules, and driving UI dropdowns in generated forms.
- Schemas
- “common” folder: UBL-2.3 base schemas and EFORMS extensions.
- “maindoc” folder: Notice-specific XSDs (ContractNotice, ContractAwardNotice, PriorInformationNotice, BusinessRegistrationInformationNotice) that import from the common schemas.
- Schematrons
- Static rules: basic structural checks running against the schemas.
- Dynamic rules: stage-based validation logic, one file per stage and notice type.
- They reference both the XSD schemas (for element names) and the codelists (for allowed values).
- EFX-grammar
- ANTLR4 grammar defining the expression language for constraints inside notices and validation rules.
- Generates a parser used by validation tooling.
- Notice-types and fields JSON
- Form structure: which fields belong to each notice subtype, their types, dependencies.
- Drive dynamic form generation and validation scenarios.
- View-templates and translations
- EFX-based templates and localized XML files used to render notices for human viewing.
- Use notice-types, fields and translations to create UI layouts or printable views.
- Examples
- Sample XML notices and their SVRL validation reports, illustrating correct and incorrect cases.

##### Relationships and data flow
- The maindoc XSDs import common XSD modules.
- Schematron rules load the maindoc schemas and the codelists to verify both structure and business constraints.
- Notice-types + fields definitions feed UI form generators and validation scenarios.
- EFX grammar parser is invoked during validation when rules include mini-expressions.
- View-templates combine with translations and notice-types/fields to render forms or XML previews.
- Examples demonstrate the end-to-end: schema validation → schematron validation → SVRL report.

##### Architectural patterns
- Modular resource layering:
common schemas → maindoc schemas → schematron rules.
metadata (codelists, notice-types, fields) → form generation + validation → view templates.
- Separation of concerns:
- Data definitions (XSD, JSON)
- Validation logic (Schematron + EFX)
- Presentation (EFX view templates + translations)
- Build & CI:
- Maven project packaging all assets into an SDK JAR.
- GitHub Actions run code analysis, performance benchmarks, and publish to Maven Central.

##### Capturing “common” ↔ “maindoc” relations accurately
- This explicitly shows that every notice schema builds on the base UBL/EForms common definitions before applying business validation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Definition Layer (Blue)
    Codelists["Codelists"]:::definitions
    CommonSchemas["Common XSD Modules"]:::definitions
    MainDocSchemas["MainDoc XSDs"]:::definitions
    SchemasIndex["Schemas Metadata Index"]:::definitions
    NoticeTypes["Notice-Types Definitions"]:::definitions
    Fields["Fields Definitions"]:::definitions

    %% Logic Layer (Green)
    subgraph "Schematron Validation"
        direction TB
        StaticRules["Static Schematron Rules"]:::logic
        DynamicRules["Dynamic Schematron Rules"]:::logic
        SchematronsIndex["Schematrons Metadata Index"]:::logic
    end
    EFXGrammar["EFX Grammar (ANTLR4)"]:::logic
    FormEngine["Form Generation & Validation Engine"]:::logic

    %% Presentation Layer (Orange)
    ViewTemplates["View-Templates"]:::presentation
    Translations["Translations"]:::presentation
    RenderedUI["Rendered UI / XML Preview"]:::presentation

    %% Examples (Gray)
    ExamplesNotices["Example Notices"]:::examples
    ExamplesReports["SVRL Reports"]:::examples

    %% Tooling Layer (Gray)
    BuildCI["Build & CI (Maven, GitHub Actions)"]:::tooling
    SDKArtifact["SDK JAR Artifact"]:::tooling
    ExternalClient["Client Application"]:::tooling

    %% Relationships
    CommonSchemas -->|import| MainDocSchemas
    SchemasIndex -->|indexes| CommonSchemas
    SchemasIndex -->|indexes| MainDocSchemas

    StaticRules -->|reference| CommonSchemas
    StaticRules -->|reference| MainDocSchemas
    StaticRules -->|reference| Codelists
    DynamicRules -->|reference| CommonSchemas
    DynamicRules -->|reference| MainDocSchemas
    DynamicRules -->|reference| Codelists
    SchematronsIndex -->|indexes| StaticRules
    SchematronsIndex -->|indexes| DynamicRules

    NoticeTypes -->|consume| FormEngine
    Fields -->|consume| FormEngine
    EFXGrammar -->|invoke| FormEngine

    FormEngine -->|render| ViewTemplates
    FormEngine -->|render| Translations
    ViewTemplates -->|combine| RenderedUI
    Translations -->|combine| RenderedUI
    NoticeTypes -->|drive| RenderedUI
    Fields -->|drive| RenderedUI

    ExamplesNotices -->|validated by| CommonSchemas
    ExamplesNotices -->|validated by| StaticRules
    ExamplesNotices -->|validated by| DynamicRules
    ExamplesReports -->|generated| ExamplesNotices

    BuildCI -->|packages| SDKArtifact
    SDKArtifact -->|published to Maven Central| ExternalClient
    ExternalClient -->|uses SDK| FormEngine

    %% Click Events
    click Codelists "https://github.com/op-ted/eforms-sdk/tree/develop/codelists/"
    click CommonSchemas "https://github.com/op-ted/eforms-sdk/tree/develop/schemas/common/"
    click MainDocSchemas "https://github.com/op-ted/eforms-sdk/tree/develop/schemas/maindoc/"
    click SchemasIndex "https://github.com/op-ted/eforms-sdk/blob/develop/schemas/schemas.json"
    click StaticRules "https://github.com/op-ted/eforms-sdk/tree/develop/schematrons/static/"
    click DynamicRules "https://github.com/op-ted/eforms-sdk/tree/develop/schematrons/dynamic/"
    click SchematronsIndex "https://github.com/op-ted/eforms-sdk/blob/develop/schematrons/schematrons.json"
    click EFXGrammar "https://github.com/op-ted/eforms-sdk/blob/develop/efx-grammar/Efx.g4"
    click EFXGrammar "https://github.com/op-ted/eforms-sdk/blob/develop/efx-grammar/EfxLexer.g4"
    click NoticeTypes "https://github.com/op-ted/eforms-sdk/blob/develop/notice-types/notice-types.json"
    click Fields "https://github.com/op-ted/eforms-sdk/blob/develop/fields/fields.json"
    click ViewTemplates "https://github.com/op-ted/eforms-sdk/blob/develop/view-templates/view-templates.json"
    click ViewTemplates "https://github.com/op-ted/eforms-sdk/tree/develop/view-templates/"
    click Translations "https://github.com/op-ted/eforms-sdk/tree/develop/translations/"
    click ExamplesNotices "https://github.com/op-ted/eforms-sdk/tree/develop/examples/notices/"
    click ExamplesReports "https://github.com/op-ted/eforms-sdk/tree/develop/examples/reports/"

    %% Legend
    subgraph Legend
        direction LR
        definitions["Definitions"]:::definitions
        logic["Logic"]:::logic
        presentation["Presentation"]:::presentation
        tooling["Tooling"]:::tooling
        examples["Examples"]:::examples
        note["--> Labels: import, reference, consume, render, invoke, combine"]:::note
    end

    %% Styles
    classDef definitions fill:#D0E6FF,stroke:#045FB4,color:#045FB4;
    classDef logic fill:#D5F5E3,stroke:#27AE60,color:#27AE60;
    classDef presentation fill:#FDEBD0,stroke:#D35400,color:#D35400;
    classDef tooling fill:#EBEDEF,stroke:#AAAAAA,color:#555555;
    classDef examples fill:#F2F3F4,stroke:#7B7D7D,color:#7B7D7D;
    classDef note fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2;
```
