# exceefind/featwalk architecture

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

- Interactive diagram: https://gitdiagram.com/exceefind/featwalk
- Repository: https://github.com/exceefind/featwalk

## Overview

##### Project type and purpose
- FeatWalk is a research-oriented Python codebase implementing a novel few-shot learning method (“FeatWalk”) on top of a ResNet backbone and BDC (bilinear distribution covariance) embeddings.
- It’s not a full-stack web service but a modular machine-learning pipeline: data ingestion → feature extraction → method logic → evaluation → checkpointing.

##### File structure
Top-level items:
- run.sh, eval.py – entry-point scripts for training/evaluation.
- data/ – data management (DataMgr, dataset loaders).
- network/ – defines backbone networks (ResNet).
- methods/ – plugin modules implementing different few-shot algorithms (FeatWalk, DeepBDC, STL_DeepBDC, template).
- utils/ – loss functions, general utilities (logging, metric computation).
- README.md – project overview & instructions.
- checkpoint/ and filelist/ (per README) – external directories holding pre-trained models and dataset file lists.

##### README for additional insights
- FeatWalk mines local views against class prototypes to improve representation.
- Relies on pre-trained models (in `checkpoint/`) and dataset splits under `filelist/`.
- run.sh orchestrates experiments; eval.py likely contains the main training/evaluation loop.

##### Main components
a. Data Sources
– filelist/miniImageNet (train/val/test)
– checkpoint/ (pre-trained weights)
b. Data Management Layer (data/)
– dataset.py: dataset abstraction
– datamgr.py: sampler & loader
c. Feature Extraction (network/)
– resnet.py: builds backbone, outputs feature maps
d. Method Modules (methods/)
– FeatWalk.py: core algorithm
– bdc_module.py / stl_deepbdc.py: baseline methods
e. Loss & Utility Layer (utils/)
– loss.py: objective functions
– utils.py: metric computation, helpers
f. Control & Orchestration
– run.sh: shell script to launch eval.py
– eval.py: main routine tying together data, network, methods, loss, evaluation
g. Outputs
– logs, checkpoints, final metrics

##### Architectural patterns & design principles
- Modular plugin design: methods/ directory lets you swap in different algorithms without touching core scripts.
- Separation of concerns: data I/O, model definition, method logic, and utilities are in distinct packages.
- Pipeline orchestration: eval.py orchestrates the end-to-end flow; run.sh simplifies experiment runs.

##### Detail
– Capture each Python module as its own component (e.g., data/datamgr.py vs. data/dataset.py).
– Show the interface points (e.g., DataLoader API → ResNet forward() → FeatWalk.forward()).
– Include both training and evaluation paths if they differ.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Sources
    filelist["filelist/miniImageNet"]:::external
    checkpoint["checkpoint/"]:::external
    logs["logs/"]:::external

    %% Scripts & Orchestration
    runsh["run.sh"]:::scriptLayer
    evalpy["eval.py"]:::scriptLayer

    %% Data Layer
    subgraph "Data Layer"
        dataset["dataset.py"]:::dataLayer
        datamgr["datamgr.py"]:::dataLayer
    end

    %% Model Layer
    subgraph "Model Layer"
        resnet["resnet.py"]:::modelLayer
    end

    %% Method Plugins
    subgraph "Method Plugins"
        featwalk["FeatWalk.py"]:::methodLayer
        bdc["bdc_module.py"]:::methodLayer
        stl["stl_deepbdc.py"]:::methodLayer
        template["template.py"]:::methodLayer
    end

    %% Utilities & Loss
    subgraph "Utilities & Loss"
        loss["loss.py"]:::utilsLayer
        helpers["utils.py"]:::utilsLayer
    end

    %% Relationships
    runsh --> evalpy
    filelist --> datamgr
    datamgr -->|"batches of images"| resnet
    checkpoint --> resnet
    resnet -->|"feature maps"| featwalk
    resnet -->|"feature maps"| bdc
    resnet -->|"feature maps"| stl
    resnet -->|"feature maps"| template
    featwalk --> loss
    bdc --> loss
    stl --> loss
    template --> loss
    loss -->|"loss gradients"| evalpy
    evalpy -->|"save checkpoints"| checkpoint
    evalpy -->|"compute metrics"| helpers
    helpers -->|"metrics output"| logs

    %% Click Events
    click dataset "https://github.com/exceefind/featwalk/blob/main/data/dataset.py"
    click datamgr "https://github.com/exceefind/featwalk/blob/main/data/datamgr.py"
    click resnet "https://github.com/exceefind/featwalk/blob/main/network/resnet.py"
    click featwalk "https://github.com/exceefind/featwalk/blob/main/methods/FeatWalk.py"
    click bdc "https://github.com/exceefind/featwalk/blob/main/methods/bdc_module.py"
    click stl "https://github.com/exceefind/featwalk/blob/main/methods/stl_deepbdc.py"
    click template "https://github.com/exceefind/featwalk/blob/main/methods/template.py"
    click loss "https://github.com/exceefind/featwalk/blob/main/utils/loss.py"
    click helpers "https://github.com/exceefind/featwalk/blob/main/utils/utils.py"
    click runsh "https://github.com/exceefind/featwalk/blob/main/run.sh"
    click evalpy "https://github.com/exceefind/featwalk/blob/main/eval.py"

    %% Styles
    classDef dataLayer fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef modelLayer fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef methodLayer fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef utilsLayer fill:#e0e0e0,stroke:#757575,color:#424242
    classDef scriptLayer fill:#d1c4e9,stroke:#7e57c2,color:#4a148c
    classDef external fill:#f0f4c3,stroke:#afb42b,color:#827717
```
