# march1995/cache-event architecture

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

- Interactive diagram: https://gitdiagram.com/march1995/cache-event
- Repository: https://github.com/march1995/cache-event

## Overview

##### Project Type and Purpose
- Cache Event is a modular, Spring Boot–based distributed cache consistency framework.
- It provides annotation-driven cache dependency management, AOP interception of cache eviction, and event-driven cache clearing across nodes (Spring events for single-node, RabbitMQ for multi-node).

A. Client Application (your microservice or monolith)
- Business code invoking methods annotated with @CacheEvict and @CacheDependency
B. cache-event-common
- @CacheDependency annotation
- InetAddressUtil utility
C. cache-event-core
- AOP interceptor (CacheEvictionAspect)
- Event builders (CacheClearEventClientBuilder)
- Event push service (EventCachePushService)
- Event listeners (CacheClearEventListener)
- Dependency registry (InMemoryCacheDependencyRegistry or RedisCacheDependencyRegistry)
- Configuration (BuilderConfig, EventCacheProperties)
D. cache-event-rabbit-mq (optional extension)
- RabbitMQ configuration and builder (RabbitMqBuilderConfig)
- RabbitMQ push service (RabbitmqPushServiceImpl)
- RabbitMQ listener (CacheClearRabbitMqListener)
E. Underlying Infrastructure
- Cache stores: Caffeine or Redis
- Message broker: RabbitMQ
- Optional: Redis used as a dependency graph store

##### Relationships and Data Flows
1. Business Code → AOP Advice
- Method call triggers CacheEvictionAspect
2. AOP Advice → Dependency Registry
- Reads/writes cache dependency graph (in-memory or Redis) via CacheDependencyRegistry
3. AOP Advice → Event Builder
- Builds a CacheClearEvent that includes target cache keys and dependency info
4. Event Builder → Event Push Service
- Strategy selected by configuration:
- SpringEventPushServiceImpl uses ApplicationEventPublisher
- RabbitmqPushServiceImpl sends to RabbitMQ exchange/queue
5. Event Broker → Event Listener
- For Spring events: local in-VM listener (CacheClearSpringListener)
- For RabbitMQ: distributed listener (CacheClearRabbitMqListener)
6. Event Listener → Local Cache
- Listeners invoke cache eviction on Caffeine/Redis caches, including dependent entries

##### Architectural Patterns and Principles
- AOP for non-intrusive interception of @CacheEvict methods
- Annotation-driven metadata (@CacheDependency) for dependency graph
- Strategy / pluggable push mechanism (Spring Event vs. RabbitMQ)
- Builder / Factory for constructing event clients and listeners
- Modular design: common + core + extension, enabling future push mechanisms

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application Layer
    subgraph "Client Application" 
        direction TB
        Client["Business Code\n(@CacheEvict, @CacheDependency)"]:::client
    end

    %% Common Module
    subgraph "cache-event-common" 
        direction TB
        CacheDependency["@CacheDependency"]:::common
        InetAddressUtil["InetAddressUtil"]:::common
    end

    %% Core Module
    subgraph "cache-event-core"
        direction TB
        EventCacheEvictAop["EventCacheEvictAop\n(Pointcut)"]:::core
        CacheEvictionAspect["CacheEvictionAspect\n(AOP Interceptor)"]:::core
        BuilderConfig["BuilderConfig"]:::core
        EventCacheProperties["EventCacheProperties"]:::core
        CacheClearEvent["CacheClearEvent"]:::core
        CacheClearEventClientBuilder["CacheClearEventClientBuilder"]:::core
        SpringEventClientBuilder["CacheClearEventSpingEventClientBuilder"]:::core
        EventCachePushService["EventCachePushService"]:::core
        SpringEventPushServiceImpl["SpringEventPushServiceImpl"]:::core
        PushTypeCondition["PushTypeCondition"]:::core
        CacheDependencyRegistry["CacheDependencyRegistry"]:::core
        InMemoryCacheDependencyRegistry["InMemoryCacheDependencyRegistry"]:::core
        RedisCacheDependencyRegistry["RedisCacheDependencyRegistry"]:::core
        CacheClearEventListener["CacheClearEventListener"]:::core
        CacheClearSpringListener["CacheClearSpringListener"]:::core
        CacheClearEventListenerBuilder["CacheClearEventListenerBuilder"]:::core
    end

    %% RabbitMQ Extension
    subgraph "cache-event-rabbit-mq (Extension)" 
        direction TB
        RabbitMqBuilderConfig["RabbitMqBuilderConfig"]:::ext
        RabbitConstants["RabbitConstants"]:::ext
        CacheClearEventRabbitMqClientBuilder["CacheClearEventRabbitMqClientBuilder"]:::ext
        RabbitmqPushServiceImpl["RabbitmqPushServiceImpl"]:::ext
        CacheClearRabbitMqListener["CacheClearRabbitMqListener"]:::ext
        CacheClearRabbitMqListenerBuilder["CacheClearRabbitMqListenerBuilder"]:::ext
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Caffeine["Caffeine Cache"]:::infra
        Redis["Redis Cache"]:::infra
        RabbitMQ["RabbitMQ\n(broker)"]:::infra
    end

    %% Relationships
    Client -->|invokes annotated methods| EventCacheEvictAop
    EventCacheEvictAop -->|"advice"| CacheEvictionAspect
    CacheEvictionAspect -->|"reads/writes"| CacheDependencyRegistry
    CacheDependencyRegistry -->|implements| InMemoryCacheDependencyRegistry
    CacheDependencyRegistry -->|implements| RedisCacheDependencyRegistry
    CacheEvictionAspect -->|"builds event"| CacheClearEventClientBuilder
    CacheClearEventClientBuilder -->|"uses config"| BuilderConfig
    CacheClearEventClientBuilder -->|"uses props"| EventCacheProperties
    CacheClearEventClientBuilder -->|"builds"| CacheClearEvent
    CacheClearEventClientBuilder -->|"delegates"| EventCachePushService
    EventCachePushService -->|conditional| SpringEventPushServiceImpl
    EventCachePushService -->|conditional| RabbitmqPushServiceImpl
    SpringEventPushServiceImpl -->|publishes via| ApplicationEventPublisher["ApplicationEventPublisher"]:::infra
    RabbitmqPushServiceImpl -->|publishes via AMQP| RabbitMQ
    ApplicationEventPublisher -->|dispatches| CacheClearSpringListener
    RabbitMQ -->|delivers| CacheClearRabbitMqListener
    CacheClearSpringListener -->|evicts| Caffeine
    CacheClearSpringListener -->|evicts| Redis
    CacheClearRabbitMqListener -->|evicts| Caffeine
    CacheClearRabbitMqListener -->|evicts| Redis

    %% Module Dependencies
    Client --- CacheDependency
    Client --- InetAddressUtil

    %% Click Events
    click CacheDependency "https://github.com/march1995/cache-event/blob/v2/cache-event-common/src/main/java/com/umax/cache/event/common/annotations/CacheDependency.java"
    click InetAddressUtil "https://github.com/march1995/cache-event/blob/v2/cache-event-common/src/main/java/com/umax/cache/event/common/utils/InetAddressUtil.java"
    click CacheEvictionAspect "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/aop/CacheEvictionAspect.java"
    click EventCacheEvictAop "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/aop/EventCacheEvictAop.java"
    click BuilderConfig "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/configuration/BuilderConfig.java"
    click EventCacheProperties "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/properties/EventCacheProperties.java"
    click CacheClearEvent "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/event/CacheClearEvent.java"
    click CacheClearEventClientBuilder "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/event/CacheClearEventClientBuilder.java"
    click SpringEventClientBuilder "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/event/spring/CacheClearEventSpingEventClientBuilder.java"
    click EventCachePushService "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/push/EventCachePushService.java"
    click SpringEventPushServiceImpl "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/push/SpringEventPushServiceImpl.java"
    click CacheDependencyRegistry "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/registry/CacheDependencyRegistry.java"
    click InMemoryCacheDependencyRegistry "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/registry/InMemoryCacheDependencyRegistry.java"
    click RedisCacheDependencyRegistry "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/registry/RedisCacheDependencyRegistry.java"
    click CacheClearEventListener "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/listen/CacheClearEventListener.java"
    click CacheClearSpringListener "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/listen/spring/CacheClearSpringListener.java"
    click CacheClearEventListenerBuilder "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/listen/CacheClearEventListenerBuilder.java"
    click PushTypeCondition "https://github.com/march1995/cache-event/blob/v2/cache-event-core/src/main/java/com/umax/cache/event/core/condition/PushTypeCondition.java"
    click RabbitMqBuilderConfig "https://github.com/march1995/cache-event/blob/v2/cache-event-rabbit-mq/src/main/java/com/umax/cache/event/rabbitmq/config/RabbitMqBuilderConfig.java"
    click RabbitConstants "https://github.com/march1995/cache-event/blob/v2/cache-event-rabbit-mq/src/main/java/com/umax/cache/event/rabbitmq/constant/RabbitConstants.java"
    click CacheClearEventRabbitMqClientBuilder "https://github.com/march1995/cache-event/blob/v2/cache-event-rabbit-mq/src/main/java/com/umax/cache/event/rabbitmq/event/CacheClearEventRabbitMqClientBuilder.java"
    click RabbitmqPushServiceImpl "https://github.com/march1995/cache-event/blob/v2/cache-event-rabbit-mq/src/main/java/com/umax/cache/event/rabbitmq/push/RabbitmqPushServiceImpl.java"
    click CacheClearRabbitMqListener "https://github.com/march1995/cache-event/blob/v2/cache-event-rabbit-mq/src/main/java/com/umax/cache/event/rabbitmq/listen/CacheClearRabbitMqListener.java"
    click CacheClearRabbitMqListenerBuilder "https://github.com/march1995/cache-event/blob/v2/cache-event-rabbit-mq/src/main/java/com/umax/cache/event/rabbitmq/listen/CacheClearRabbitMqListenerBuilder.java"

    %% Styles
    classDef client fill:#d0f0c0,stroke:#2e7d32,color:#1b5e20
    classDef common fill:#bbdefb,stroke:#1565c0,color:#0d47a1
    classDef core fill:#90caf9,stroke:#1565c0,color:#0d47a1
    classDef ext fill:#ffe0b2,stroke:#ef6c00,color:#e65100
    classDef infra fill:#ffcc80,stroke:#ef6c00,color:#e65100
    class ApplicationEventPublisher infra
    class RabbitMQ infra
    class Caffeine infra
    class Redis infra
```
