How katherindominguez/symmetric-multialgorithm-compressor-x86 works
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: descompresor.c Decompressor · compresor.asm Core codec · ui.c UI · contratos.h ABI contract
Components 16
Application
Console app entrypoint, menu flow, and orchestration
File boundary
Raw file access and compressed container format
- File I/O · Reads raw bytes and writes compressed or restored files
src/c/archivos.c - File header · Signature, extension, size metadata, and payload envelope
src/c/archivos.h
Compression core
Compression and decompression engines across C and assembly
- Core codec · Routes compression work to the selected algorithm core
src/asm/compresor.asm - RLE core · Run-length compression and decompression routines
src/asm/compresor_rle.asm - Huffman core · Huffman compression and decompression bitstream logic
src/asm/compresor_huffman.asm - Huffman tree · Builds Huffman tree and tables for codec use
src/c/huffman.c - Decompressor · Validates container metadata and restores original bytes
src/c/descompresor.c
Statistics
Post-processing metrics and numeric helpers
Platform services
Low-level memory and ABI contract between C and assembly
- Memory · VirtualAlloc-based buffer management
src/asm/memoria.asm - ABI contract · Windows x64 calling convention and module contracts
include/contratos.h
Connections 23
- 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