# dev-hive-school/typescript-lru-cache architecture

> Architecture diagram of the GitHub repository dev-hive-school/typescript-lru-cache, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dev-hive-school/typescript-lru-cache
- Repository: https://github.com/dev-hive-school/typescript-lru-cache

## Overview

This project is **not a full-stack app**. It is a **NestJS backend sample** focused on one production-style concern: **how to use `lru-cache` correctly for caching user permissions**.

- NestJS application bootstrap
- module-based request handling
- permissions API
- cache layer
- permission data source / storage layer
- tests validating cache behavior

##### What this project is

- a **TypeScript / NestJS application**
- demonstrating **best practices for LRU cache usage**
- specifically in a **permissions lookup flow**
- with **explicit invalidation**, **fixed TTL**, and **bounded memory usage**

Instead, it should look like a **single backend service with internal layers**.

##### Client / API Consumer
- Represents whoever calls the permissions endpoint.
- Could be a browser, another backend service, or a CLI client.

##### NestJS Application Bootstrap
- `src/main.ts`
- Starts the server and wires the app together.

##### App Module
- `src/app.module.ts`
- Root composition module.

##### App Controller / App Service
- `src/app.controller.ts`
- `src/app.service.ts`
- Likely a basic root endpoint / app-level example.

##### Permissions Module
- `src/permissions/permissions.module.ts`
- Feature module for the cache-backed permissions logic.

##### Permissions Controller
- `src/permissions/permissions.controller.ts`
- HTTP interface for permissions operations.

##### Permissions Service
- `src/permissions/permissions.service.ts`
- Core business logic:
- reads permissions
- consults cache
- fetches from source of truth on miss
- invalidates cache when needed

##### LRU Cache
- This is the key architectural element.
- It explicitly as a separate component.
- It with:
- bounded entries (`max`)
- bounded size (`maxSize`)
- fixed TTL
- no refresh on read (`updateAgeOnGet: false`)

##### Permissions Storage / Source of Truth
- `src/storage.ts`
- This appears to be the backing data source for permissions.
- It may be an in-memory store or data access abstraction.

##### Unit Tests
- `src/*.spec.ts`
- `src/permissions/*.spec.ts`

##### E2E Tests
- `test/app.e2e-spec.ts`

These should usually be shown in a **separate “Testing” lane** or a side annotation, not in the main runtime path.

##### Service checks the LRU cache
- if **cache hit**: return cached permissions immediately
- if **cache miss**: fetch from `storage.ts`

##### Invalidation flow
There are two explicit invalidation operations mentioned in the README:

- `invalidateUserPermissions(userId)`
- `clearPermissionsCache()`

- targeted eviction for one user
- full cache clear for all users

This is an important part of the design and should be visually highlighted.

##### Architectural pattern to emphasize

This project uses a very clear **NestJS modular layered architecture**:

##### Pattern
- **Controller layer**
- handles HTTP requests/responses
- **Service layer**
- contains business logic and cache logic
- **Data source layer**
- `storage.ts`
- **Cross-cutting cache layer**
- `lru-cache`

##### Design principles
- **Separation of concerns**
- **Dependency injection**
- **Feature-module organization**
- **Explicit cache invalidation**
- **Bounded memory cache**
- **Production-style TTL behavior**

##### What to label

Be very explicit. Use labels like:

- **NestJS App Entry Point**
- **Root Module**
- **Permissions Feature Module**
- **HTTP Controller**
- **Permissions Service**
- **LRU Cache**
- `max`
- `maxSize`
- `TTL`
- `updateAgeOnGet: false`
- **Permissions Source of Truth**
- **Cache Invalidation API**
- `invalidateUserPermissions(userId)`
- `clearPermissionsCache()`

- **bounded memory**
- **stale permissions revalidated on TTL expiry**
- **reads do not extend lifespan**

Include:
- module boundaries
- cache boundary
- invalidation flow
- cache miss / hit paths
- source-of-truth storage
- test layer

But keep the runtime architecture focused.
Do **not** add unrelated infrastructure like:
- databases
- queues
- auth providers
- CDNs
- microservices
unless they are actually in the codebase, which they are not.

##### What technologies to mention

Major technologies because they define the architecture:

- **NestJS**
- **TypeScript**
- **lru-cache**
- **Jest** for tests
- **Node.js** runtime

Optional tooling to show as secondary:
- **ESLint**
- **Prettier**
- **Nest CLI**

##### Unit tests
- `app.controller.spec.ts`
- `app.service.spec.ts`
- `permissions.controller.spec.ts`
- `permissions.service.spec.ts`

##### E2E tests
- `test/app.e2e-spec.ts`

Tests as:
- validating controller/service behavior
- verifying real cache semantics:
- cache hits
- expiry
- invalidation

This is especially important because the README emphasizes that tests verify **real cache behavior**, not just mocks.

- separate controller, service, cache, and storage
- Read and invalidation paths
- make cache semantics explicit
- Tests as a supporting layer

## Diagram (Mermaid)

```mermaid
flowchart TD

    Client["Client / API Consumer"]:::external

    subgraph Runtime["Runtime / Request Path"]
        Main["NestJS Application Bootstrap<br/>src/main.ts"]:::nest
        AppModule["App Module<br/>Root Composition"]:::nest
        AppController["App Controller<br/>HTTP Entry"]:::controller
        AppService["App Service<br/>App Logic"]:::service
        PermissionsModule["Permissions Module<br/>Feature Module"]:::nest
        PermissionsController["Permissions Controller<br/>Permissions API"]:::controller
        PermissionsService["Permissions Service<br/>Cache-Aware Business Logic"]:::service
    end

    subgraph Caching["Caching & Source of Truth"]
        Cache["LRU Cache<br/>max • maxSize • TTL<br/>updateAgeOnGet: false<br/>bounded memory"]:::cache
        Storage["Permissions Storage / Source of Truth<br/>Authoritative permissions data"]:::store
        Invalidate["Cache Invalidation APIs<br/>invalidateUserPermissions(userId)<br/>clearPermissionsCache()"]:::cacheOp
        TTL["TTL Expiry<br/>stale entries revalidated"]:::note
    end

    subgraph Verification["Verification / Test Coverage"]
        UnitAppController["App Controller Unit Tests"]:::test
        UnitAppService["App Service Unit Tests"]:::test
        UnitPermController["Permissions Controller Unit Tests"]:::test
        UnitPermService["Permissions Service Unit Tests"]:::test
        E2E["End-to-End Tests<br/>app.e2e-spec.ts"]:::test
        JestCfg["E2E Jest Config<br/>jest-e2e.json"]:::tooling
    end

    subgraph Tooling["Project Configuration"]
        Package["Package Metadata / Dependencies<br/>package.json"]:::tooling
        NestCfg["NestJS Project Configuration<br/>nest-cli.json"]:::tooling
        TsCfg["TypeScript Configuration<br/>tsconfig.json"]:::tooling
        TsBuild["TypeScript Build Configuration<br/>tsconfig.build.json"]:::tooling
        ESLint["ESLint Configuration<br/>eslint.config.mjs"]:::tooling
        Prettier["Prettier Configuration<br/>.prettierrc"]:::tooling
    end

    Client -->|"HTTP request"| Main
    Main --> AppModule
    AppModule --> AppController
    AppController --> AppService
    AppModule --> PermissionsModule
    PermissionsModule --> PermissionsController
    PermissionsController --> PermissionsService

    PermissionsService -->|"cache lookup"| Cache
    Cache -->|"cache hit"| PermissionsService
    PermissionsService -->|"cache miss"| Storage
    Storage -->|"permissions data"| PermissionsService
    PermissionsService -->|"populate / refresh cache"| Cache
    PermissionsService -->|"HTTP response"| PermissionsController
    PermissionsController -->|"response"| Client

    PermissionsService -->|"invalidateUserPermissions(userId)"| Invalidate
    PermissionsService -->|"clearPermissionsCache()"| Invalidate
    Invalidate --> Cache
    TTL --> Cache
    Cache -.->|"eviction / expiry"| TTL

    UnitAppController -.-> AppController
    UnitAppService -.-> AppService
    UnitPermController -.-> PermissionsController
    UnitPermService -.-> PermissionsService
    E2E -.-> Main
    E2E -.-> PermissionsController
    E2E -.-> PermissionsService
    E2E -.-> Storage

    JestCfg -.-> E2E
    Package -.-> Main
    Package -.-> E2E
    NestCfg -.-> Main
    TsCfg -.-> Main
    TsBuild -.-> Main
    ESLint -.-> Package
    Prettier -.-> Package

    click Main "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/main.ts" "src/main.ts"
    click AppModule "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/app.module.ts" "src/app.module.ts"
    click AppController "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/app.controller.ts" "src/app.controller.ts"
    click AppService "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/app.service.ts" "src/app.service.ts"
    click PermissionsModule "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/permissions/permissions.module.ts" "src/permissions/permissions.module.ts"
    click PermissionsController "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/permissions/permissions.controller.ts" "src/permissions/permissions.controller.ts"
    click PermissionsService "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/permissions/permissions.service.ts" "src/permissions/permissions.service.ts"
    click Storage "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/storage.ts" "src/storage.ts"
    click UnitAppController "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/app.controller.spec.ts" "src/app.controller.spec.ts"
    click UnitAppService "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/app.service.spec.ts" "src/app.service.spec.ts"
    click UnitPermController "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/permissions/permissions.controller.spec.ts" "src/permissions/permissions.controller.spec.ts"
    click UnitPermService "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/src/permissions/permissions.service.spec.ts" "src/permissions/permissions.service.spec.ts"
    click E2E "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/test/app.e2e-spec.ts" "test/app.e2e-spec.ts"
    click JestCfg "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/test/jest-e2e.json" "test/jest-e2e.json"
    click NestCfg "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/nest-cli.json" "nest-cli.json"
    click TsCfg "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/tsconfig.json" "tsconfig.json"
    click TsBuild "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/tsconfig.build.json" "tsconfig.build.json"
    click ESLint "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/eslint.config.mjs" "eslint.config.mjs"
    click Prettier "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/.prettierrc" ".prettierrc"
    click Package "https://github.com/dev-hive-school/typescript-lru-cache/blob/main/package.json" "package.json"

    classDef external fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#0f172a;
    classDef nest fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#0f172a;
    classDef controller fill:#bfdbfe,stroke:#2563eb,stroke-width:2px,color:#0f172a;
    classDef service fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#0f172a;
    classDef cache fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#0f172a;
    classDef store fill:#e5e7eb,stroke:#6b7280,stroke-width:2px,color:#0f172a;
    classDef cacheOp fill:#fed7aa,stroke:#ea580c,stroke-width:2px,color:#0f172a;
    classDef note fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray: 4 3,color:#111827;
    classDef test fill:#f3e8ff,stroke:#a855f7,stroke-width:2px,stroke-dasharray: 5 3,color:#0f172a;
    classDef tooling fill:#eef2ff,stroke:#6366f1,stroke-width:1.5px,color:#0f172a;
```
