# stellatechnologies/valigator architecture

> Architecture diagram of the GitHub repository stellatechnologies/valigator, 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/stellatechnologies/valigator
- Repository: https://github.com/stellatechnologies/valigator

## Overview

##### Project Type and Purpose
- This is a Python-based project that serves a dual purpose: it provides a web application (with a graphical user interface) and a command-line tool. Both are used for validating digital twin data files against a structured data schema with defined validation rules.
- The README clearly describes both the web interface (launched via app.py) and the CLI (using main.py), along with detailed steps for schema/data validation, logging, and testing.

##### Analyzing the File Structure
- Top-level files and directories such as app.py, main.py, static/, templates/, and validators/ indicate separation of concerns:
- app.py: Entry point for the web application.
- main.py: Entry point for the command-line interface.
- static/ and templates/: Represent the frontend part (UI assets and HTML views).
- validators/: Contains modules (property_validators.py and type_validators.py) that implement the core validation logic.
- utils/: Provides supporting functionality (logger.py for logging).
- tests/: Comprehensive test suite which covers different validation scenarios.
- This structure hints at a modular design where several independent components interact (frontend, backend validations, logging, CLI vs. Web interface, and testing).

a. Main Components:
- Web Interface:
- Represented by the static directory (CSS, images) and templates directory (HTML views).
- Interacts with app.py that acts as the web server.
- Command-Line Interface:
- Driven by main.py for direct validation processing.
- Core Validation Engine:
- Located in the validators module, divided into property and type validators.
- This engine handles schema, data, table, column, type, foreign key, and property validations.
- Utility/Logging Module:
- Provided by utils/logger.py to log outputs at various levels (Structural Errors, Errors, Warnings, Info).
- Testing Framework:
- The tests directory, including scenario tests and unit tests, validates each piece of functionality.

b. Relationships and Interactions:
- Users interact with the system via two entry points:
- Web Browser: Makes HTTP requests to app.py.
- Command-Line: Invokes main.py with file paths, which then calls into the validation routines.
- Both entry points use the same underlying core validation engine from the validators modules.
- The logging module is used by the validators to log validation results.
- The frontend (HTML/CSS) in the templates and static directories displays validation results received from the backend.
- The test suite ensures these components interact as expected and that validations are correctly performed.

c. Architectural Patterns:
- Modularity: Clear separation between interface layers (web and CLI) and the core validation logic.
- MVC-Like Separation: Although not a full-blown MVC framework, the web interface (templates and static assets) is clearly separated from the business logic (app.py and validators).
- Reusability: The validators and logger modules are structured to be reusable by both interfaces.

d. Technologies & Frameworks:
- The project is written in Python (targeting Python 3.x).
- The web server in app.py likely uses a lightweight framework (such as Flask), inferred from the structure with static and templates directories.
- Command-line interactions and logging are handled via the standard Python ecosystem.
- The testing suite uses Python’s unittest framework.

##### Essential Elements
- Labels clearly naming each component (e.g., “Web Server (app.py)”, “CLI Interface (main.py)”, “Validation Engine (validators modules)”, “Logger (utils/logger.py)”).
- From user input (web or CLI) to the validation engine.
- From the validation engine back to the user (web pages / command-line output).
- Annotations explaining interactions, such as “Uploads schema & data” from the UI to app.py, or “Processes and logs validation steps” from validators to logger.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        WebBrowser["Web Browser"]:::interface
        CLIUser["CLI User"]:::interface
    end

    %% Backend Components
    subgraph "Backend Components"
        WebServer["Web Server (app.py)"]:::backend
        CLIInterface["CLI Interface (main.py)"]:::backend
        subgraph "Core Validation Engine"
            PV["Property Validators (validators/property_validators.py)"]:::core
            TV["Type Validators (validators/type_validators.py)"]:::core
        end
        Logger["Logger (utils/logger.py)"]:::utility
    end

    %% Web Frontend
    subgraph "Web Frontend"
        StaticAssets["Static Assets (static/)"]:::frontend
        Templates["Templates (templates/)"]:::frontend
    end

    %% Testing Framework
    subgraph "Testing"
        TestSuite["Test Suite (tests/)"]:::testing
        UnitTests["Unit Tests (tests/test_validator.py)"]:::testing
        ScenarioTests["Scenario Tests (tests/scenarios/)"]:::testing
    end

    %% Web Flow
    WebBrowser -->|"HTTPRequest"| WebServer
    WebServer -->|"calls"| PV
    WebServer -->|"calls"| TV
    WebServer -->|"renders"| Templates
    Templates -->|"loads"| StaticAssets

    %% CLI Flow
    CLIUser -->|"commandInput"| CLIInterface
    CLIInterface -->|"calls"| PV
    CLIInterface -->|"calls"| TV

    %% Logging Interaction (common to both flows)
    PV -->|"logs"| Logger
    TV -->|"logs"| Logger

    %% Testing Interactions (dashed lines to indicate test validations)
    TestSuite ---|"validates"| PV
    TestSuite ---|"validates"| TV
    TestSuite --> UnitTests
    TestSuite --> ScenarioTests

    %% Click Events
    click WebServer "https://github.com/stellatechnologies/valigator/blob/main/app.py"
    click CLIInterface "https://github.com/stellatechnologies/valigator/blob/main/main.py"
    click StaticAssets "https://github.com/stellatechnologies/valigator/tree/main/static/"
    click Templates "https://github.com/stellatechnologies/valigator/tree/main/templates/"
    click PV "https://github.com/stellatechnologies/valigator/blob/main/validators/property_validators.py"
    click TV "https://github.com/stellatechnologies/valigator/blob/main/validators/type_validators.py"
    click Logger "https://github.com/stellatechnologies/valigator/blob/main/utils/logger.py"
    click TestSuite "https://github.com/stellatechnologies/valigator/tree/main/tests/"
    click UnitTests "https://github.com/stellatechnologies/valigator/blob/main/tests/test_validator.py"
    click ScenarioTests "https://github.com/stellatechnologies/valigator/tree/main/tests/scenarios/"

    %% Styles
    classDef interface fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef utility fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef frontend fill:#AFEEEE,stroke:#000,stroke-width:2px;
    classDef testing fill:#F08080,stroke:#000,stroke-width:2px;
```
