# hit-box/hitbox architecture

> Architecture diagram of the GitHub repository hit-box/hitbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hit-box/hitbox
- Repository: https://github.com/hit-box/hitbox

## Overview

##### Main Components Identification

- Framework Integration Layer (Top)
- Core Caching Layer (Middle)
- Backend Layer (Bottom)

##### Component Breakdown

a. Framework Integration Components:
- Integration modules (hitbox-actix, hitbox-tower)
- Connection points to the core caching layer

b. Core Components (hitbox):
- Cache Management System
- State Machine (found in src/states)
- Transition Groups
- Metrics System
- Error Handling

c. Backend Layer:
- Redis Backend
- Mock Backend (for testing)
- Extension point for future backends

##### Key Flows

- Only Cache Flow
- Stale Cache Flow
- Upstream Flow

##### Detailed Component Relationships

Specific interactions:
**Framework Integration**
- ↓
**Cache Management Layer**
- ↓
**State Machine (with states):**
- Initial
- Cache Policy
- Cache Polled
- Upstream Polled
- Cache Updated
- Finish
- ↓
**Backend Implementations**

##### Additional Details

- Notes about the Cacheable trait implementation paths (derived vs. manual)
- Integration points for metrics collection
- Where cache key generation occurs
- Stale cache mechanics

## Diagram (Mermaid)

```mermaid
graph TB
    %% Framework Integration Layer
    subgraph Frameworks
        ActixIntegration["Actix Integration"]:::framework
        TowerIntegration["Tower Integration"]:::framework
    end

    %% Core Layer
    subgraph Core
        CacheManager["Cache Management System"]:::core
        StateMachine["State Machine"]:::core
        TransitionGroups["Transition Groups"]:::core
        MetricsSystem["Metrics System"]:::utility
        ErrorHandler["Error Handler"]:::utility
        Runtime["Core Runtime"]:::core
        Settings["Settings Manager"]:::utility
        SerializationLayer["Serialization Layer"]:::core
        CacheableDerive["Cacheable Derive Macros"]:::utility
    end

    %% State Machine Components
    subgraph States
        Initial["Initial State"]:::state
        CachePolicy["Cache Policy"]:::state
        CachePolled["Cache Polled"]:::state
        UpstreamPolled["Upstream Polled"]:::state
        CacheUpdated["Cache Updated"]:::state
        Finish["Finish"]:::state
    end

    %% Transition Groups
    subgraph Transitions
        OnlyCache["Only Cache Flow"]:::transition
        StaleCache["Stale Cache Flow"]:::transition
        Upstream["Upstream Flow"]:::transition
    end

    %% Backend Layer
    subgraph Backends
        RedisBackend["Redis Backend"]:::backend
        MockBackend["Mock Backend"]:::backend
    end

    %% Relationships
    ActixIntegration --> CacheManager
    TowerIntegration --> CacheManager
    CacheManager --> StateMachine
    StateMachine --> TransitionGroups
    TransitionGroups --> |Manages| States
    StateMachine --> MetricsSystem
    StateMachine --> ErrorHandler
    CacheManager --> Runtime
    Runtime --> Settings
    SerializationLayer --> Backends
    CacheableDerive --> CacheManager

    %% State Transitions
    Initial --> CachePolicy
    CachePolicy --> CachePolled
    CachePolled --> UpstreamPolled
    UpstreamPolled --> CacheUpdated
    CacheUpdated --> Finish

    %% Backend Connections
    CacheManager --> RedisBackend
    CacheManager --> MockBackend

    %% Styling
    classDef framework fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef utility fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef state fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef transition fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef backend fill:#FFA500,stroke:#333,stroke-width:2px

    %% Click Events
    click ActixIntegration "https://github.com/hit-box/hitbox/blob/main/hitbox-actix/src/lib.rs"
    click TowerIntegration "https://github.com/hit-box/hitbox/blob/main/hitbox-tower/src/lib.rs"
    click CacheManager "https://github.com/hit-box/hitbox/blob/main/hitbox/src/cache.rs"
    click StateMachine "https://github.com/hit-box/hitbox/blob/main/hitbox/src/states/mod.rs"
    click TransitionGroups "https://github.com/hit-box/hitbox/blob/main/hitbox/src/transition_groups/mod.rs"
    click MetricsSystem "https://github.com/hit-box/hitbox/blob/main/hitbox/src/metrics.rs"
    click ErrorHandler "https://github.com/hit-box/hitbox/blob/main/hitbox/src/error.rs"
    click RedisBackend "https://github.com/hit-box/hitbox/blob/main/hitbox-redis/src/lib.rs"
    click MockBackend "https://github.com/hit-box/hitbox/blob/main/hitbox/src/dev/mock_backend.rs"
    click CachePolicy "https://github.com/hit-box/hitbox/blob/main/hitbox/src/states/cache_policy/mod.rs"
    click OnlyCache "https://github.com/hit-box/hitbox/blob/main/hitbox/src/transition_groups/only_cache.rs"
    click StaleCache "https://github.com/hit-box/hitbox/blob/main/hitbox/src/transition_groups/stale.rs"
    click Upstream "https://github.com/hit-box/hitbox/blob/main/hitbox/src/transition_groups/upstream.rs"
    click SerializationLayer "https://github.com/hit-box/hitbox/blob/main/hitbox-backend/src/serializer.rs"
    click Runtime "https://github.com/hit-box/hitbox/blob/main/hitbox/src/runtime/mod.rs"
    click Settings "https://github.com/hit-box/hitbox/blob/main/hitbox/src/settings.rs"
    click CacheableDerive "https://github.com/hit-box/hitbox/blob/main/hitbox-derive/src/lib.rs"
```
