# sherlock-hashed/kshama architecture

> Architecture diagram of the GitHub repository sherlock-hashed/kshama, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sherlock-hashed/kshama
- Repository: https://github.com/sherlock-hashed/kshama

## Overview

This is a CLI-configured HTTP caching reverse proxy. Operators supply the origin and cache settings; clients send requests to the Express server, which forwards non-GET requests and serves GETs from an in-memory LRU+TTL cache when possible, otherwise fetching and caching the origin response. Admin routes expose statistics and clear the cache, while logging records proxy activity. README capabilities are included where documented; runtime flows are based on the sampled entry point, server, cache, and logger sources.

Main entry points: [`src/server.js`](https://github.com/sherlock-hashed/kshama/blob/main/src/server.js) (Proxy Server), [`src/index.js`](https://github.com/sherlock-hashed/kshama/blob/main/src/index.js) (CLI Configuration), [`src/cache/CacheService.js`](https://github.com/sherlock-hashed/kshama/blob/main/src/cache/CacheService.js) (LRU TTL Cache), [`src/utils/logger.js`](https://github.com/sherlock-hashed/kshama/blob/main/src/utils/logger.js) (Console Logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup & Configuration"]
  node_cli["CLI Configuration<br/>[index.js]"]
end

subgraph group_proxy["Proxy Runtime"]
  node_server["Proxy Server<br/>[server.js]"]
end

subgraph group_cache["Cache &amp; Observability"]
  node_cache[("LRU TTL Cache<br/>[CacheService.js]")]
  node_logger["Console Logger<br/>[logger.js]"]
end

node_operator(("Operator"))
node_client(("HTTP Client"))
node_origin["Origin API"]

node_operator -->|"configures"| node_cli
node_cli -->|"starts"| node_server
node_operator -->|"requests clear"| node_cli
node_cli -->|"DELETE request"| node_server
node_client -->|"HTTP request"| node_server
node_server -->|"checks GET"| node_cache
node_cache -->|"returns entry"| node_server
node_server -->|"fetches on miss"| node_origin
node_server -->|"forwards non-GET"| node_origin
node_server -->|"stores miss response"| node_cache
node_server -->|"reads stats / clears"| node_cache
node_server -->|"logs operations"| node_logger
node_cli -->|"logs CLI events"| node_logger

click node_cli "https://github.com/sherlock-hashed/kshama/blob/main/src/index.js"
click node_server "https://github.com/sherlock-hashed/kshama/blob/main/src/server.js"
click node_cache "https://github.com/sherlock-hashed/kshama/blob/main/src/cache/CacheService.js"
click node_logger "https://github.com/sherlock-hashed/kshama/blob/main/src/utils/logger.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_client toneBlue
class node_server toneAmber
class node_cache,node_logger,node_origin toneMint
class node_operator toneIndigo
```

## Components

### Startup & Configuration

- [CLI Configuration](https://github.com/sherlock-hashed/kshama/blob/main/src/index.js): `src/index.js`

### Proxy Runtime

- [Proxy Server](https://github.com/sherlock-hashed/kshama/blob/main/src/server.js): `src/server.js`

### Cache & Observability

- [LRU TTL Cache](https://github.com/sherlock-hashed/kshama/blob/main/src/cache/CacheService.js): `src/cache/CacheService.js`
- [Console Logger](https://github.com/sherlock-hashed/kshama/blob/main/src/utils/logger.js): `src/utils/logger.js`

### Other components

- **Operator**
- **HTTP Client**
- **Origin API**

## Connections

- Operator → CLI Configuration: configures
- CLI Configuration → Proxy Server: starts
- Operator → CLI Configuration: requests clear
- CLI Configuration → Proxy Server: DELETE request
- HTTP Client → Proxy Server: HTTP request
- Proxy Server → LRU TTL Cache: checks GET
- LRU TTL Cache → Proxy Server: returns entry
- Proxy Server → Origin API: fetches on miss
- Proxy Server → Origin API: forwards non-GET
- Proxy Server → LRU TTL Cache: stores miss response
- Proxy Server → LRU TTL Cache: reads stats / clears
- Proxy Server → Console Logger: logs operations
- CLI Configuration → Console Logger: logs CLI events