chore: add docs

Author: MikaAK

guides/explanation/architecture.md

@@ -0,0 +1,94 @@
+# Architecture and Core Concepts
+
+This document explains the key architectural concepts behind ElixirCache and how its components work together.
+
+## Core Architecture
+
+ElixirCache is designed around a simple principle: provide a consistent interface to different caching backends. The architecture consists of:
+
+1. **Core Interface**: Defined by the `Cache` module
+2. **Adapters**: Backend-specific implementations
+3. **Term Encoder**: Handles serialization and compression
+4. **Telemetry Integration**: For observability and metrics
+5. **Sandbox System**: For isolated testing
+
+## The Cache Behaviour
+
+At the heart of ElixirCache is the `Cache` behaviour, which defines the contract that all cache adapters must implement:
+
+- `child_spec/1`: Defines how the cache is started and supervised
+- `opts_definition/0`: Defines adapter-specific options
+- `put/5`: Stores a value in the cache
+- `get/3`: Retrieves a value from the cache
+- `delete/3`: Removes a value from the cache
+
+Each adapter implements these functions, allowing your application code to remain the same regardless of which cache backend you use.
+
+## The `use Cache` Macro
+
+When you `use Cache` in your module, the macro:
+
+1. Sets up the configuration for your cache
+2. Creates the required module functions that delegate to the appropriate adapter
+3. Wraps operations in telemetry spans for metrics and observability
+4. Implements the `get_or_create/2` convenience function
+5. Adds sandboxing capabilities for testing if enabled
+
+## Term Encoding and Compression
+
+ElixirCache includes internal term encoding functionality that handles serialization and deserialization of Elixir terms. This allows you to store complex Elixir data structures in any cache backend. The encoding system:
+
+1. Uses Erlang's term_to_binary for efficient serialization
+2. Applies configurable compression to reduce memory usage
+3. Automatically handles decoding when retrieving values
+
+## Sandboxing for Tests
+
+A unique feature of ElixirCache is its sandboxing capability for tests. When you enable sandboxing:
+
+1. Each test has its own isolated cache namespace
+2. Cache operations are automatically prefixed with a test-specific ID
+3. Tests can run concurrently without cache interference or global overlap
+
+This is achieved through the `Cache.SandboxRegistry` which maintains a registry of cache contexts.
+
+## Adapters Design
+
+Each adapter is designed to be a thin wrapper around the underlying storage mechanism:
+
+### ETS Adapter
+
+The ETS adapter uses Erlang Term Storage for high-performance in-memory caching. It:
+- Starts an ETS table with the configured settings
+- Provides direct access to ETS-specific functions
+- Handles conversion between the Cache interface and ETS operations
+
+### DETS Adapter
+
+Similar to the ETS adapter but uses disk-based storage for persistence across restarts.
+
+### Redis Adapter
+
+The Redis adapter provides a more feature-rich distributed caching solution:
+- Manages a connection pool to Redis
+- Handles serialization of Elixir terms for Redis storage
+- Provides access to Redis-specific operations like hash and JSON commands
+
+### Agent Adapter
+
+A simple implementation using Elixir's Agent for lightweight in-memory storage.
+
+### ConCache Adapter
+
+Wraps the ConCache library to provide its expiration and callback capabilities.
+
+## Telemetry Integration
+
+ElixirCache provides telemetry events for all cache operations:
+- `[:elixir_cache, :cache, :put]` - When storing values
+- `[:elixir_cache, :cache, :get]` - When retrieving values
+- `[:elixir_cache, :cache, :get, :miss]` - When a key is not found
+- `[:elixir_cache, :cache, :delete]` - When deleting values
+- Error events when operations fail
+
+This allows you to monitor cache performance, hit/miss ratios, and error rates.

guides/how-to/choosing_adapter.md

@@ -0,0 +1,178 @@
+# How to Choose the Right Cache Adapter
+
+ElixirCache supports multiple cache adapters, each with its own strengths and use cases. This guide will help you choose the most appropriate adapter for your specific needs.
+
+## Available Adapters
+
+ElixirCache provides the following adapters:
+
+1. `Cache.ETS` - Erlang Term Storage
+2. `Cache.DETS` - Disk-based ETS
+3. `Cache.Redis` - Redis-backed distributed cache
+4. `Cache.Agent` - Simple Agent-based in-memory cache
+5. `Cache.ConCache` - ConCache wrapper
+6. `Cache.Sandbox` - Isolated cache for testing
+
+## Choosing an Adapter
+
+### Cache.ETS
+
+**Best for:**
+- High-performance in-memory caching
+- Single node applications
+- Low-latency requirements
+
+**Configuration example:**
+
+```elixir
+defmodule MyApp.Cache do
+  use Cache,
+    adapter: Cache.ETS,
+    name: :my_app_cache,
+    opts: [
+      read_concurrency: true,
+      write_concurrency: true
+    ]
+end
+```
+
+### Cache.DETS
+
+**Best for:**
+- Persistent caching across application restarts
+- Larger datasets that shouldn't be lost on restart
+- Less frequent access patterns
+
+**Configuration example:**
+
+```elixir
+defmodule MyApp.PersistentCache do
+  use Cache,
+    adapter: Cache.DETS,
+    name: :my_app_persistent_cache,
+    opts: [
+      file: "cache_data.dets"
+    ]
+end
+```
+
+### Cache.Redis
+
+**Best for:**
+- Distributed applications running on multiple nodes
+- Systems requiring shared cache across services
+- Applications needing advanced features like expiration, pub/sub, etc.
+
+**Configuration example:**
+
+```elixir
+defmodule MyApp.DistributedCache do
+  use Cache,
+    adapter: Cache.Redis,
+    name: :my_app_redis_cache,
+    opts: [
+      host: "localhost",
+      port: 6379,
+      pool_size: 5
+    ]
+end
+```
+
+### Cache.Agent
+
+**Best for:**
+- Simple use cases
+- Small applications
+- Development environments
+
+**Configuration example:**
+
+```elixir
+defmodule MyApp.SimpleCache do
+  use Cache,
+    adapter: Cache.Agent,
+    name: :my_app_simple_cache
+end
+```
+
+### Cache.ConCache
+
+**Best for:**
+- Applications already using ConCache
+- Needs for automatic key expiration and callback execution
+
+**Configuration example:**
+
+```elixir
+defmodule MyApp.ConCache do
+  use Cache,
+    adapter: Cache.ConCache,
+    name: :my_app_con_cache,
+    opts: [
+      ttl_check_interval: :timer.seconds(1),
+      global_ttl: :timer.minutes(10)
+    ]
+end
+```
+
+### Cache.Sandbox
+
+**Best for:**
+- Testing environments
+- Isolated tests that shouldn't interfere with each other
+
+**Configuration example:**
+
+```elixir
+defmodule MyApp.TestCache do
+  use Cache,
+    adapter: Cache.ETS,
+    name: :my_app_test_cache,
+    sandbox?: true
+end
+```
+
+## Switching Between Adapters
+
+One of the main benefits of ElixirCache is the ability to easily switch between adapters without changing your application code. You can use different adapters in different environments:
+
+```elixir
+defmodule MyApp.Cache do
+  use Cache,
+    adapter: get_adapter(),
+    name: :my_app_cache,
+    opts: get_opts()
+
+  defp get_adapter do
+    case Mix.env() do
+      :test -> Cache.Sandbox
+      :dev -> Cache.ETS
+      :prod -> Cache.Redis
+    end
+  end
+
+  defp get_opts do
+    case Mix.env() do
+      :test -> []
+      :dev -> [read_concurrency: true]
+      :prod -> [
+        host: System.get_env("REDIS_HOST", "localhost"),
+        port: String.to_integer(System.get_env("REDIS_PORT", "6379")),
+        pool_size: 10
+      ]
+    end
+  end
+end
+```
+
+## Performance Considerations
+
+When choosing an adapter, consider:
+
+1. **Access patterns** - How frequently are you reading vs writing?
+2. **Data volume** - How much data will be stored?
+3. **Persistence requirements** - Does the data need to survive restarts?
+4. **Distribution needs** - Will multiple nodes/services need access?
+5. **Complexity** - Do you need advanced features or simple key-value storage?
+
+Always benchmark different options with your specific workload to determine the best fit.