# harshsri28/lrucache-backend architecture

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

- Interactive diagram: https://gitdiagram.com/harshsri28/lrucache-backend
- Repository: https://github.com/harshsri28/lrucache-backend

## Overview

##### Project type and purpose
- This is a single‐service Go backend that implements an in‐memory LRU cache with RESTful API endpoints and a WebSocket channel for cache event notifications (item expirations, updates).
- Its primary responsibilities are:
- Expose CRUD operations on the cache via HTTP
- Manage the LRU eviction logic in memory
- Push real-time notifications over WebSocket when items expire or change

##### File structure
- main.go: application entry point; sets up HTTP router, WebSocket handler, and starts the server.
- routes/cacheRoutes.go: defines /cache REST endpoints (GET, POST, DELETE) and /ws for WebSocket upgrade.
- controllers/cacheControllers.go: HTTP handler functions that parse requests, call the cache module, and return JSON responses.
- module/lruCache.go: core LRU cache implementation (data structures, get, put, eviction).
- helper/websocket.go: WebSocket hub, broadcast channel, client management, notification routines.
- go.mod / go.sum: module definitions and dependencies.

##### Key architectural patterns
- Layered design:
- API Layer (routes → controllers)
- Business Logic Layer (LRU cache module)
- Real-time Notification Layer (WebSocket helper)
- In-memory data store (no external DB).
- Event broadcasting (pub/sub) via channels and goroutines.

##### Components
a. HTTP Server & Router
- Go HTTP server (net/http or Gin-like router).
- Shows incoming HTTP connections routed to controllers and WS upgrader.
b. Cache Controller Layer
- Endpoints:
- GET /cache
- GET /cache/{key}
- POST /cache
- DELETE /cache/{key}
c. LRU Cache Module
- Core data structure (doubly‐linked list + hash map)
- Methods: Get, Put, Delete, Evict
d. WebSocket Hub
- HandleConnections: upgrades and tracks clients
- HandleMessages: listens on broadcast channel
- NotifyClients: pushes events
e. Clients
- REST clients (e.g., Postman, frontend apps)
- WebSocket clients (browsers or services listening to /ws)

##### Relationships and data flow
- HTTP Request → Router → Controller → LRU Module → (on mutation/expiration) → WebSocket broadcast channel → WebSocket Hub → Connected Clients
- WebSocket Connection → Hub.HandleConnections → Subscribed to broadcast channel → Receive notifications

##### Architectural patterns/design principles
- Separation of concerns: routing, controllers, business logic, notifications are in separate packages.
- Concurrency model: goroutines + channels for pub/sub.
- In-memory state management: no external persistence.

## Diagram (Mermaid)

```mermaid
graph TD
    classDef http fill:#ADD8E6,stroke:#000,color:#000
    classDef cache fill:#90EE90,stroke:#000,color:#000
    classDef ws fill:#FFA500,stroke:#000,color:#000
    classDef client fill:#D3D3D3,stroke:#000,color:#000

    RESTClient["REST Client"]:::client
    WSClient["WebSocket Client"]:::client

    subgraph "Cache Service"
        subgraph "API Layer"
            HTTPServer["HTTP Server"]:::http
            Router["Router"]:::http
            Controllers["Cache Controllers"]:::http
        end
        subgraph "Business Logic Layer"
            LRUCache["LRU Cache Module"]:::cache
        end
        subgraph "Notification Layer"
            BroadcastChannel("Broadcast Channel"):::ws
            WSHub("WebSocket Hub"):::ws
        end
    end

    RESTClient -->|"HTTP Request"| HTTPServer
    HTTPServer -->|"route /cache, /ws"| Router
    Router -->|"handle endpoints"| Controllers
    Controllers -->|"Get/Put/Delete"| LRUCache

    LRUCache -.->|"expire/update event"| BroadcastChannel
    BroadcastChannel -->|"send event"| WSHub
    WSClient -->|"WS Connection"| WSHub
    WSHub -->|"WebSocket message"| WSClient

    click HTTPServer "https://github.com/harshsri28/lrucache-backend/blob/master/main.go"
    click Router "https://github.com/harshsri28/lrucache-backend/blob/master/routes/cacheRoutes.go"
    click Controllers "https://github.com/harshsri28/lrucache-backend/blob/master/controllers/cacheControllers.go"
    click LRUCache "https://github.com/harshsri28/lrucache-backend/blob/master/module/lruCache.go"
    click WSHub "https://github.com/harshsri28/lrucache-backend/blob/master/helper/websocket.go"

    class HTTPServer,Router,Controllers http
    class LRUCache cache
    class BroadcastChannel,WSHub ws
    class RESTClient,WSClient client
```
