# open-cas/open-cas-linux architecture

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

- Interactive diagram: https://gitdiagram.com/open-cas/open-cas-linux
- Repository: https://github.com/open-cas/open-cas-linux

## Overview

##### Main system components
- Kernel Module & Cache Engine: Represent the core caching functionality implemented as a kernel module. This layer is built from various submodules (for example, the cas_cache code in the modules directory and cache logic that likely integrates with OCF libraries) and the configuration frameworks.
- Command-Line Tools and User-Space Utilities: Include the casadm directory (with its multiple C files and utilities) and the utilities in the utils directory (e.g., casctl). These provide the user and administrator interfaces to control the caching configuration and monitor or manage cache operations.
- Build, Configuration, and Packaging Infrastructure: Show the build scripts (Makefile, configure scripts, doc/requirements, tools for generating RPM/DEB packages) as a component that takes part in configuring, building, and deploying the system.
- Testing and Validation Framework: Indicate the extensive test suite directories (test/functional, test/smoke_test, test/utils_tests) that check the correctness, performance, and security of the cache system.
- External Libraries and Dependencies: Note that the system uses a safe string library (located in casadm/safeclib) and also has Python dependencies (requirements.txt, test harness requirements).

##### Relationships and interactions
- Kernel module to storage devices so that it intercepts and manages I/O requests—caching “hot” data from slower backend (HDD/SSD) media onto fast flash devices.
- Relationship between the build/configuration components and both the kernel module and the user utilities. This demonstrates that configuration files and build scripts (like ./configure, Makefile, and package generators in the tools directory) are used to compile, test, and install the kernel module as well as associated user tools.

##### Architectural patterns and design principles
- Separation of Concerns: The caching layer is isolated from the user-space tools and from the packaging/build infrastructure.
- Modular Design: The presence of separate directories for the casadm tool, the caching module (modules/cas_cache) and utility scripts denote a modular approach.
- Integration between Kernel and User Space: The design leverages direct kernel integration (via a kernel module) along with external command utilities, ensuring transparency and minimal latency.
- Robustness and Testing: The extensive test suite (functional, smoke, and utils tests) reflects the emphasis on data integrity, performance under various loads, and security.

##### Technology stack
- Languages: C (for kernel module and utilities), Python (for testing and some automation scripts), and shell scripting for build and deployment.
- Dependency on Safeclib: The safe string operations library is an integral part of the casadm component.
- Packaging Tools: Scripts and make targets that produce RPM/DEB packages and integration with dracut/service setup.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% High-level external actor
    User["User/Administrator"]:::admin

    %% User Space Subgraph
    subgraph "User Space"
        Casadm["casadm CLI Tool"]:::user
        Casctl["casctl & Utilities"]:::user
    end

    %% Kernel Space Subgraph
    subgraph "Kernel Space"
        Kernel["Open CAS Kernel Module"]:::kernel
        Storage["Storage Devices"]:::kernel
    end

    %% Infrastructure Subgraph
    subgraph "Infrastructure"
        BuildPackaging["Build & Packaging"]:::build
        TestSuite["Test & Validation Suite"]:::test
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        SafeLib["Safe String Library"]:::external
        PythonDeps["Python Dependencies"]:::external
    end

    %% Connections
    User -->|"sends_commands"| Casadm
    User -->|"issues_commands"| Casctl

    Casadm -->|"configures"| Kernel
    Casctl -->|"manages"| Kernel

    Kernel -->|"caches_to"| Storage

    BuildPackaging -->|"builds"| Kernel
    BuildPackaging -->|"builds"| Casadm

    TestSuite -->|"validates"| Kernel
    TestSuite -->|"validates"| Casadm

    SafeLib -->|"integrates_with"| Casadm
    PythonDeps -->|"supports"| TestSuite

    %% Click Events
    click Kernel "https://github.com/open-cas/open-cas-linux/tree/master/modules/cas_cache"
    click Casadm "https://github.com/open-cas/open-cas-linux/tree/master/casadm directory"
    click Casctl "https://github.com/open-cas/open-cas-linux/tree/master/utils directory"
    click BuildPackaging "https://github.com/open-cas/open-cas-linux/tree/master/Makefile"
    click BuildPackaging "https://github.com/open-cas/open-cas-linux/tree/master/configure"
    click BuildPackaging "https://github.com/open-cas/open-cas-linux/blob/master/configure.d"
    click BuildPackaging "https://github.com/open-cas/open-cas-linux/tree/master/tools directory"
    click TestSuite "https://github.com/open-cas/open-cas-linux/tree/master/test directory"
    click SafeLib "https://github.com/open-cas/open-cas-linux/tree/master/casadm/safeclib"
    click PythonDeps "https://github.com/open-cas/open-cas-linux/blob/master/requirements.txt"

    %% Styles
    classDef kernel fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef user fill:#ccf2ff,stroke:#006699,stroke-width:2px;
    classDef build fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef test fill:#fff2cc,stroke:#cc9900,stroke-width:2px;
    classDef external fill:#ffd9b3,stroke:#ff8000,stroke-width:2px;
    classDef admin fill:#d9ccff,stroke:#663399,stroke-width:2px;
```
