# rails/solid_cache architecture

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

- Interactive diagram: https://gitdiagram.com/rails/solid_cache
- Repository: https://github.com/rails/solid_cache

## Overview

##### Main Components
- Cache Engine & Configuration: At the heart is the Solid Cache engine (found in lib/solid_cache and app/models/solid_cache) that integrates into Rails as a cache store (configurable in the environment, e.g., production.rb via “config.cache_store = :solid_cache_store”). Also include the configurations (config/cache.yml or config/solid_cache.yml) which drive options like max_age, max_size, shards, encryption, etc.
- Cache Data Models: The engine uses ActiveRecord models (e.g., SolidCache::Entry and related sub-components that handle encryption, expiration, and size estimation) to maintain cache entries in a database table.
- Database Connections & Sharding: The project supports connecting to one or multiple cache databases (configured via “database”, “databases”, or “connects_to”), and employs Maglev consistent hashing for sharding (see lib/solid_cache/connections, with separate classes for “sharded”, “single”, and “unmanaged” connections).
- Cache Expiry Mechanism: Solid Cache employs a FIFO strategy and includes an expiration mechanism that is triggered either in a background thread or as an Active Job (SolidCache::ExpiryJob) when a write threshold is met. This component is key for cache management.
- Installation & Generators: There’s also a generator component (lib/generators/solid_cache/install) that sets up initial configuration files and a database schema (e.g., db/cache_schema.rb) when installing the gem in a Rails application.

##### Relationships & Interactions
- When the application writes to the cache (through the ActiveSupport interface), it translates those calls into operations on the Solid Cache entry models stored in the database.
- The cache engine communicates with the database(s), using configuration settings that can point to multiple shards – so represent directional data flows from the cache store component to one or more database instances.
- When writes trigger a counter threshold, a background job or thread (depending on configuration) is triggered to purge expired cache entries.
- The encryption and serialization modules are used as layers between the cache entries and their stored representations (as seen in lib/solid_cache/entry/encryption.rb and related files).

##### Important Architectural Patterns & Design Principles
- Separation of Concerns: The architecture clearly divides responsibilities among configuration, data access (ActiveRecord models), background processing (jobs vs. threads), and connection management.
- Extensible Configuration: It leverages Rails conventions by using initializer/generator scripts to set up the environment and connecting to database shards when necessary.
- Modular Design: Each concern (encryption, expiration, database connection, sharding) has its own module/subdirectory under lib/solid_cache, simplifying testing and maintenance.
- Consistency & Sharding: Use of Maglev consistent hashing to distribute cache load evenly across several database shards.

##### Technologies & Frameworks
- Ruby on Rails (ActiveRecord, ActiveSupport, Rails engine, and ActiveJob).
- Background job processing (with configurable queues for expiry tasks).
- Database systems (SQLite for development; MySQL, PostgreSQL, or other production-grade DBs via configuration).
- Optional integration with Active Record Encryption for cache value encryption.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Rails Application Layer"
        RailsApp["Rails Application (config.cache_store = :solid_cache_store)"]:::config
    end

    subgraph "Solid Cache Engine"
        EngineCore["Solid Cache Engine Core"]:::engine
        StoreAPI["Cache Store API"]:::engine
        EntryModels["Cache Entry Models"]:::model
        Encryption["Encryption Module"]:::model
        Expiration["Expiration Module"]:::model
        Size["Size Estimation"]:::model
    end

    subgraph "Cache Configuration"
        ConfigFiles["Cache Configuration Files"]:::config
    end

    subgraph "Database Connections & Sharding"
        ConnManager["Database Connection Manager"]:::engine
        Shard1["cache_shard1"]:::database
        Shard2["cache_shard2"]:::database
    end

    subgraph "Background Processing"
        ExpiryJob["SolidCache::ExpiryJob / Background Thread"]:::background
    end

    subgraph "Installation & Generators"
        InstallGen["Install Generator"]:::config
        DBSchema["Database Schema Template"]:::config
    end

    %% Connections
    RailsApp -->|"CacheCalls"| EngineCore
    EngineCore -->|"Uses"| EntryModels
    EngineCore -->|"API_Operations"| StoreAPI
    EngineCore -->|"ReadsConfig"| ConfigFiles
    EngineCore -->|"ManagesDBConnections"| ConnManager
    EntryModels -->|"EncryptionLayer"| Encryption
    EntryModels -->|"ExpirationLogic"| Expiration
    EntryModels -->|"SizeEstimation"| Size
    ConnManager -->|"Shards"| Shard1
    ConnManager -->|"Shards"| Shard2
    EngineCore -->|"Triggers"| ExpiryJob
    InstallGen -->|"GeneratesConfig"| ConfigFiles
    InstallGen -->|"GeneratesSchema"| DBSchema

    %% Click Events
    click EngineCore "https://github.com/rails/solid_cache/tree/main/lib/solid_cache"
    click StoreAPI "https://github.com/rails/solid_cache/blob/main/lib/solid_cache/store.rb"
    click ConfigFiles "https://github.com/rails/solid_cache/blob/main/lib/generators/solid_cache/install/templates/config/cache.yml.tt"
    click EntryModels "https://github.com/rails/solid_cache/blob/main/app/models/solid_cache/entry.rb"
    click Encryption "https://github.com/rails/solid_cache/blob/main/app/models/solid_cache/entry/encryption.rb"
    click Expiration "https://github.com/rails/solid_cache/blob/main/app/models/solid_cache/entry/expiration.rb"
    click Size "https://github.com/rails/solid_cache/blob/main/app/models/solid_cache/entry/size/estimate.rb"
    click ConnManager "https://github.com/rails/solid_cache/tree/main/lib/solid_cache/connections"
    click ExpiryJob "https://github.com/rails/solid_cache/blob/main/app/jobs/solid_cache/expiry_job.rb"
    click InstallGen "https://github.com/rails/solid_cache/tree/main/lib/generators/solid_cache/install"
    click DBSchema "https://github.com/rails/solid_cache/blob/main/lib/generators/solid_cache/install/templates/db/cache_schema.rb"

    %% Styles
    classDef config fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef engine fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef model fill:#90CAF9,stroke:#0D47A1,stroke-width:2px;
    classDef background fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px;
    classDef database fill:#E0E0E0,stroke:#757575,stroke-width:2px;

    class RailsApp,ConfigFiles,InstallGen,DBSchema config;
    class EngineCore,StoreAPI,ConnManager engine;
    class EntryModels,Encryption,Expiration,Size model;
    class ExpiryJob background;
    class Shard1,Shard2 database;
```
