# dvreeze/tqa architecture

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

- Interactive diagram: https://gitdiagram.com/dvreeze/tqa
- Repository: https://github.com/dvreeze/tqa

## Overview

##### Project’s Main Components
- Layered Architecture: Emphasize the three logical layers:
- The Taxonomy DOM Layer (lowest): Provides a type-safe, yaidom-based representation of taxonomy and linkbase documents.
- The Relationship Layer: Resolves XLink arcs from the DOM layer; manages complex constructs like networks of relationships and overriding.
- The Query API Layer (highest): Offers the type-safe API that applications use to query taxonomy data.
- Extensibility Modules: Note that TQA contains extensions (e.g., formula and table support) that augment the base functionality.
- Pluggable Backing DOM Implementations: Illustrate that alternative DOM implementations (e.g., Saxon tiny trees for production and native DOM for testing) can be plugged in.
- Multi-Module Structure: In the file tree you see separate modules such as “jvm”, “js”, and “shared”. The “shared” module encapsulates core functionality that is used across platforms. The “jvm” and “js” folders indicate platform-specific adaptations (for server/desktop versus JavaScript deployments).
- Supporting Infrastructure: Incorporate components such as the console tools (in the “jvm/console” directory), taxonomy builders (in document builder and taxonomybuilder packages), and test suites which drive quality and provide examples of usage.

##### Relationships and Interactions
- Module Interactions: Map how the “shared” components are used by both the “jvm” and “js” projects, highlighting the dependency flow.
- Extension Integration: Represent extension modules (formula, table) as plug-in components that integrate with the base query API, enhancing functionality without disturbing core layers.
- Pluggability: Indicate that the backing DOM implementation is an interchangeable component that influences how taxonomies are parsed and built.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly denote separation of concerns between data representation (DOM), business logic (resolving relationships), and API exposure (query API).
- Immutability and Thread Safety: Note that TQA is designed to work in multi-threaded environments, assuming that the underlying DOM is both immutable and thread safe.
- Extensibility: Illustrate how extensions (such as for formula and table support) can be integrated without altering the core layers.
- Pluggability: Emphasize that the underlying XML DOM can be swapped (by dependency injection or appropriate factory patterns) based on the use-case scenario.

##### Relevant Technologies
- Scala and SBT: The project uses Scala (with a “build.sbt” at the top level) as the primary language.
- yaidom XML Query API: This plays a central role as the underlying XML processing engine.
- Saxon Tiny Trees (as an example): For the production environment, the Saxon-based DOM wrapper is highlighted for its performance and low memory footprint.
- Testing and Build Infrastructure: Tools such as Travis CI (referenced by “.travis.yml”) and scripts are present for building and deployment.

- Submodules demonstrating the separation into “jvm” and “js” projects, showing how “shared” underpins both.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input
    RAW["Raw XBRL Documents"]:::input

    %% Taxonomy DOM Layer Subgraph
    subgraph "Taxonomy DOM Layer"
        DOM["DOM Representation"]:::core
        DOCBUILDER["Document Builder"]:::core
        DOM --> DOCBUILDER
        DOCBUILDER --> SAXON["Saxon-based Implementation"]:::plugin
        DOCBUILDER --> JVMDOC["JVM Document Builder"]:::plugin
        SAXON --- DOMOUT["DOM Output"]:::core
        JVMDOC --- DOMOUT
    end

    %% Relationship Layer
    REL["Relationship Resolution"]:::core

    %% Query API Layer Subgraph
    subgraph "Query API Layer"
        MODEL["Model Query API"]:::core
        QUERY["Query API Core"]:::core
        MODEL --> QUERY
    end

    %% Extension Modules Subgraph
    subgraph "Extension Modules"
        FORMULA["Formula Support"]:::ext
        TABLE["Table Support"]:::ext
    end

    %% Platform Modules Subgraph
    subgraph "Platform Modules"
        SHARED["Shared Module"]:::module
        JVM["JVM Module"]:::module
        JS["JS Module"]:::module
        SHARED --> JVM
        SHARED --> JS
        %% Supporting Infrastructure within JVM Module
        CONSOLE["Console Tools"]:::infra
        TAXBUILDER["Taxonomy Builders"]:::infra
        CUSTOM["Custom Factories"]:::infra
        JVM --> CONSOLE
        JVM --> TAXBUILDER
        TAXBUILDER --> CUSTOM
    end

    %% Dataflow connections
    RAW --> DOM
    DOMOUT --> REL
    REL --> MODEL
    QUERY -->|"feeds"| FORMULA
    QUERY -->|"feeds"| TABLE

    %% Styling Classes
    classDef input fill:#f7f7f7,stroke:#333,stroke-width:2px;
    classDef core fill:#a1d99b,stroke:#333,stroke-width:2px;
    classDef ext fill:#fdae6b,stroke:#333,stroke-width:2px;
    classDef plugin fill:#9ecae1,stroke:#333,stroke-width:2px;
    classDef module fill:#c7e9c0,stroke:#333,stroke-width:2px;
    classDef infra fill:#fdd0a2,stroke:#333,stroke-width:2px;

    %% Click Events
    click DOM "https://github.com/dvreeze/tqa/tree/master/shared/src/main/scala/eu/cdevreeze/tqa/base/dom"
    click DOCBUILDER "https://github.com/dvreeze/tqa/tree/master/shared/src/main/scala/eu/cdevreeze/tqa/docbuilder"
    click SAXON "https://github.com/dvreeze/tqa/tree/master/jvm/src/main/scala/eu/cdevreeze/tqa/docbuilder/saxon"
    click JVMDOC "https://github.com/dvreeze/tqa/tree/master/jvm/src/main/scala/eu/cdevreeze/tqa/docbuilder/jvm"
    click REL "https://github.com/dvreeze/tqa/tree/master/shared/src/main/scala/eu/cdevreeze/tqa/base/relationship"
    click MODEL "https://github.com/dvreeze/tqa/tree/master/shared/src/main/scala/eu/cdevreeze/tqa/base/model/queryapi"
    click QUERY "https://github.com/dvreeze/tqa/tree/master/shared/src/main/scala/eu/cdevreeze/tqa/base/queryapi"
    click FORMULA "https://github.com/dvreeze/tqa/tree/master/shared/src/main/scala/eu/cdevreeze/tqa/extension/formula"
    click TABLE "https://github.com/dvreeze/tqa/tree/master/shared/src/main/scala/eu/cdevreeze/tqa/extension/table"
    click SHARED "https://github.com/dvreeze/tqa/tree/master/shared/"
    click JVM "https://github.com/dvreeze/tqa/tree/master/jvm/"
    click JS "https://github.com/dvreeze/tqa/tree/master/js/"
    click CONSOLE "https://github.com/dvreeze/tqa/tree/master/jvm/src/main/scala/eu/cdevreeze/tqa/console"
    click TAXBUILDER "https://github.com/dvreeze/tqa/tree/master/jvm/src/main/scala/eu/cdevreeze/tqa/base/taxonomybuilder"
    click CUSTOM "https://github.com/dvreeze/tqa/tree/master/jvm/src/main/scala/eu/cdevreeze/tqa/base/taxonomy/customfactory/jvm"
```
