# clockworksspheres/ramdisk architecture

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

- Interactive diagram: https://gitdiagram.com/clockworksspheres/ramdisk
- Repository: https://github.com/clockworksspheres/ramdisk

## Overview

##### Project type and purpose
- This is a cross-platform Python library (with CLI entrypoints and examples) for setting up and managing RAM-backed disks on macOS, Linux, and (eventually) Windows. Its primary use cases are DevOps automation, build pipelines, and unit-testing on a clean, fast temporary filesystem to avoid “cache poisoning.”

##### File structure
- Top-level:
- README.md, pyenv-notes.md – project overview
- src/ramdisk – core package implementing ramdisk API and platform factory
- src/ramdisk/lib – helper submodules (fsHelper, getLibc, manage_keychain, manage_user(s), logging, command runner, etc.)
- src/examples – demonstration scripts
- src/tests – unit tests and generic test utilities
- src/proto – placeholder for future protocol or interface definitions
- run_tests.py, clean.sh – build/test tooling scripts
- Architectural patterns:
- Factory (ramdiskFactory chooses correct subclass at runtime based on OS)
- Strategy (platform-specific implementations: macRamdisk, linuxLoopRamdisk, linuxTmpfsRamdisk, winImDiskRamdisk)
- Layering (core API layer, subcomponent library layer, platform implementations, CLI/examples/test layers)

##### Extract insights from the README
- Core components: RamDisk class, platform adapters, user/keychain management, filesystem helpers
- Notes on Python versions, OS restrictions, branching strategy (dev vs. master)
- Examples and “future work” outline

##### Main components
a. Core API Layer
- RamdiskFactory (entrypoint)
- Ramdisk (abstract interface)
b. Platform Implementations
- macRamdisk
- linuxLoopRamdisk
- linuxTmpfsRamdisk
- winImDiskRamdisk (stubbed/future)
c. Subcomponent Library Layer
- fsHelper (apfsfsHelper, hfsFsHelper, linuxFsHelper, etc.)
- getLibc (OS-specific libc locators)
- manage_keychain (macOS keychain management)
- manage_user(s) (per-OS user management)
- run_commands / run_communicate (shell invocation)
- logdispatcher_lite, loggers, spinners, versionstamp (logging & instrumentation)
d. CLI / Script Layer
- clean.sh, run_tests.py
- src/examples (menu.py, setup_ramdisk_example.py, etc.)
e. Test Layer
- Unit tests under src/tests
- GenericTestUtilities

##### Relationships and interactions
- User or CI script ➔ invokes CLI script or directly imports RamdiskFactory
- RamdiskFactory detects OS ➔ returns appropriate Ramdisk subclass
- Subclass calls subcomponents:
- fsHelper to create/mount filesystems
- getLibc to locate runtime libs
- manage_user/ manage_keychain for permissions
- run_commands to execute system calls
- logging modules to record events
- Examples and tests exercise the core API and subcomponents

##### Important architectural patterns
- Factory + Strategy for platform abstraction
- Layered design separating core logic from OS-specific and utility modules
- Dependency injection via modular helper libraries
- Clear separation of production code, examples, and tests

##### Essential elements
- Clear labels on every component
- Script ➔ Factory ➔ Implementation ➔ Subcomponent

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI / Examples / Tests Layer
    subgraph "CLI / Examples / Tests"
        direction TB
        Clean["clean.sh"]:::scripts
        RunTests["run_tests.py"]:::scripts
        Examples["src/examples"]:::scripts
        Tests["src/tests"]:::scripts
    end

    %% Core API Layer
    subgraph "Core API" 
        direction TB
        Factory["RamdiskFactory"]:::core
        Interface["Ramdisk (abstract)"]:::core
        Template["commonRamdiskTemplate"]:::core
        Config["config"]:::core
    end

    %% Platform Implementations
    subgraph "Platform Implementations"
        direction TB
        Mac["macRamdisk"]:::platform
        LinuxLoop["linuxLoopRamdisk"]:::platform
        LinuxTmpfs["linuxTmpfsRamdisk"]:::platform
        WinStub["winImDiskRamdisk"]:::platformDashed
    end

    %% Utility Libraries
    subgraph "Utilities"
        direction TB
        FsHelper["fsHelper"]:::util
        GetLibc["getLibc"]:::util
        Keychain["manage_keychain"]:::util
        UserMgmt["manage_user"]:::util
        UsersAgg["manage_users"]:::util
        Commands["run_commands / run_communicate"]:::util
        Logging["logging & instrumentation"]:::util
        Misc["misc helpers"]:::util
    end

    %% Connections
    Clean -->|invokes| Factory
    RunTests -->|invokes| Factory
    Examples -->|imports| Factory
    Tests -->|tests| Interface

    Factory -->|returns| Mac
    Factory -->|returns| LinuxLoop
    Factory -->|returns| LinuxTmpfs
    Factory -->|returns| WinStub

    Factory --> Interface
    Factory --> Template
    Factory --> Config

    Mac --> FsHelper
    Mac --> GetLibc
    Mac --> Keychain
    Mac --> UserMgmt
    Mac --> Commands
    Mac --> Logging
    Mac --> Misc

    LinuxLoop --> FsHelper
    LinuxLoop --> GetLibc
    LinuxLoop --> UserMgmt
    LinuxLoop --> Commands
    LinuxLoop --> Logging

    LinuxTmpfs --> FsHelper
    LinuxTmpfs --> GetLibc
    LinuxTmpfs --> UserMgmt
    LinuxTmpfs --> Commands
    LinuxTmpfs --> Logging

    WinStub -.-> FsHelper
    WinStub -.-> GetLibc
    WinStub -.-> UserMgmt
    WinStub -.-> Commands

    %% Click Events
    click Factory "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/ramdiskFactory.py"
    click Interface "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/ramdisk.py"
    click Template "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/commonRamdiskTemplate.py"
    click Config "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/config.py"
    click Mac "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/macRamdisk.py"
    click LinuxLoop "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/linuxLoopRamdisk.py"
    click LinuxTmpfs "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/linuxTmpfsRamdisk.py"
    click WinStub "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/winImDiskRamdisk.py"
    click FsHelper "https://github.com/clockworksspheres/ramdisk/tree/master/src/ramdisk/lib/fsHelper/"
    click GetLibc "https://github.com/clockworksspheres/ramdisk/tree/master/src/ramdisk/lib/getLibc/"
    click Keychain "https://github.com/clockworksspheres/ramdisk/tree/master/src/ramdisk/lib/manage_keychain/"
    click UserMgmt "https://github.com/clockworksspheres/ramdisk/tree/master/src/ramdisk/lib/manage_user/"
    click UsersAgg "https://github.com/clockworksspheres/ramdisk/tree/master/src/ramdisk/lib/manage_users/"
    click Commands "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/run_commands.py"
    click Commands "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/run_communicate.py"
    click Logging "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/logdispatcher_lite.py"
    click Logging "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/loggers.py"
    click Logging "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/spinners.py"
    click Logging "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/versionstamp.py"
    click Logging "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/log_message.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/CheckApplicable.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/PlatformFoundErrors.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/composite_menu.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/environment.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/localize.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/libHelperFunctions.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/libHelperExceptions.py"
    click Misc "https://github.com/clockworksspheres/ramdisk/blob/master/src/ramdisk/lib/singleton.py"

    click Clean "https://github.com/clockworksspheres/ramdisk/blob/master/src/clean.sh"
    click RunTests "https://github.com/clockworksspheres/ramdisk/blob/master/src/run_tests.py"
    click Examples "https://github.com/clockworksspheres/ramdisk/tree/master/src/examples/"
    click Tests "https://github.com/clockworksspheres/ramdisk/tree/master/src/tests/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef platform fill:#d4edda,stroke:#155724,color:#155724
    classDef platformDashed fill:#d4edda,stroke:#155724,color:#155724,stroke-dasharray: 5 5
    classDef util fill:#fff3cd,stroke:#856404,color:#856404
    classDef scripts fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef platformDashed platform
    class Factory,Interface,Template,Config core
    class Mac,LinuxLoop,LinuxTmpfs,WinStub platform
    class FsHelper,GetLibc,Keychain,UserMgmt,UsersAgg,Commands,Logging,Misc util
    class Clean,RunTests,Examples,Tests scripts
```
