# hdubey-debug/vcs architecture

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

- Interactive diagram: https://gitdiagram.com/hdubey-debug/vcs
- Repository: https://github.com/hdubey-debug/vcs

## Overview

##### Project Type and Purpose
- This is an open-source Python library and CLI tool for computing and visualizing a range of text-comparison and segmentation metrics (“VCS” metrics like GAS, LAS, NAS, VCS itself, BLEU, METEOR, ROUGE-LCS, etc.).
- It provides a plug-in style architecture: you feed it source and target text (or segmented chunks), it segments, matches, computes multiple metrics, and can generate visual output (charts, tables, PDF reports).

##### High-Level File-Tree Analysis
- src_vcs-16/
- __init__.py and scorer.py – entry-point and top-level CLI or API call
- _config.py – global configuration
- _brm, _mapping_windows, _matching – preprocessing steps: segmentation and alignment
- _metrics – metric computation (subpackages: gas, las, nas with detailed components, vcs)
- _segment_metrics – standard metrics per segment (BLEU, METEOR, ROUGE-LCS)
- _segmenting – chunk/sentence splitting
- _models – any data models or schemas
- _utils – shared utilities (I/O, logging, general helpers)
- _visualize_vcs – visualization engine, with submodules for each metric type plus PDF report, similarity matrix, summary tables, etc.

##### README Insights
- The README is minimal (“I am read me”), so architectural details must come from the code layout rather than documentation.

##### Core Components
a. CLI/API Layer
- scorer.py: accepts user input (file paths, config flags)
b. Configuration
- _config.py
c. Preprocessing
- _segmenting
- _mapping_windows
- _matching (best match algorithms)
- _brm (some specialized alignment strategy)
d. Metric Engine
- _metrics (gas, las, nas, vcs)
- _segment_metrics
e. Data Models
- _models/models.py
f. Visualization Engine
- _visualize_vcs with sub-modules:
- best_match
- core_remove
- distance_nas
- las
- line_nas
- mapping_windows
- metrics_summary
- pdf_report
- similarity_matrix
- text_chunks
- window_regularizer
g. Utilities
- _utils (shared helpers)
h. External Libraries (e.g., numpy, matplotlib, reportlab – if present)

##### Relationships and Data Flow
- User → CLI/API Layer → Configuration
- CLI invokes Preprocessing (segmenting → mapping → matching)
- Preprocessed data passed to Metric Engine → returns raw metric scores
- Scores optionally passed back through Visualization Engine → generates figures, tables, PDFs
- All modules use shared Utilities and Data Models for I/O and in-memory representations

##### Architectural Patterns & Design Principles
- Modular plugin-style: each metric type and visualizer is its own subpackage, making it easy to add new metrics or visualizers
- Clear separation of concerns: preprocessing, metric computation, visualization, and configuration are distinct
- Data flow pipeline: linear stages from raw input to final report

##### Essential Details to Capture
- All major directories and their roles
- Data flow order and dependencies (e.g., matching depends on mapping_windows, which depends on segmenting)
- Extensibility: how new metrics or visualizers fit in
- External dependencies at the bottom or side

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    User("User"):::external
    User -->|runs| CLI

    %% CLI/API Layer
    CLI["CLI/API Layer\n(scorer.py)"]:::io
    click CLI "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/scorer.py"
    CLI --> Config

    %% Configuration
    Config["Configuration\n(_config.py)"]:::io
    click Config "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_config.py"
    Config --> Preprocessing

    %% Preprocessing
    subgraph "Preprocessing" 
        direction TB
        Segmenting["Segmenting\n(_segmenting.py)"]:::core
        click Segmenting "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_segmenting/_segmenting.py"
        MappingWindows["Mapping Windows\n(_mapping_windows.py)"]:::core
        click MappingWindows "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_mapping_windows/_mapping_windows.py"
        Matching["Matching (Best Match)\n(_best_match.py)"]:::core
        click Matching "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_matching/_best_match.py"
        BRM["BRM Alignment\n(brm.py)"]:::core
        click BRM "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_brm/brm.py"
        Segmenting --> MappingWindows --> Matching --> BRM
    end
    Preprocessing --> MetricsEngine

    %% Metric Engine
    subgraph "Metric Engine" 
        direction TB
        subgraph "Core Metrics"
            GAS["GAS Metric\n(_gas.py)"]:::plugin
            click GAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_metrics/_gas/_gas.py"
            LAS["LAS Metric\n(_las.py)"]:::plugin
            click LAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_metrics/_las/_las.py"
            NAS["NAS Metric\n(_nas.py)"]:::plugin
            click NAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_metrics/_nas/_nas.py"
            VCSMetric["VCS Metric\n(_vcs.py)"]:::plugin
            click VCSMetric "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_metrics/_vcs/_vcs.py"
            GAS --> LAS
        end
        subgraph "NAS Components"
            direction TB
            DistanceNAS["Distance NAS\n(_distance_nas.py)"]:::plugin
            click DistanceNAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_metrics/_nas/_nas_components/_distance_nas/_distance_nas.py"
            LineNAS["Line NAS\n(_line_nas.py)"]:::plugin
            click LineNAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_metrics/_nas/_nas_components/_line_nas/_line_nas.py"
            DistanceNAS --> LineNAS
        end
        CoreMetrics --> NASComponents
    end
    MetricsEngine["Metric Engine"]:::core
    MetricsEngine --> SegmentMetrics

    %% Segment-level Metrics
    subgraph "Segment-level Metrics" 
        direction TB
        BLEU["BLEU\n(segment_bleu.py)"]:::plugin
        click BLEU "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_segment_metrics/segment_bleu.py"
        METEOR["METEOR\n(segment_meteor.py)"]:::plugin
        click METEOR "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_segment_metrics/segment_meteor.py"
        ROUGE["ROUGE-LCS\n(segment_rouge_lcs.py)"]:::plugin
        click ROUGE "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_segment_metrics/segment_rouge_lcs.py"
        BLEU --> METEOR --> ROUGE
    end
    SegmentMetrics --> Visualization

    %% Visualization Engine
    subgraph "Visualization Engine" 
        direction TB
        VisBestMatch["Best Match\n(visualizer.py)"]:::plugin
        click VisBestMatch "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_best_match/visualizer.py"
        VisCoreRemove["Core Remove\n(visualizer.py)"]:::plugin
        click VisCoreRemove "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_core_remove/visualizer.py"
        VisDistanceNAS["Distance NAS\n(visualizer.py)"]:::plugin
        click VisDistanceNAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_distance_nas/visualizer.py"
        VisLAS["LAS\n(visualizer.py)"]:::plugin
        click VisLAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_las/visualizer.py"
        VisLineNAS["Line NAS\n(visualizer.py)"]:::plugin
        click VisLineNAS "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_line_nas/visualizer.py"
        VisMappingWindows["Mapping Windows\n(visualizer.py)"]:::plugin
        click VisMappingWindows "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_mapping_windows/visualizer.py"
        VisSummary["Metrics Summary\n(visualizer.py)"]:::plugin
        click VisSummary "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_metrics_summary/visualizer.py"
        VisPDF["PDF Report\n(pdf_report.py)"]:::plugin
        click VisPDF "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_pdf_report/pdf_report.py"
        VisSimMatrix["Similarity Matrix\n(visualizer.py)"]:::plugin
        click VisSimMatrix "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_similarity_matrix/visualizer.py"
        VisTextChunks["Text Chunks\n(visualizer.py)"]:::plugin
        click VisTextChunks "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_text_chunks/visualizer.py"
        VisWindowReg["Window Regularizer\n(visualizer.py)"]:::plugin
        click VisWindowReg "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_visualize_vcs/_window_regularizer/visualizer.py"
    end
    Visualization --> Output

    Output("Final Outputs\n(charts, tables, PDF)"):::io

    %% Shared Models and Utilities
    Models["Data Models\n(models.py)"]:::io
    click Models "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_models/models.py"
    Utils["Utilities\n(_utils.py)"]:::io
    click Utils "https://github.com/hdubey-debug/vcs/blob/main/src_vcs-16/_utils/_utils.py"
    Models --> Preprocessing
    Models --> MetricsEngine
    Models --> Visualization
    Utils --> Preprocessing
    Utils --> MetricsEngine
    Utils --> Visualization

    %% External Libraries
    ExtLibs("External Libraries\n(numpy, matplotlib, reportlab)"):::ext

    %% Styles
    classDef core fill:#cce5ff,stroke:#0066cc,color:#003366;
    classDef io fill:#d4edda,stroke:#28a745,color:#155724;
    classDef plugin fill:#fff3cd,stroke:#ffcc00,color:#856404;
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#343a40;
    class CLI,Config,Models,Utils,Output io
    class Preprocessing,MetricsEngine,SegmentMetrics,Visualization core
    class User,ExtLibs external
```
