# sisovin/cache-system-implementation architecture

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

- Interactive diagram: https://gitdiagram.com/sisovin/cache-system-implementation
- Repository: https://github.com/sisovin/cache-system-implementation

## Overview

##### Project Type and Purpose
- This is a distributed, full-stack caching system composed of multiple specialized components. Its purpose is to provide multi-layer caching strategies across client, edge (load balancer/CDN), API gateway, distributed cache cluster, search engine, messaging, and database layers.
- Key indicators:
- The README lists features for client-side caching, load balancer, API gateway, distributed cache, messaging, full-text search, relational database, and common infrastructure.
- The file tree shows directories for client-app, load-balancer, api-gateway, distributed-cache, full-text-search, messaging, relational-database, common-infrastructure, and deployment.

##### File Structure
- Top-level components:
- client-app: React/JS service worker and Cache API code for offline and dynamic content caching.
- load-balancer: Go code implementing LRU hot-route caching and CDN integration.
- api-gateway: Python main.py (FastAPI) for request/response caching, hierarchical (RAM → Redis → DB) and rate-limiting.
- distributed-cache: Java cluster configuration for Hazelcast/Redis-like patterns.
- full-text-search: Java Elasticsearch integration and query caching.
- messaging: Scala/Java Kafka producers/consumers for cache population and invalidation.
- relational-database: C code for PostgreSQL caching extensions (pg_cache.c).
- common-infrastructure: Java utilities for metrics, encryption, multi-level invalidation.
- deployment: Dockerfiles, Kubernetes HPA, blue-green deploy scripts, Terraform for infra provisioning.

##### Key Architectural Patterns
- Hierarchical cache (RAM → Redis → DB) in API gateway.
- Cache-aside and write-through in distributed cache.
- LRU and TTL on load balancer/CDN edge.
- Service worker + Cache API at client side.
- Kafka messaging for asynchronous cache updates and warm-up.
- Materialized view and WAL archiving optimizations for database cache.
- Multi-level invalidation and distributed tracing for observability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client & Edge Layer
    subgraph "Client Layer"
        SW["Service Worker"]:::client
        CW["CacheWrapper Component"]:::client
    end
    subgraph "Edge Layer"
        LB["Load Balancer"]:::edge
        CDN["CDN"]:::edge
    end
    SW -->|"Intercept & Cache Requests"| LB
    CW -->|"Wrap Components"| SW
    LB -->|"LRU Cache Lookup"| CDN
    CDN -->|"TLS Termination & Forward"| APIGateway

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        APIGateway["API Gateway<br/>(FastAPI, Hierarchical Cache)"]:::gateway
        RAM["RAM Cache"]:::cache
        Redis["Redis Cache"]:::cache
        DBFallback["Relational DB<br/>Fallback"]:::db
    end
    CDN --> APIGateway
    APIGateway -->|"RAM Lookup"| RAM
    APIGateway -->|"Redis Lookup"| Redis
    APIGateway -->|"DB Query"| DBFallback
    APIGateway -->|"Publish Cache Event"| Kafka

    %% Messaging & Search Layer
    subgraph "Messaging & Search Layer"
        Kafka["Kafka Messaging"]:::messaging
        Search["Full-Text Search<br/>(Elasticsearch)"]:::messaging
    end
    APIGateway -->|"Kafka Publish"| Kafka
    Kafka -->|"Cache Update"| DistributedCache
    Kafka -->|"Search Index Update"| Search

    %% Distributed Cache Layer
    subgraph "Distributed Cache Layer"
        DistributedCache["Distributed Cache<br/>(Hazelcast/Redis)"]:::cache
    end
    DistributedCache -->|"Serve Cached Data"| APIGateway

    %% Database Layer
    subgraph "Database Layer"
        PostgreSQL["PostgreSQL<br/>(C Extension Cache)"]:::db
        ElasticsearchDB["Elasticsearch Data Store"]:::db
    end
    Search -->|"Query Cache Lookup"| ElasticsearchDB
    DBFallback --> PostgreSQL

    %% Common Infrastructure
    subgraph "Common Infrastructure"
        Metrics["Metrics & Tracing"]:::infra
        Encryption["Encryption Service"]:::infra
        Invalidation["Invalidation Utility"]:::infra
    end
    APIGateway -->|"Emit Metrics"| Metrics
    APIGateway -->|"Emit Traces"| Metrics
    APIGateway -->|"Trigger Invalidation"| Invalidation
    DistributedCache -->|"Invalidate on Update"| Invalidation
    Search -->|"Emit Metrics"| Metrics

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        InfraDocker["Docker Containers"]:::infra
        K8s["Kubernetes (HPA)"]:::infra
        BlueGreen["Blue-Green Deploy"]:::infra
        Terraform["Terraform IaC"]:::infra
    end
    APIGateway --> InfraDocker
    DistributedCache --> InfraDocker
    Search --> InfraDocker
    PostgreSQL --> InfraDocker
    InfraDocker --> K8s
    K8s --> BlueGreen
    BlueGreen --> Terraform

    %% Click Events
    click SW "https://github.com/sisovin/cache-system-implementation/blob/main/client-app/src/serviceWorker.js"
    click CW "https://github.com/sisovin/cache-system-implementation/blob/main/client-app/src/components/CacheWrapper.js"
    click LB "https://github.com/sisovin/cache-system-implementation/blob/main/load-balancer/main.go"
    click CDN "https://github.com/sisovin/cache-system-implementation/blob/main/load-balancer/cdn.go"
    click APIGateway "https://github.com/sisovin/cache-system-implementation/blob/main/api-gateway/main.py"
    click DistributedCache "https://github.com/sisovin/cache-system-implementation/blob/main/distributed-cache/src/main/java/com/example/CacheConfig.java"
    click Kafka "https://github.com/sisovin/cache-system-implementation/blob/main/messaging/src/main/scala/com/example/KafkaProducer.scala"
    click Search "https://github.com/sisovin/cache-system-implementation/blob/main/full-text-search/src/main/java/com/example/ElasticsearchConfig.java"
    click PostgreSQL "https://github.com/sisovin/cache-system-implementation/blob/main/relational-database/src/main/c/pg_cache.c"
    click Metrics "https://github.com/sisovin/cache-system-implementation/blob/main/common-infrastructure/src/main/java/com/example/CacheOps.java"
    click InfraDocker "https://github.com/sisovin/cache-system-implementation/tree/main/deployment/Dockerfile"
    click K8s "https://github.com/sisovin/cache-system-implementation/blob/main/deployment/k8s/hpa.yaml"
    click BlueGreen "https://github.com/sisovin/cache-system-implementation/blob/main/deployment/scripts/blue-green-deploy.sh"
    click Terraform "https://github.com/sisovin/cache-system-implementation/blob/main/deployment/terraform/main.tf"

    %% Styles
    classDef client fill:#c6f5c6,stroke:#28a745,color:#000
    classDef edge fill:#d0f0ff,stroke:#007bff,color:#000
    classDef gateway fill:#cfe2ff,stroke:#0056b3,color:#000
    classDef cache fill:#ffe5b4,stroke:#ff8800,color:#000
    classDef messaging fill:#e5d0ff,stroke:#800080,color:#000
    classDef db fill:#e0e0e0,stroke:#666,color:#000
    classDef infra fill:#fff3b0,stroke:#ffc107,color:#000
```
