# packetcoders/net-schema architecture

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

- Interactive diagram: https://gitdiagram.com/packetcoders/net-schema
- Repository: https://github.com/packetcoders/net-schema

## Overview

##### Project Type and Purpose
- Project Type: A Python-based library and CLI tool.
- Purpose: Validate JSON/YAML documents against a defined schema (leveraging JSON Schema) and apply custom validators (for network-specific data like ASN, IP, and VLAN). The tool also supports an option to check for duplicate keys.

##### File Structure
- Top-Level Files: Configuration files such as .flake8, .gitignore, Makefile, LICENSE, and pyproject.toml indicate standard Python project setup and CI configurations.
- Directories Breakdown:
- src: Contains core source code including:
▪ main.py – Likely the entry point for the CLI.
▪ helpers.py – Contains supportive utility functions.
▪ plugins/json_schema: Houses modules for custom validator implementations (asn.py, ip.py, validator.py, vlan.py). This indicates the use of a plugin-like architecture to extend JSON Schema with network-specific validations.
- examples: Provides sample host variables (YAML) and a sample schema file, which helps understand inputs and usage.
- tests: Contains test suites and fixtures – validating different aspects of the code (helpers, each plugin validator, etc.).
- .github/workflows: CI/CD pipeline configurations.

##### README for Additional Insights
- The README explains the project’s usage via CLI, installation instructions, and examples.
- It lists out custom validators (for ASN, IP, and VLAN), suggesting that these are core to the system’s operation.
- The descriptions help confirm that the primary interaction model is through command-line invocation, leveraging the main entry point and plugins.

a. Main Components:
- CLI Interface:
- Represented by the command-line entry point (src/main.py) that parses user arguments (document and schema paths, dup key option).
- Core Validation Engine:
- Includes core logic defined in src/helpers.py and orchestrated via main.py.
- This orchestrates reading input files, applying the JSON Schema validations, and using custom validators.
- Plugin System for Custom Validators:
- Represented by modules under src/plugins/json_schema/.
- Includes dedicated components for asn, ip, and vlan validation.
- Input and Output:
- Input: Document files and Schema file (illustrated by the examples directory).
- Output: Validation results (success or error messages).
- Testing Framework:
- Tests directory ensures functional correctness of each component.

b. Relationships and Interactions:
- The CLI initiates the process by invoking main.py.
- The main module uses helper functions to load and parse the documents and schema.
- The JSON Schema validator (plugin system) is invoked to check conformity to standard rules.
- Custom validator plugins (asn.py, ip.py, vlan.py) are then triggered when their keys are detected in the schema; they validate specialized network data rules.
- The results and any validation errors are then collected and output to the user.
- CI/CD and tests components ensure that each portion (core logic and plugins) is continually validated.

c. Architectural Patterns & Design Principles:
- Modularity: Separation between core validation logic (in main and helpers) and specialized validators (as plugins).
- Extensibility: Clear plugin structure that allows adding additional domain-specific checks without altering the core engine.
- Maintainability: Well-structured directories (src, tests, examples) indicate a clear separation of concerns.

d. Relevant Technologies and Frameworks:
- Python as the primary language.
- JSON Schema for document validation.
- Standard packaging tools (pip, poetry) and CI/CD (GitHub workflows).
- Testing frameworks (pytest implied by test files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    A["Input Documents & Schemas"]:::input
    B["CLI Entry Point (src/main.py)"]:::processing
    C["Validation Engine (src/helpers.py)"]:::processing
    E["Validation Output"]:::input
    F["Test Suite (tests)"]:::tests

    %% Custom Validator Plugins Subgraph
    subgraph "Custom Validator Plugins"
        D1["JSON Schema Plugin Base (src/plugins/json_schema/validator.py)"]:::plugins
        D2["ASN Validator (src/plugins/json_schema/asn.py)"]:::plugins
        D3["IP Validator (src/plugins/json_schema/ip.py)"]:::plugins
        D4["VLAN Validator (src/plugins/json_schema/vlan.py)"]:::plugins
    end

    %% Connections
    A -->|"provides"| B
    B -->|"invokes"| C
    C -->|"calls"| D1
    D1 -->|"triggers"| D2
    D1 -->|"triggers"| D3
    D1 -->|"triggers"| D4
    D2 -->|"returns"| C
    D3 -->|"returns"| C
    D4 -->|"returns"| C
    C -->|"produces"| E
    C -->|"monitored_by"| F

    %% Click Events
    click A "https://github.com/packetcoders/net-schema/tree/development/examples"
    click B "https://github.com/packetcoders/net-schema/blob/development/src/main.py"
    click C "https://github.com/packetcoders/net-schema/blob/development/src/helpers.py"
    click D1 "https://github.com/packetcoders/net-schema/blob/development/src/plugins/json_schema/validator.py"
    click D2 "https://github.com/packetcoders/net-schema/blob/development/src/plugins/json_schema/asn.py"
    click D3 "https://github.com/packetcoders/net-schema/blob/development/src/plugins/json_schema/ip.py"
    click D4 "https://github.com/packetcoders/net-schema/blob/development/src/plugins/json_schema/vlan.py"
    click F "https://github.com/packetcoders/net-schema/tree/development/tests"

    %% Styles
    classDef input fill:#9fdf9f,stroke:#333,stroke-width:2px;
    classDef processing fill:#9fc5e8,stroke:#333,stroke-width:2px;
    classDef plugins fill:#f9cb9c,stroke:#333,stroke-width:2px;
    classDef tests fill:#cccccc,stroke:#333,stroke-width:2px;
```
