# katherindominguez/symmetric-multialgorithm-compressor-x86 architecture

> Architecture diagram of the GitHub repository katherindominguez/symmetric-multialgorithm-compressor-x86, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/katherindominguez/symmetric-multialgorithm-compressor-x86
- Repository: https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86

## Overview

1. **Project shape**
   - This is a **single executable** (`compresor.exe`) built from **C + x86-64 assembly**.
   - The architecture is not client/server or layered web; it is a **desktop console application** with one main interactive flow: compress, decompress, exit.

2. **Top-level control**
   - `src/c/main.c` is the entry point.
   - `src/c/ui.c` drives the menu and user prompts.
   - The UI is the first boundary visible to the user; everything else hangs off menu actions.

3. **Main runtime flow**
   - User chooses **compress** or **decompress**.
   - The app reads a file, processes it with the selected algorithm, writes an output file, then computes and displays statistics.
   - The overall flow is: **UI → file I/O → algorithm engine → output file → stats/UI**.

4. **File I/O and metadata layer**
   - `src/c/archivos.c` handles reading and writing raw file bytes.
   - It also supports the project’s compressed-file envelope: signature, original extension, original size, compressed size, and payload.
   - This layer is the boundary between the filesystem and the codec logic.

5. **Compression engine split across C and ASM**
   - The heavy compression work lives in `src/asm/compresor.asm`, with algorithm-specific assembly files:
     - `src/asm/compresor_rle.asm`
     - `src/asm/compresor_huffman.asm`
   - The project supports two codecs:
     - **RLE** for repeated runs
     - **Huffman** for entropy-based compression
   - The assembly layer is the performance-critical core of the repository.

6. **Huffman-specific pipeline**
   - `src/c/huffman.c` builds the Huffman tree/table in C.
   - The tree/frequency metadata is then consumed by the Huffman compression/decompression path.
   - This means Huffman is **split**: tree construction in C, bitstream processing in assembly.

7. **Decompression pipeline**
   - `src/c/descompresor.c` reads the compressed container, validates the signature, restores metadata, and dispatches to the proper decoder.
   - It supports both `.rle` and `.huff` payloads.
   - The decompressor is responsible for restoring the original file bytes and original extension.

8. **Statistics subsystem**
   - `src/c/estadisticas.c` formats compression metrics for the UI.
   - `src/asm/fpu_stats.asm` performs numeric work with the **x87 FPU**.
   - Metrics include compression ratio, space savings, and throughput in KB/s.
   - This is a separate subsystem from the codec itself: it observes results, it does not transform file data.

9. **Memory management boundary**
   - `src/asm/memoria.asm` encapsulates memory allocation using **Windows VirtualAlloc**.
   - This suggests the app uses explicit large-buffer management rather than relying only on C heap behavior.
   - Memory allocation is therefore a platform-specific low-level service used by the compression pipeline.

10. **ABI contract between modules**
   - `include/contratos.h` defines the interface contract between C and assembly modules.
   - The repo explicitly targets the **Windows x64 calling convention**: RCX/RDX/R8/R9 for integer args, XMM0–XMM3 for floats, RAX for return, with callee-saved register rules.
   - This file is a key architectural boundary: it keeps the mixed-language modules interoperable.

11. **Output file format as an architectural artifact**
   - Compressed files are not raw codec output; they are wrapped in a small header.
   - The header stores:
     - file signature (`HUFF` or `RLE_`)
     - original extension
     - original size
     - compressed data size
     - payload
   - This format is what lets decompression reconstruct the original file name/type and verify validity.

12. **Testing and substitution**
   - `stubs/` contains stub assembly modules for memory, compression, and FPU behavior.
   - These are likely used to isolate parts of the system during integration or grading.
   - Architecturally, they act as drop-in replacements for the assembly-heavy subsystems.

13. **Build/tooling boundary**
   - The project is built with **MinGW-w64**, **NASM**, and **Make**.
   - That matters architecturally because the runtime is Windows-targeted and the implementation depends on an assembler/compiler toolchain that can link C and NASM objects together.

14. **Best diagram summary**
   - Draw one central application boundary with:
     - **UI/Main**
     - **File I/O**
     - **Compression/Decompression engines**
     - **Huffman tree builder**
     - **Stats**
     - **Memory allocator**
   - Emphasize the **C ↔ ASM interface** as the main internal boundary, and the **file format header** as the main data-contract boundary.

Main entry points: [`src/c/descompresor.c`](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/descompresor.c) (Decompressor), [`src/asm/compresor.asm`](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/compresor.asm) (Core codec), [`src/c/ui.c`](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/ui.c) (UI), [`include/contratos.h`](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/include/contratos.h) (ABI contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main(("Main<br/>entrypoint C<br/>[main.c]"))
  node_ui["UI<br/>menu flow<br/>[ui.c]"]
end

subgraph group_io["File boundary"]
  node_files["File I/O<br/>container I/O<br/>[archivos.c]"]
  node_container["File header<br/>format contract<br/>[archivos.h]"]
end

subgraph group_codec["Compression core"]
  node_compressor{{"Core codec<br/>asm dispatcher<br/>[compresor.asm]"}}
  node_rle["RLE core<br/>asm codec<br/>[compresor_rle.asm]"]
  node_huffcore["Huffman core<br/>asm bitstream"]
  node_huffman["Huffman tree<br/>C builder<br/>[huffman.c]"]
  node_decomp["Decompressor<br/>C dispatcher<br/>[descompresor.c]"]
end

subgraph group_stats["Statistics"]
  node_statsui["Stats UI<br/>metrics formatter<br/>[estadisticas.c]"]
  node_fpu{{"FPU stats<br/>asm math<br/>[fpu_stats.asm]"}}
end

subgraph group_platform["Platform services"]
  node_mem[("Memory<br/>alloc service<br/>[memoria.asm]")]
  node_contract["ABI contract<br/>C/ASM interface<br/>[contratos.h]"]
end

subgraph group_support["Support"]
  node_stubasm["ASM stubs<br/>test doubles<br/>[stub_compresor.asm]"]
  node_stubfpu["FPU stub<br/>test double<br/>[stub_fpu.asm]"]
  node_stubmem["Mem stub<br/>test double<br/>[stub_memoria.asm]"]
end

node_main -->|"starts"| node_ui
node_ui -->|"selects file"| node_files
node_ui -->|"compress"| node_compressor
node_ui -->|"decompress"| node_decomp
node_files -->|"wraps/unwraps"| node_container
node_compressor -->|"dispatches"| node_rle
node_compressor -->|"dispatches"| node_huffcore
node_huffman -->|"feeds tables"| node_huffcore
node_decomp -->|"validates"| node_container
node_decomp -->|"decodes"| node_rle
node_decomp -->|"decodes"| node_huffcore
node_decomp -->|"writes output"| node_files
node_compressor -->|"allocates"| node_mem
node_decomp -->|"allocates"| node_mem
node_statsui -->|"computes"| node_fpu
node_ui -->|"shows stats"| node_statsui
node_contract -.->|"defines ABI"| node_compressor
node_contract -.->|"defines ABI"| node_huffcore
node_contract -.->|"defines ABI"| node_fpu
node_contract -.->|"defines ABI"| node_mem
node_stubasm -.->|"replaces"| node_compressor
node_stubfpu -.->|"replaces"| node_fpu
node_stubmem -.->|"replaces"| node_mem

click node_main "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/main.c"
click node_ui "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/ui.c"
click node_files "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/archivos.c"
click node_container "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/archivos.h"
click node_compressor "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/compresor.asm"
click node_rle "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/compresor_rle.asm"
click node_huffcore "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/compresor_huffman.asm"
click node_huffman "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/huffman.c"
click node_decomp "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/descompresor.c"
click node_statsui "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/estadisticas.c"
click node_fpu "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/fpu_stats.asm"
click node_mem "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/memoria.asm"
click node_contract "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/include/contratos.h"
click node_stubasm "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/stubs/stub_compresor.asm"
click node_stubfpu "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/stubs/stub_fpu.asm"
click node_stubmem "https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/stubs/stub_memoria.asm"

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_main,node_ui toneBlue
class node_files,node_container toneAmber
class node_compressor,node_rle,node_huffcore,node_huffman,node_decomp toneMint
class node_statsui,node_fpu toneRose
class node_mem,node_contract toneIndigo
class node_stubasm,node_stubfpu,node_stubmem toneTeal
```

## Components

### Application

Console app entrypoint, menu flow, and orchestration

- [Main](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/main.c): entrypoint C · Program entry and top-level dispatch · `src/c/main.c`
- [UI](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/ui.c): menu flow · Interactive prompts and user choice handling · `src/c/ui.c`

### File boundary

Raw file access and compressed container format

- [File I/O](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/archivos.c): container I/O · Reads raw bytes and writes compressed or restored files · `src/c/archivos.c`
- [File header](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/archivos.h): format contract · Signature, extension, size metadata, and payload envelope · `src/c/archivos.h`

### Compression core

Compression and decompression engines across C and assembly

- [Core codec](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/compresor.asm): asm dispatcher · Routes compression work to the selected algorithm core · `src/asm/compresor.asm`
- [RLE core](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/compresor_rle.asm): asm codec · Run-length compression and decompression routines · `src/asm/compresor_rle.asm`
- [Huffman core](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/compresor_huffman.asm): asm bitstream · Huffman compression and decompression bitstream logic · `src/asm/compresor_huffman.asm`
- [Huffman tree](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/huffman.c): C builder · Builds Huffman tree and tables for codec use · `src/c/huffman.c`
- [Decompressor](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/descompresor.c): C dispatcher · Validates container metadata and restores original bytes · `src/c/descompresor.c`

### Statistics

Post-processing metrics and numeric helpers

- [Stats UI](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/c/estadisticas.c): metrics formatter · Formats compression metrics for display · `src/c/estadisticas.c`
- [FPU stats](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/fpu_stats.asm): asm math · Numeric helpers for ratios and throughput calculations · `src/asm/fpu_stats.asm`

### Platform services

Low-level memory and ABI contract between C and assembly

- [Memory](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/src/asm/memoria.asm): alloc service · VirtualAlloc-based buffer management · `src/asm/memoria.asm`
- [ABI contract](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/include/contratos.h): C/ASM interface · Windows x64 calling convention and module contracts · `include/contratos.h`

### Support

Stub modules for replacement or isolation

- [ASM stubs](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/stubs/stub_compresor.asm): test doubles · Replacement modules for compression, FPU, and memory · `stubs/stub_compresor.asm`
- [FPU stub](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/stubs/stub_fpu.asm): test double · Stubbed numeric routines for isolation · `stubs/stub_fpu.asm`
- [Mem stub](https://github.com/katherindominguez/symmetric-multialgorithm-compressor-x86/blob/main/stubs/stub_memoria.asm): test double · Stubbed allocator for isolation · `stubs/stub_memoria.asm`

## Connections

- Main → UI: starts · Main launches the interactive menu flow
- UI → File I/O: selects file · User actions trigger reads and writes
- UI → Core codec: compress · Compression requests enter the codec engine
- UI → Decompressor: decompress · Decompression requests enter the restore path
- File I/O → File header: wraps/unwraps · File I/O uses the compressed container header format
- Core codec → RLE core: dispatches · Core codec selects RLE routines when appropriate
- Core codec → Huffman core: dispatches · Core codec selects Huffman routines when appropriate
- Huffman tree → Huffman core: feeds tables · C builds Huffman metadata consumed by assembly
- Decompressor → File header: validates · Decompression checks signature and restores metadata
- Decompressor → RLE core: decodes · RLE payloads are restored through the RLE path
- Decompressor → Huffman core: decodes · Huffman payloads are restored through the Huffman path
- Decompressor → File I/O: writes output · Restored bytes are written back to disk
- Core codec → Memory: allocates · Compression pipeline uses low-level buffers
- Decompressor → Memory: allocates · Decompression pipeline uses low-level buffers
- Stats UI → FPU stats: computes · Metrics rely on numeric helpers in assembly
- UI → Stats UI: shows stats · UI presents compression results to the user
- ABI contract → Core codec: defines ABI · Shared calling convention for C and assembly modules
- ABI contract → Huffman core: defines ABI · Shared calling convention for C and assembly modules
- ABI contract → FPU stats: defines ABI · Shared calling convention for C and assembly modules
- ABI contract → Memory: defines ABI · Shared calling convention for C and assembly modules
- ASM stubs → Core codec: replaces · Stub compressor can stand in for the real assembly core
- FPU stub → FPU stats: replaces · Stub numeric routines can stand in for the real FPU helpers
- Mem stub → Memory: replaces · Stub allocator can stand in for the real memory service
