# samdvr/milena architecture

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

- Interactive diagram: https://gitdiagram.com/samdvr/milena
- Repository: https://github.com/samdvr/milena

## Overview

- milena-cache – The cache node implementation with multi-tiered storage (in-memory LRU caching, disk store, and backup via S3)
- milena-router – The routing service that uses consistent hashing to distribute client requests across cache nodes and enforce rate limiting
- milena-protos – The collection of Protocol Buffer (.proto) definitions and build scripts for generating gRPC interfaces between the cache and router

##### Main Components
– Client: The external user or application that sends requests.
– Router: Acts as the gateway to the cache nodes. It’s responsible for using consistent hashing for key distribution among the cache nodes, and it implements rate limiting.
– Cache Nodes: Represented as individual milena-cache instances. Each node implements a multi-tiered storage system:
○ LRU in-memory cache (fast, transient storage)
○ Disk-based persistent storage (for longer-term storage)
○ S3 storage for backup/overflow
– Protocol Definitions: Indicate the gRPC interfaces used to communicate between the Router and Cache Nodes.

##### Out Relationships and Interactions
– The Client sends requests (Get, Put, Delete) to the Router.
– The Router processes the requests using its consistent hashing mechanism to determine the correct Cache Node.
– Each Cache Node receives requests via gRPC (as defined in the milena-protos) and then handles the request by interacting with its layered storage:
○ It first checks the LRU memory cache.
○ If the data is not found, it looks up the disk store.
○ Optionally, S3 is used as a backup store for additional durability.
– Highlight the feedback loops for monitoring (Prometheus metrics are exposed by cache nodes via a designated endpoint) and error handling.

##### Architectural Patterns and Technologies
– Distributed System Design: Emphasize the separation of concerns between routing and caching.
– Multi-tiered Caching: Illustrate the hierarchy of caching from in-memory to persistent storage.

##### Final Touch and Recommendations
– High detail is favored. The more granular you separate the caching tiers within the Cache Node, the better the insights for troubleshooting and scalability planning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    Client("Client"):::external
    S3Storage("S3 Storage"):::external
    Prometheus("Prometheus Metrics"):::external

    %% Milena-Router Subgraph
    subgraph "Milena-Router"
        RouterMain("Milena-Router"):::service
        RateLimiter("Rate Limiter"):::service
        Validation("Validation"):::service
        Connection("Connection Handler"):::service
    end

    %% Protocol Definitions (milena-protos) Subgraph
    subgraph "Protocol Definitions (milena-protos)"
        RouProto("Router gRPC Proto"):::proto
        CachProto("Cache gRPC Proto"):::proto
        Build("Build Script"):::proto
        Lib("Library Integration"):::proto
    end

    %% Milena-Cache (Cache Node) Subgraph
    subgraph "Cache Node"
        LRU("LRU In-memory Cache"):::storage
        Disk("Disk Store"):::storage
    end

    %% Additional Cache Metrics/Configuration Nodes
    Metrics("Cache Metrics"):::external
    Config("Cache Config"):::external

    %% Connections
    Client -->|"sends_request"| RouterMain
    RouterMain -->|"consistent_hashing"| LRU
    LRU -->|"cache_miss"| Disk
    Disk -->|"backup"| S3Storage
    %% Monitoring: Cache node exposes metrics
    Disk -->|"exports_metrics"| Prometheus
    %% Dependencies on Protocol Definitions (gRPC interfaces)
    RouterMain -.->|"uses_gRPC"| RouProto
    LRU -.->|"uses_gRPC"| CachProto

    %% Additional internal router dependencies (optional flow)
    RouterMain -->|"triggers"| RateLimiter
    RouterMain -->|"validates"| Validation
    RouterMain -->|"handles_conn"| Connection

    %% Protocol Definitions internal structure connections (for clarity)
    RouProto ---|"relates_to"| CachProto
    Build ---|"builds"| Lib

    %% Cache Metrics/Configuration attachment (monitoring & config overrides)
    Disk ---|"configured_by"| Config
    Disk ---|"monitored_by"| Metrics

    %% Click Events for milena-cache (Cache Node Implementation)
    click LRU "https://github.com/samdvr/milena/tree/main/milena-cache/src/service/"
    click Disk "https://github.com/samdvr/milena/tree/main/milena-cache/src/store/"
    click Metrics "https://github.com/samdvr/milena/blob/main/milena-cache/src/metrics.rs"
    click Config "https://github.com/samdvr/milena/blob/main/milena-cache/src/config.rs"

    %% Click Events for milena-router (Routing Service)
    click RouterMain "https://github.com/samdvr/milena/blob/main/milena-router/src/main.rs"
    click RateLimiter "https://github.com/samdvr/milena/blob/main/milena-router/src/rate_limit.rs"
    click Validation "https://github.com/samdvr/milena/blob/main/milena-router/src/validation.rs"
    click Connection "https://github.com/samdvr/milena/blob/main/milena-router/src/connection.rs"
    
    %% Additional router service mapping
    click RouterMain "https://github.com/samdvr/milena/blob/main/milena-router/src/service/mod.rs"

    %% Click Events for milena-protos (Protocol Buffer Definitions)
    click RouProto "https://github.com/samdvr/milena/tree/main/milena-protos/proto/"
    click CachProto "https://github.com/samdvr/milena/tree/main/milena-protos/proto/"
    click Build "https://github.com/samdvr/milena/blob/main/milena-protos/build.rs"
    click Lib "https://github.com/samdvr/milena/blob/main/milena-protos/src/lib.rs"

%% Styles
classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
classDef service fill:#ccffcc,stroke:#006600,stroke-width:2px;
classDef storage fill:#cce5ff,stroke:#003399,stroke-width:2px;
classDef proto fill:#e6ccff,stroke:#800080,stroke-width:2px;
```
