# schovi/baked_file_system architecture

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

- Interactive diagram: https://gitdiagram.com/schovi/baked_file_system
- Repository: https://github.com/schovi/baked_file_system

## Overview

##### Main Components
- BakedFileSystem Core: Represent the core module (located in src/baked_file_system.cr) which defines the custom type and the macros (like bake_folder) that perform the static-file baking.
- Loader Module: From src/loader and its subcomponents (including loader/loader.cr and loader/string_encoder.cr), which likely handle the initialization, file retrieval, and possibly encoding/decoding or string handling for the baked files.
- Version Management: The version file (src/baked_file_system/version.cr) shows that the library maintains versioning information.
- Test Suite: The spec directory (with files like baked_file_system_spec.cr, loader_spec.cr, and string_encoder_spec.cr) indicates test-driven practices to verify correct behavior. Also, sample storage directories under spec/storage are used to mimic various file conditions (e.g., hidden files, empty directories, different file encodings).

##### Relationships and Interactions
- The Core is extended by client classes (as seen in the README example where a custom FileStorage class extends BakedFileSystem) to “bake” specified folders.
- At compile time, the macro processes the file system directories provided via bake_folder and embeds the file contents to be accessible later.
- At runtime, the Loader module is responsible for retrieving file data, handling errors (like NoSuchFileError), and providing file properties (such as content, path, and size).
- Testing components ensure that the baked contents, file retrieval, and error handling work as expected.

##### Architectural Patterns and Design Principles
- Compile-Time Code Generation: The macro “bake_folder” is the metaprogramming mechanism capturing the static assets during compilation.
- Modular Design: There is clear separation between core functionalities (baking, file management) and ancillary responsibilities (version management, file loading, encoding).
- Test-Driven Development: The presence of a comprehensive ‘spec’ directory implies an emphasis on verifying each architectural component.
- File Abstraction: The design abstracts file system operations such that the caller doesn’t need to know if the file is being loaded from disk or from the embedded resource.

##### Relevant Technologies and Frameworks
- Crystal Language: Based on file extensions (*.cr) and the shard.yml dependency manager, the project is built for the Crystal programming language.
- Git and GitHub: Shown by the .gitignore file, GitHub workflows, and contribution instructions.
- Build/Dependency Configuration: The shard.yml file plays an essential role in dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Compile-Time Stage"
        BF["BakedFileSystem Core\n(macro bake_folder)"]:::core
        DS["Baked Data Store"]:::core
        VM["Version Management"]:::core
        BF -->|"Embed_file_contents"| DS
        BF -->|"Includes_version_info"| VM
    end

    subgraph "Runtime Stage"
        CC["Client Code (extends BakedFileSystem)"]:::runtime
        LM["Loader Module"]:::runtime
        L["Loader"]:::runtime
        SE["StringEncoder"]:::runtime
        NE["NoSuchFileError"]:::runtime
        CC -->|"Uses_Core"| BF
        CC -->|"Request_file"| LM
        LM -->|"Retrieves_content"| DS
        LM --> L
        LM --> SE
        DS -->|"NotFound_triggers"| NE
    end

    subgraph "Test Suite"
        TS1["BakedFileSystem Spec"]:::test
        TS2["Loader Spec"]:::test
        TS3["StringEncoder Spec"]:::test
    end

    click BF "https://github.com/schovi/baked_file_system/blob/master/src/baked_file_system.cr"
    click VM "https://github.com/schovi/baked_file_system/blob/master/src/baked_file_system/version.cr"
    click L "https://github.com/schovi/baked_file_system/blob/master/src/loader/loader.cr"
    click SE "https://github.com/schovi/baked_file_system/blob/master/src/loader/string_encoder.cr"
    click TS1 "https://github.com/schovi/baked_file_system/blob/master/spec/baked_file_system_spec.cr"
    click TS2 "https://github.com/schovi/baked_file_system/blob/master/spec/loader_spec.cr"
    click TS3 "https://github.com/schovi/baked_file_system/blob/master/spec/string_encoder_spec.cr"

    classDef core fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef runtime fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef test fill:#90ee90,stroke:#333,stroke-width:2px;
```
