# jaredwray/cacheable architecture

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

- Interactive diagram: https://gitdiagram.com/jaredwray/cacheable
- Repository: https://github.com/jaredwray/cacheable

## Overview

##### Project Type and Purpose
- This is an open-source monorepo (“Cacheable Project”) that bundles multiple Node.js caching libraries as independent packages.
- Its goal is to provide a suite of caching solutions (in-memory, file-based, HTTP-cache compliant, Keyv-backed, etc.) and documentation (website) under a single workspace, managed with pnpm.

##### File-Structure Analysis
- Top level:
- `.github/workflows/…` – CI definitions (tests, codecov, deploy docs)
- `docker-compose.yml` – brings up Redis for integration tests
- `pnpm-workspace.yaml`, `package.json` – configure the mono-repo
- `packages/`
- `cacheable` – core, multi-layer caching framework (layer1, layer2)
- `cache-manager` – drop-in manager for NestJS and others
- `cacheable-request` – HTTP wrapper with RFC-compliant caching
- `flat-cache`, `file-entry-cache`, `@cacheable/node-cache` – specialized stores
- `website` – static docs generator & deployment
- Each package has its own `src/`, `test/`, `tsconfig.json`, and build config (`vite.config.ts` or similar).

##### README Insights
- Confirms the repo’s focus on npm-distributed caching packages, their download stats, and interdependence (all built on Keyv).
- Mentions prerequisites (Redis via Docker) and standard build/test flows (`pnpm build`, `pnpm test`).

a. Main Components
- Monorepo root & workspace manager (pnpm)
- GitHub Actions CI/CD pipeline
- Dockerized Redis instance (for tests & examples)
- Package modules:
1. cacheable (core framework)
2. cache-manager (NestJS adapter)
3. cacheable-request (HTTP layer)
4. flat-cache (in-memory + file persistence)
5. file-entry-cache (file metadata store)
6. @cacheable/node-cache (replacement node-cache)
- External Dependencies & Services:
- Keyv backends (Redis, memory, files)
- HTTP endpoints (for cacheable-request)
- Filesystem (for flat-cache, file-entry-cache)
- Documentation Website generator & host

b. Relationships & Data Flows
- Developers push code → GitHub Actions → run tests in each package (spinning up Redis via docker-compose) → publish to npm & deploy docs.
- Applications import any package:
- If using `cacheable` or `cache-manager`, at runtime calls go through the core module → layered caches → Keyv adapters → storage backends.
- If using `cacheable-request`, HTTP calls flow into its caching layer → underlying Keyv store → network or cache hit.
- flat-cache and file-entry-cache operate directly on the filesystem for persistence.
- @cacheable/node-cache uses in-process memory store.

c. Architectural Patterns & Principles
- Monorepo with isolated, independently versioned packages
- Workspace sharing of charted dependencies & build scripts
- Adapter pattern (Keyv adapters for Redis, memory, file)
- Layered caching (L1 in-memory, L2 remote or file)
- CI/CD as code (GitHub workflows + docker-compose for test dependencies)

d. Key Technologies & Frameworks
- Node.js & TypeScript
- pnpm workspaces
- Keyv (abstracted pluggable store)
- Vite (build/test config)
- Docker (Redis for integration)
- GitHub Actions (CI/CD)
- Docula (for website)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Infra
    subgraph "Monorepo Infrastructure" 
        direction TB
        RootPM["pnpm-workspace.yaml"]:::infra
        RootPkg["package.json"]:::infra
        CI["GitHub Actions CI/CD"]:::infra
        DC["docker-compose.yml"]:::infra
    end

    %% Packages
    subgraph "Packages" 
        direction TB
        subgraph "Core & Adapters"
            direction TB
            Core["cacheable (Core Framework)"]:::core
            AdapterNest["cache-manager (NestJS Adapter)"]:::adapter
            AdapterHTTP["cacheable-request (HTTP Caching)"]:::adapter
        end
        subgraph "Specialized Stores"
            direction TB
            Flat["flat-cache"]:::store
            FileMeta["file-entry-cache"]:::store
            NodeStore["@cacheable/node-cache"]:::store
        end
        subgraph "Website"
            direction TB
            Docs["website (Docs Generator)"]:::docs
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Redis["Redis (via Docker)"]:::external
        FS["Filesystem"]:::external
        HTTP["HTTP Endpoints"]:::external
    end

    %% CI/CD Flow
    DevPush["Developer Push"]:::infra
    DevPush -->|push code| CI
    CI -->|run tests| DC
    DC -->|start Redis| Redis
    CI -->|publish npm| RootPM
    CI -->|deploy docs| Docs

    %% Package Dependencies
    AdapterNest -->|depends on| Core
    AdapterHTTP -->|depends on| Core
    Flat -->|Keyv adapter| Core
    FileMeta -->|Keyv adapter| Core
    NodeStore -->|Keyv adapter| Core

    %% Runtime Flows
    Core -->|L1/L2 caching| Redis
    Core -->|L2 file persistence| FS
    AdapterHTTP -->|HTTP request| HTTP
    AdapterHTTP -->|caches via| Core

    Flat -->|reads/writes| FS
    FileMeta -->|reads/writes| FS
    NodeStore -->|in-memory store| Core

    %% Docs
    Docs -->|serves docs| HTTP

    %% Click Events - Infra
    click RootPM "https://github.com/jaredwray/cacheable/blob/main//pnpm-workspace.yaml"
    click RootPkg "https://github.com/jaredwray/cacheable/blob/main//package.json"
    click CI "https://github.com/jaredwray/cacheable/blob/main//.github/workflows/tests.yml"
    click CI "https://github.com/jaredwray/cacheable/blob/main//.github/workflows/codecov.yml"
    click CI "https://github.com/jaredwray/cacheable/blob/main//.github/workflows/deploy-website.yml"
    click DC "https://github.com/jaredwray/cacheable/blob/main//docker-compose.yml"

    %% Click Events - Packages
    click Core "https://github.com/jaredwray/cacheable/tree/main//packages/cacheable"
    click Core "https://github.com/jaredwray/cacheable/tree/main//packages/cacheable/src"
    click Core "https://github.com/jaredwray/cacheable/tree/main//packages/cacheable/test"
    click Core "https://github.com/jaredwray/cacheable/blob/main//packages/cacheable/vite.config.ts"

    click AdapterNest "https://github.com/jaredwray/cacheable/tree/main//packages/cache-manager"
    click AdapterNest "https://github.com/jaredwray/cacheable/tree/main//packages/cache-manager/src"
    click AdapterNest "https://github.com/jaredwray/cacheable/tree/main//packages/cache-manager/test"
    click AdapterNest "https://github.com/jaredwray/cacheable/blob/main//packages/cache-manager/vite.config.ts"

    click AdapterHTTP "https://github.com/jaredwray/cacheable/tree/main//packages/cacheable-request"
    click AdapterHTTP "https://github.com/jaredwray/cacheable/tree/main//packages/cacheable-request/src"
    click AdapterHTTP "https://github.com/jaredwray/cacheable/tree/main//packages/cacheable-request/test"
    click AdapterHTTP "https://github.com/jaredwray/cacheable/blob/main//packages/cacheable-request/vitest.config.mjs"

    click Flat "https://github.com/jaredwray/cacheable/tree/main//packages/flat-cache"
    click Flat "https://github.com/jaredwray/cacheable/tree/main//packages/flat-cache/src"
    click Flat "https://github.com/jaredwray/cacheable/tree/main//packages/flat-cache/test"
    click Flat "https://github.com/jaredwray/cacheable/blob/main//packages/flat-cache/vite.config.ts"

    click FileMeta "https://github.com/jaredwray/cacheable/tree/main//packages/file-entry-cache"
    click FileMeta "https://github.com/jaredwray/cacheable/tree/main//packages/file-entry-cache/src"
    click FileMeta "https://github.com/jaredwray/cacheable/tree/main//packages/file-entry-cache/test"
    click FileMeta "https://github.com/jaredwray/cacheable/blob/main//packages/file-entry-cache/vite.config.ts"

    click NodeStore "https://github.com/jaredwray/cacheable/tree/main//packages/node-cache"
    click NodeStore "https://github.com/jaredwray/cacheable/tree/main//packages/node-cache/src"
    click NodeStore "https://github.com/jaredwray/cacheable/tree/main//packages/node-cache/test"
    click NodeStore "https://github.com/jaredwray/cacheable/blob/main//packages/node-cache/vite.config.ts"

    click Docs "https://github.com/jaredwray/cacheable/tree/main//packages/website"
    click Docs "https://github.com/jaredwray/cacheable/blob/main//packages/website/site/docula.config.mjs"
    click Docs "https://github.com/jaredwray/cacheable/blob/main//packages/website/src/docs.cts"

    %% Styles
    classDef infra fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef adapter fill:#bfb,stroke:#333,stroke-width:1px
    classDef store fill:#ffb,stroke:#333,stroke-width:1px
    classDef docs fill:#fbf,stroke:#333,stroke-width:1px
    classDef external fill:#fdd,stroke:#333,stroke-width:1px
```
