# vulpfin/vfa architecture

> Architecture diagram of the GitHub repository vulpfin/vfa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vulpfin/vfa
- Repository: https://github.com/vulpfin/vfa

## Overview

VFA is a cross-platform archive toolchain. Users create or append VFA1/VFA2 archives, then browse or extract them; VFA2 adds chunking, deduplication, filters, and specialized codecs. The repository also includes Windows self-extracting archives and a self-finishing installer flow. The excerpts show selected writer, reader, codec, and GUI internals; several documented features are represented at their owning module without guessing unshown call paths.

Main entry points: [`vfa.py`](https://github.com/vulpfin/vfa/blob/main/vfa.py) (VFA CLI), [`vfa_extract.py`](https://github.com/vulpfin/vfa/blob/main/vfa_extract.py) (Archive extraction), [`vulp/vulp.h`](https://github.com/vulpfin/vfa/blob/main/vulp/vulp.h) (Codec API), [`vfa2.py`](https://github.com/vulpfin/vfa/blob/main/vfa2.py) (VFA2 writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_archive["Archive workflows"]
  node_cli["VFA CLI<br/>[vfa.py]"]
  node_vfa1["VFA1 archives<br/>[vfa.py]"]
  node_vfa2writer["VFA2 writer<br/>[vfa2.py]"]
  node_extract["Archive extraction<br/>[vfa_extract.py]"]
  node_vfa2reader["VFA2 reading<br/>[vfa2.py]"]
  node_metadata["File metadata<br/>[vfa.py]"]
  node_security["Archive security<br/>[vfa.py]"]
end

subgraph group_codec["VFA2 codecs"]
  node_filters["Filters and chunking<br/>[vfa2.py]"]
  node_reference["Python reference codec<br/>[vulp_ref.py]"]
end

subgraph group_browse["Browse and install"]
  node_viewer["Archive viewer<br/>[vfa_viewer.py]"]
  node_sfx["SFX launcher<br/>[sfx_stub.py]"]
  node_sfi["Installer stub<br/>[sfi_stub.py]"]
  node_wizard["Installer wizard<br/>[sfi_gui.py]"]
  node_version["Version reporting<br/>[vfa_version.py]"]
end

subgraph group_native["Native codec"]
  node_tans["tANS codec<br/>[vulp.c]"]
  node_lz["Vulp LZ codec<br/>[vulp_lz.c]"]
  node_context["Context mixer<br/>[vulp_cm.c]"]
  node_codec_api["Codec API<br/>[vulp.h]"]
end

node_user(("Archive user"))

node_user -->|"invokes"| node_cli
node_cli -->|"creates or appends"| node_vfa1
node_cli -->|"selects VFA2"| node_vfa2writer
node_cli -->|"extracts via"| node_extract
node_cli -->|"dispatches VFA2"| node_vfa2reader
node_vfa2writer -->|"chunks and filters"| node_filters
node_vfa2reader -->|"reverses filters"| node_filters
node_vfa2writer -.->|"uses fallback codec"| node_reference
node_vfa2reader -.->|"uses fallback codec"| node_reference
node_codec_api -->|"declares API"| node_tans
node_codec_api -->|"declares API"| node_lz
node_codec_api -->|"declares API"| node_context
node_user -->|"browses archives"| node_viewer
node_viewer -->|"uses extraction"| node_extract
node_sfx -->|"extracts payload"| node_extract
node_sfi -->|"extracts payload"| node_extract
node_sfi -->|"opens GUI"| node_wizard
node_cli -.->|"preserves metadata"| node_metadata
node_cli -.->|"supports encryption"| node_security
node_cli -->|"reports version"| node_version

click node_cli "https://github.com/vulpfin/vfa/blob/main/vfa.py"
click node_vfa1 "https://github.com/vulpfin/vfa/blob/main/vfa.py"
click node_vfa2writer "https://github.com/vulpfin/vfa/blob/main/vfa2.py"
click node_extract "https://github.com/vulpfin/vfa/blob/main/vfa_extract.py"
click node_vfa2reader "https://github.com/vulpfin/vfa/blob/main/vfa2.py"
click node_metadata "https://github.com/vulpfin/vfa/blob/main/vfa.py"
click node_security "https://github.com/vulpfin/vfa/blob/main/vfa.py"
click node_filters "https://github.com/vulpfin/vfa/blob/main/vfa2.py"
click node_reference "https://github.com/vulpfin/vfa/blob/main/vulp_ref.py"
click node_tans "https://github.com/vulpfin/vfa/blob/main/vulp/vulp.c"
click node_lz "https://github.com/vulpfin/vfa/blob/main/vulp/vulp_lz.c"
click node_context "https://github.com/vulpfin/vfa/blob/main/vulp/vulp_cm.c"
click node_codec_api "https://github.com/vulpfin/vfa/blob/main/vulp/vulp.h"
click node_viewer "https://github.com/vulpfin/vfa/blob/main/vfa_viewer.py"
click node_sfx "https://github.com/vulpfin/vfa/blob/main/sfx_stub.py"
click node_sfi "https://github.com/vulpfin/vfa/blob/main/sfi_stub.py"
click node_wizard "https://github.com/vulpfin/vfa/blob/main/sfi_gui.py"
click node_version "https://github.com/vulpfin/vfa/blob/main/vfa_version.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_vfa1,node_vfa2writer,node_extract,node_vfa2reader,node_metadata,node_security,node_user toneBlue
class node_filters,node_reference toneAmber
class node_viewer,node_sfx,node_sfi,node_wizard,node_version toneMint
class node_tans,node_lz,node_context,node_codec_api toneRose
```

## Components

### Archive workflows

- [VFA CLI](https://github.com/vulpfin/vfa/blob/main/vfa.py): `vfa.py`
- [VFA1 archives](https://github.com/vulpfin/vfa/blob/main/vfa.py): `vfa.py`
- [VFA2 writer](https://github.com/vulpfin/vfa/blob/main/vfa2.py): `vfa2.py`
- [Archive extraction](https://github.com/vulpfin/vfa/blob/main/vfa_extract.py): `vfa_extract.py`
- [VFA2 reading](https://github.com/vulpfin/vfa/blob/main/vfa2.py): `vfa2.py`
- [File metadata](https://github.com/vulpfin/vfa/blob/main/vfa.py): `vfa.py`
- [Archive security](https://github.com/vulpfin/vfa/blob/main/vfa.py): `vfa.py`

### VFA2 codecs

- [Filters and chunking](https://github.com/vulpfin/vfa/blob/main/vfa2.py): `vfa2.py`
- [Python reference codec](https://github.com/vulpfin/vfa/blob/main/vulp_ref.py): `vulp_ref.py`

### Browse and install

- [Archive viewer](https://github.com/vulpfin/vfa/blob/main/vfa_viewer.py): `vfa_viewer.py`
- [SFX launcher](https://github.com/vulpfin/vfa/blob/main/sfx_stub.py): `sfx_stub.py`
- [Installer stub](https://github.com/vulpfin/vfa/blob/main/sfi_stub.py): `sfi_stub.py`
- [Installer wizard](https://github.com/vulpfin/vfa/blob/main/sfi_gui.py): `sfi_gui.py`
- [Version reporting](https://github.com/vulpfin/vfa/blob/main/vfa_version.py): `vfa_version.py`

### Native codec

- [tANS codec](https://github.com/vulpfin/vfa/blob/main/vulp/vulp.c): `vulp/vulp.c`
- [Vulp LZ codec](https://github.com/vulpfin/vfa/blob/main/vulp/vulp_lz.c): `vulp/vulp_lz.c`
- [Context mixer](https://github.com/vulpfin/vfa/blob/main/vulp/vulp_cm.c): `vulp/vulp_cm.c`
- [Codec API](https://github.com/vulpfin/vfa/blob/main/vulp/vulp.h): `vulp/vulp.h`

### Other components

- **Archive user**

## Connections

- Archive user → VFA CLI: invokes (evidence: `README.md`)
- VFA CLI → VFA1 archives: creates or appends (evidence: `README.md`)
- VFA CLI → VFA2 writer: selects VFA2 (evidence: `README.md`)
- VFA CLI → Archive extraction: extracts via (evidence: `vfa.py`)
- VFA CLI → VFA2 reading: dispatches VFA2 (evidence: `vfa.py`)
- VFA2 writer → Filters and chunking: chunks and filters (evidence: `vfa2.py`)
- VFA2 reading → Filters and chunking: reverses filters (evidence: `vfa2.py`)
- VFA2 writer → Python reference codec: uses fallback codec (evidence: `vfa2.py`)
- VFA2 reading → Python reference codec: uses fallback codec (evidence: `vfa2.py`)
- Codec API → tANS codec: declares API (evidence: `vulp/vulp.h`)
- Codec API → Vulp LZ codec: declares API (evidence: `vulp/vulp.h`)
- Codec API → Context mixer: declares API (evidence: `vulp/vulp.h`)
- Archive user → Archive viewer: browses archives (evidence: `README.md`)
- Archive viewer → Archive extraction: uses extraction (evidence: `vfa_viewer.py`)
- SFX launcher → Archive extraction: extracts payload (evidence: `sfx_stub.py`)
- Installer stub → Archive extraction: extracts payload (evidence: `sfi_stub.py`)
- Installer stub → Installer wizard: opens GUI (evidence: `sfi_stub.py`)
- VFA CLI → File metadata: preserves metadata (evidence: `README.md`)
- VFA CLI → Archive security: supports encryption (evidence: `README.md`)
- VFA CLI → Version reporting: reports version (evidence: `vfa.py`)