# fitzgen/safe-gc architecture

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

- Interactive diagram: https://gitdiagram.com/fitzgen/safe-gc
- Repository: https://github.com/fitzgen/safe-gc

## Overview

##### Project type and purpose
- This is a Rust library implementing a garbage collector that is completely safe (i.e. without any unsafe code). Its primary purpose is to allow users to allocate and manage memory safely in Rust via a GC heap.

##### File structure for architectural components
- Top-level directories include:
- “src”: Contains the core library code (e.g., free_list.rs, mark_bits.rs, lib.rs) which likely implement the low-level memory management and GC algorithms.
- “crates/mutator”: Likely a separate crate/module that provides additional functionality (perhaps an API extension or mutation logic) for the main GC library, with its own Cargo.toml and source code.
- “fuzz”: Contains fuzz testing code (e.g., mutator.rs) and its own configuration; this shows an infrastructure for robustness and testing of the GC logic.
- “.github”: Contains CI configuration (GitHub workflows) to ensure code quality and build status.
- There are also top-level Cargo.toml and license files which indicate that this is a properly packaged library with multiple components (or sub-crates) in a workspace.

##### Key components to highlight
a. GC Core Library:
- Components from “src” such as the main library (lib.rs) and support modules (free_list.rs, mark_bits.rs) that implement the heap, memory allocation, and garbage collection logic.
- The “Trace” trait implementations and the use of types like Gc<T>, Heap, Collector and Root<T> as described in the README.
b. Mutator Crate:
- Additional functionality provided by the “crates/mutator” crate. Explain its relationship with the core GC library (likely an extension or experimental component).
c. Fuzz Testing Framework:
- The “fuzz” directory which houses fuzz tests (mutator.rs) should be shown as a separate component interacting with the core library to validate the GC logic.
d. External Integration:
e. CI Infrastructure:

##### Relationships and interactions
- Within the GC core component, show the relationship between:
- Heap creation and allocation modules.
- The Collector component that scans and reclaims unreachable objects.
- The Trace mechanism where user-defined types implement the Trace trait.
- From the Mutator crate, illustrate how it either augments or tests mutation aspects within the GC system.
- From the fuzz testing block, demonstrate the feedback loop where fuzz tests interact with the GC core to catch potential errors.

##### Architectural patterns and design principles
- Design’s safe-by-design principle; note that the entire GC library is implemented in safe Rust with no use of unsafe code.
- That the system supports multiple independent heaps and heterogeneous object types.
- Modularity by showing different modules (core, mutator, testing) as separate, well-defined components that follow the separation of concerns principle.

##### Final elements to be present
- Clear labels for each component (GC Core, Mutator Crate, Fuzz Tests, CI Workflow, Client API).

## Diagram (Mermaid)

```mermaid
graph TD
    CLIENT["Client Code (User Application)"]:::client

    subgraph "GC Core Library"
        direction TB
        ALLOCATION["Memory Allocation (src/free_list.rs)"]:::core
        TRACING["Object Tracing (src/lib.rs)"]:::core
        MARKBITS["Mark Bits (src/mark_bits.rs)"]:::core
        COLLECTOR["Collector & Heap Management"]:::core
    end

    MUTATOR["Mutator Crate"]:::mutator
    FUZZ["Fuzz Testing Framework"]:::testing
    CI["CI Workflow"]:::ci

    CLIENT -->|"allocates"| ALLOCATION
    CLIENT -->|"triggers"| COLLECTOR

    ALLOCATION -->|"provides_memory"| COLLECTOR
    TRACING -->|"implements_trace"| COLLECTOR
    MARKBITS -->|"supports_tracing"| COLLECTOR

    MUTATOR -->|"augments"| COLLECTOR
    FUZZ -->|"validates"| COLLECTOR

    CI -->|"runs_tests_on"| CLIENT
    CI -->|"runs_tests_on"| MUTATOR
    CI -->|"runs_tests_on"| FUZZ

    click ALLOCATION "https://github.com/fitzgen/safe-gc/blob/main/src/free_list.rs"
    click TRACING "https://github.com/fitzgen/safe-gc/blob/main/src/lib.rs"
    click MARKBITS "https://github.com/fitzgen/safe-gc/blob/main/src/mark_bits.rs"
    click MUTATOR "https://github.com/fitzgen/safe-gc/tree/main/crates/mutator"
    click FUZZ "https://github.com/fitzgen/safe-gc/tree/main/fuzz"
    click CI "https://github.com/fitzgen/safe-gc/blob/main/.github/workflows/rust.yml"

    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#aeeaff,stroke:#333,stroke-width:2px;
    classDef mutator fill:#c8e6c9,stroke:#333,stroke-width:2px;
    classDef testing fill:#fff9c4,stroke:#333,stroke-width:2px;
    classDef ci fill:#f8bbd0,stroke:#333,stroke-width:2px;
```
