# rks-2804/vista architecture

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

- Interactive diagram: https://gitdiagram.com/rks-2804/vista
- Repository: https://github.com/rks-2804/vista

## Overview

##### Project Type & Purpose
- VISTA is a modular, config-driven machine-learning pipeline for structured text analysis.
- Key use-cases: Mix-and-match encoder/decoder backbones (CNN/ViT/Swin + Transformer/BART), run experiments, log metrics to Weights & Biases, support dataset download & training.

##### File Structure
- Top-level modules:
- core/            — registry, abstract base classes
- data/            — dataset loaders and I/O
- encoders/        — CNN, ViT, Swin encoder implementations
- decoders/        — Transformer, BART decoder implementations
- models/          — model composition glue
- training/        — train.py harness
- evaluation/      — metric computation
- scripts/         — CLI entrypoints (run experiments, download data)
- configs/         — YAML configs for experiments & training
- utils/           — helpers
- Build & deploy: setup.py, requirements.txt

##### Extract Insights from README
- Config-based experiment orchestration (configs/*.yaml)
- Registry pattern in core/ to inject encoders/decoders
- Scripts invoke training and evaluation pipelines, optionally logging to wandb
- docs/ folder holds further architectural notes

##### Main Components
a. Command-Line Interface (scripts/)
- run_all_experiments.py
- download_synthdog_ja.py
b. Configuration Manager (configs/ + config_example.yaml)
- Loads YAML, passes to core.registry
c. Core Registry (core/registry.py)
- Factory for encoders/decoders/models
d. Data Pipeline (data/dataset.py)
- Downloads or loads SynthDoG-ja, CORD, etc.
e. Encoder Module (encoders/)
- CNN, ViT, Swin
f. Decoder Module (decoders/)
- Transformer, BART
g. Model Assembly (models/model.py)
- Combines selected encoder + decoder into one trainable model
h. Training Engine (training/train.py)
- Instantiates model, optimizer, loss, data loader; runs epochs
i. Evaluation Suite (evaluation/metrics.py)
- Computes Normed ED, TED, F1 after/between epochs
j. Logging & Tracking
- Weights & Biases integration (wandb)
k. Utilities (utils/)
- Miscellaneous helpers

##### Relationships & Data Flow
1. User invokes a script via CLI → script parses args (config path, wandb flag).
2. Config Manager loads YAML → hands config dict to core.registry.
3. Registry uses config entries to instantiate:
- Data loader
- Encoder
- Decoder
- Model wrapper
- Optimizer, scheduler
4. Training Engine receives these instances → loops over data batches:
- Data loader → batch → encoder → feature maps
- Decoder → predictions → loss
5. After each epoch or at checkpoints:
- Evaluation metrics module computes scores
- Metrics & hyperparams are logged to wandb
6. Final artifacts (models, logs) are stored locally or in wandb.

##### Architectural Patterns & Design Principles
- Plugin/Registry pattern in core.registry for pluggable encoders & decoders
- Config-driven pipeline (YAML files define all hyperparams & component choices)
- Clear separation of concerns: data, model, training, evaluation, logging
- Extensible directory structure allowing additional backbones or metrics
- Script-based orchestration for reproducible experiments

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        CLI_RUN["run_all_experiments.py"]:::orchestration
        CLI_DL["download_synthdog_ja.py"]:::orchestration
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        ConfigsDir["configs/*.yaml"]:::config
        ConfigExample["config_example.yaml"]:::config
    end

    %% Component Layer
    subgraph "Component Layer"
        direction TB
        Registry["core.registry.Registry"]:::component
        subgraph "Encoders"
            direction TB
            CNN["CNN Encoder"]:::component
            ViT["ViT Encoder"]:::component
            Swin["Swin Encoder"]:::component
        end
        subgraph "Decoders"
            direction TB
            Transformer["Transformer Decoder"]:::component
            BART["BART Decoder"]:::component
        end
        Model["Model Assembly"]:::component
    end

    %% Execution Layer
    subgraph "Execution Layer"
        direction TB
        Dataset["Dataset Loader"]:::data
        Training["Training Engine"]:::execution
        Metrics["Evaluation Suite"]:::execution
    end

    %% Persistence & Logging
    subgraph "Persistence & Logging"
        direction TB
        RawStore["Raw Dataset Storage"]:::data
        Wandb["Weights & Biases"]:::logging
    end

    %% Utilities
    Utils["Utilities"]:::util

    %% Connections
    CLI_RUN -->|invokes| ConfigsDir
    CLI_RUN -->|invokes| ConfigExample
    CLI_DL -->|invokes| ConfigsDir
    CLI_DL -->|invokes| ConfigExample

    ConfigsDir -->|loads YAML| Registry
    ConfigExample -->|provides template| Registry

    Registry -->|instantiates| Dataset
    Registry -->|instantiates| CNN
    Registry -->|instantiates| ViT
    Registry -->|instantiates| Swin
    Registry -->|instantiates| Transformer
    Registry -->|instantiates| BART
    Registry -->|assembles| Model

    Dataset -->|provides batches| Training
    Model -->|trained on batches| Training

    Training -->|computes metrics| Metrics
    Training -->|logs metrics| Wandb
    Metrics -->|sends scores| Wandb

    RawStore -->|input data| Dataset

    Utils -.-> Registry
    Utils -.-> Training
    Utils -.-> Metrics

    %% Click Events
    click CLI_RUN "https://github.com/rks-2804/vista/blob/main/scripts/run_all_experiments.py"
    click CLI_DL "https://github.com/rks-2804/vista/blob/main/scripts/download_synthdog_ja.py"
    click ConfigsDir "https://github.com/rks-2804/vista/tree/main/configs/"
    click ConfigExample "https://github.com/rks-2804/vista/blob/main/config_example.yaml"
    click Registry "https://github.com/rks-2804/vista/blob/main/core/registry.py"
    click Dataset "https://github.com/rks-2804/vista/blob/main/data/dataset.py"
    click CNN "https://github.com/rks-2804/vista/blob/main/encoders/cnn.py"
    click ViT "https://github.com/rks-2804/vista/blob/main/encoders/vit.py"
    click Swin "https://github.com/rks-2804/vista/blob/main/encoders/swin.py"
    click Transformer "https://github.com/rks-2804/vista/blob/main/decoders/transformer.py"
    click BART "https://github.com/rks-2804/vista/blob/main/decoders/bart.py"
    click Model "https://github.com/rks-2804/vista/blob/main/models/model.py"
    click Training "https://github.com/rks-2804/vista/blob/main/training/train.py"
    click Metrics "https://github.com/rks-2804/vista/blob/main/evaluation/metrics.py"
    click Utils "https://github.com/rks-2804/vista/tree/main/utils/"

    %% Styles
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef component fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef execution fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef logging fill:#EE82EE,stroke:#333,stroke-width:1px;
    classDef util fill:#F5F5F5,stroke:#333,stroke-width:1px;
```
