# genc-murat/crystalcache architecture

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

- Interactive diagram: https://gitdiagram.com/genc-murat/crystalcache
- Repository: https://github.com/genc-murat/crystalcache

## Overview

##### Main Components

a) Client Interface Layer:
- RESP (Redis Serialization Protocol) handler (/pkg/resp)
- Connection management and client handlers (/internal/client)
- ACL management system (/internal/core/acl)

b) Command Processing Layer:
- Command router (/internal/handlers)
- Handler registry system
- Pipeline and transaction management

c) Core Storage Layer:
- Memory cache implementation (/internal/cache)
- Data structure implementations:
- Basic types (Strings, Lists, Sets, Hashes)
- Advanced types (Bitmap, BloomFilter, HyperLogLog, etc.)
- Specialized structures (GeoSpatial, TimesSeries)

d) Persistence Layer:
- AOF (Append-Only File) system (/internal/storage)
- Recovery management

e) Supporting Systems:
- Connection pooling (/internal/pool)
- Metrics collection (/internal/metrics)
- Configuration management (/config)

##### Component Relationships

**[Client] → [RESP Protocol Handler] → [ACL Layer] → [Command Router] →**
**[Handler Registry] → [Core Cache Layer] → [Data Structures]**
- ↓
- [Persistence Layer]

##### Specific Implementation Details

a) Following interfaces:
**/internal/core/ports/**
- cache.go
- pool.go
- server.go
- storage.go

b) Data structure implementations:
**/internal/cache/**
- memory.go
- memory_bitmap.go
- memory_bloomfilter.go
- [other specialized implementations]

##### Key Architectural Patterns to Emphasize

- Hexagonal Architecture (ports and adapters pattern)
- Command Pattern (in handlers)
- Factory Pattern (pool factory)
- Repository Pattern (storage implementation)

##### Additional Elements

a) External Interfaces:
- Metrics endpoint (port 2112)
- Main server port (6379)
- Replication connections

b) Cross-Cutting Concerns:
- Metrics collection
- Configuration management
- Error handling
- Retry mechanisms

Create distinct sections for:

##### Special Notes

- Bidirectional flows where applicable
- Async operations (like AOF writing)
- Replication paths
- Transaction boundaries
- Connection pooling mechanism

##### Scale and Detail Level

- Keep high-level architecture visible at a glance
- Provide zoom-in sections for complex subsystems

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Interface Layer"
        Client["Client"]
        RESP["RESP Protocol Handler"]:::resp
        ClientHandler["Client Management"]:::client
        ACL["ACL System"]:::acl
    end

    subgraph "Command Processing Layer"
        CmdRouter["Command Router"]:::handler
        HandlerReg["Handler Registry"]:::handler
    end

    subgraph "Core Storage Layer"
        Cache["Memory Cache"]:::cache
        DataStructures["Data Structures"]:::cache
        subgraph "Specialized Structures"
            Bitmap["Bitmap"]:::datastructure
            ZSet["Sorted Sets"]:::datastructure
            Models["Core Models"]:::datastructure
        end
    end

    subgraph "Persistence Layer"
        AOF["AOF System"]:::persistence
    end

    subgraph "Supporting Systems"
        Pool["Connection Pool"]:::support
        Metrics["Metrics Collection"]:::support
        Config["Configuration"]:::support
        Server["Server Implementation"]:::server
    end

    subgraph "Core Interfaces"
        CacheInterface["Cache Interface"]:::interface
        PoolInterface["Pool Interface"]:::interface
        ServerInterface["Server Interface"]:::interface
        StorageInterface["Storage Interface"]:::interface
    end

    Client --> RESP
    RESP --> ClientHandler
    ClientHandler --> ACL
    ACL --> CmdRouter
    CmdRouter --> HandlerReg
    HandlerReg --> Cache
    Cache --> DataStructures
    DataStructures --> Bitmap
    DataStructures --> ZSet
    DataStructures --> Models
    Cache --> AOF
    Cache -.-> Metrics
    Server --> Pool
    Server --> Config
    Cache --> CacheInterface
    Pool --> PoolInterface
    Server --> ServerInterface
    AOF --> StorageInterface

    %% Click events for component mapping
    click RESP "https://github.com/genc-murat/crystalcache/tree/main//pkg/resp/"
    click ClientHandler "https://github.com/genc-murat/crystalcache/blob/main//internal/client/client.go"
    click ACL "https://github.com/genc-murat/crystalcache/tree/main//internal/core/acl/"
    click CmdRouter "https://github.com/genc-murat/crystalcache/tree/main//internal/handlers/"
    click HandlerReg "https://github.com/genc-murat/crystalcache/blob/main//internal/handlers/registry.go"
    click Cache "https://github.com/genc-murat/crystalcache/blob/main//internal/cache/memory.go"
    click Bitmap "https://github.com/genc-murat/crystalcache/tree/main//internal/cache/bitmap/"
    click ZSet "https://github.com/genc-murat/crystalcache/tree/main//internal/cache/zset/"
    click Models "https://github.com/genc-murat/crystalcache/tree/main//internal/core/models/"
    click AOF "https://github.com/genc-murat/crystalcache/blob/main//internal/storage/aof.go"
    click Pool "https://github.com/genc-murat/crystalcache/tree/main//internal/pool/"
    click Metrics "https://github.com/genc-murat/crystalcache/blob/main//internal/metrics/metrics.go"
    click Config "https://github.com/genc-murat/crystalcache/tree/main//config/"
    click CacheInterface "https://github.com/genc-murat/crystalcache/blob/main//internal/core/ports/cache.go"
    click PoolInterface "https://github.com/genc-murat/crystalcache/blob/main//internal/core/ports/pool.go"
    click ServerInterface "https://github.com/genc-murat/crystalcache/blob/main//internal/core/ports/server.go"
    click StorageInterface "https://github.com/genc-murat/crystalcache/blob/main//internal/core/ports/storage.go"
    click Server "https://github.com/genc-murat/crystalcache/blob/main//internal/server/server.go"

    %% Styling
    classDef resp fill:#3498db
    classDef client fill:#3498db
    classDef acl fill:#e74c3c
    classDef handler fill:#2ecc71
    classDef cache fill:#f1c40f
    classDef datastructure fill:#f1c40f
    classDef persistence fill:#e67e22
    classDef support fill:#9b59b6
    classDef interface fill:#95a5a6
    classDef server fill:#34495e
```
