# square/ttcache architecture

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

- Interactive diagram: https://gitdiagram.com/square/ttcache
- Repository: https://github.com/square/ttcache

## Overview

##### Main Components

a) Core Components:
- TTCache Main Service
- Tag Management System
- Store Layer
- Return Directive System

b) Storage Implementations:
- Memcached Store
- Sharded Memcached Store
- Tagged Store

**┌─ Application Layer ─────────────────────────────────────┐**

- ┌─ Client Code ─┐                                     │
- Controllers   │                                     │
- Middleware    │                                     │
- ┘                                     │
- ↓                                           │
- ┌─ TTCache Core ──────────────────────────────┐     │

- ┌─ Tag Management ─┐  ┌─ Cache Control ─┐  │     │
- TagNode        │  │ - Remember      │  │     │
- TaggedValue    │  │ - Load         │  │     │
- TaggingKey     │  │ - Clear        │  │     │
- ┘  └───────────────┘  │     │
- ↓                   ↓          │     │
- ┌─ Tag Types ────┐  ┌─ Results ────┐   │     │
- HeritableTag │  │ - LoadResult │   │     │
- ShardingTag  │  │ - StoreResult│   │     │
- ┘  └──────────────┘   │     │
- ┘     │
- ↓                                       │
- ┌─ Store Layer ────────────────────────────┐    │
- ┌─ Store Implementations ─┐              │    │
- MemcachedStore       │              │    │
- ShardedMemcachedStore│  Interface   │    │
- TaggedStore          │              │    │
- ┘              │    │
- ┘     │
- ┘

##### Important Relationships to Highlight

a) Tag Tree Structure:
- How tags form a hierarchical structure
- How HeritableTag and ShardingTag extend the base tag system
- Demonstrate tag propagation through the cache hierarchy

b) Storage Layer:
- Relationship between different store implementations
- How the storage interface is implemented by different stores
- Connection between TaggedStore and other store implementations

##### Implementation Details

- Tag inheritance mechanism
- Sharding implementation
- Cache key generation and management
- Memory preloading functionality
- Error handling and result wrapping

##### Notes

- Keep the main TTCache interface simple but show its powerful recursive capabilities
- Tag tree structure as it's the core concept
- How the caching system integrates with different storage backends
- Flexibility of the tagging system

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Application["Application Layer"]
        Client["Client Code"]
        
        subgraph Core["TTCache Core"]
            TTCache["TTCache Main Service"]:::core
            click TTCache "https://github.com/square/ttcache/blob/main/src/TTCache.php"
            
            subgraph TagMgmt["Tag Management"]
                TagNode["TagNode"]:::tag
                click TagNode "https://github.com/square/ttcache/blob/main/src/TagNode.php"
                TaggedValue["TaggedValue"]:::tag
                click TaggedValue "https://github.com/square/ttcache/blob/main/src/TaggedValue.php"
                TaggingKey["TaggingKey"]:::tag
                click TaggingKey "https://github.com/square/ttcache/blob/main/src/TaggingKey.php"
                Tags["Tags"]:::tag
                click Tags "https://github.com/square/ttcache/blob/main/src/Tags.php"
            end
            
            subgraph TagTypes["Tag Types"]
                TagInterface["Tag Interface"]:::interface
                click TagInterface "https://github.com/square/ttcache/blob/main/src/Tags/TagInterface.php"
                HeritableTag["Heritable Tag"]:::tag
                click HeritableTag "https://github.com/square/ttcache/blob/main/src/Tags/HeritableTag.php"
                ShardingTag["Sharding Tag"]:::tag
                click ShardingTag "https://github.com/square/ttcache/blob/main/src/Tags/ShardingTag.php"
            end
            
            subgraph Results["Results System"]
                Result["Result"]:::result
                click Result "https://github.com/square/ttcache/blob/main/src/Result.php"
                LoadResult["Load Result"]:::result
                click LoadResult "https://github.com/square/ttcache/blob/main/src/LoadResult.php"
                KnownMiss["Known Miss"]:::result
                click KnownMiss "https://github.com/square/ttcache/blob/main/src/KnownMiss.php"
            end
            
            subgraph ReturnDir["Return Directive System"]
                BypassCache["Bypass Cache"]:::directive
                click BypassCache "https://github.com/square/ttcache/blob/main/src/ReturnDirective/BypassCache.php"
                BypassInterface["Bypass Interface"]:::interface
                click BypassInterface "https://github.com/square/ttcache/blob/main/src/ReturnDirective/BypassCacheInterface.php"
            end
        end
        
        subgraph Store["Store Layer"]
            StoreInterface["Cache Store Interface"]:::interface
            click StoreInterface "https://github.com/square/ttcache/blob/main/src/Store/CacheStoreInterface.php"
            
            subgraph Implementations["Store Implementations"]
                MemcachedStore["Memcached Store"]:::store
                click MemcachedStore "https://github.com/square/ttcache/blob/main/src/Store/MemcachedStore.php"
                ShardedStore["Sharded Memcached Store"]:::store
                click ShardedStore "https://github.com/square/ttcache/blob/main/src/Store/ShardedMemcachedStore.php"
                TaggedStore["Tagged Store"]:::store
                click TaggedStore "https://github.com/square/ttcache/blob/main/src/Store/TaggedStore.php"
            end
            
            StoreException["Cache Store Exception"]:::error
            click StoreException "https://github.com/square/ttcache/blob/main/src/Store/CacheStoreException.php"
            StoreResult["Store Result"]:::result
            click StoreResult "https://github.com/square/ttcache/blob/main/src/Store/StoreResult.php"
        end
    end
    
    %% Relationships
    Client --> TTCache
    TTCache --> TagMgmt
    TTCache --> Results
    TTCache --> ReturnDir
    TTCache --> Store
    
    TagMgmt --> TagTypes
    HeritableTag & ShardingTag --> TagInterface
    
    MemcachedStore & ShardedStore & TaggedStore --> StoreInterface
    
    BypassCache --> BypassInterface
    
    %% Styling
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef tag fill:#FFC107,stroke:#FFA000,color:black
    classDef store fill:#4CAF50,stroke:#388E3C,color:white
    classDef interface fill:#FF9800,stroke:#F57C00,color:white
    classDef result fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef directive fill:#795548,stroke:#5D4037,color:white
    classDef error fill:#F44336,stroke:#D32F2F,color:white
```
