# axm1647/fastapi-semcache architecture

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

- Interactive diagram: https://gitdiagram.com/axm1647/fastapi-semcache
- Repository: https://github.com/axm1647/fastapi-semcache

## Overview

fastapi-semcache is a semantic response-caching library for FastAPI/ASGI APIs, with an optional reverse-proxy mode. A request enters the middleware, which extracts query and scope information and asks SemanticCache for a match; on a hit it replays the stored response, and on a miss it invokes the downstream app and may store the response. SemanticCache coordinates embedding, pgvector similarity search, and optional Redis response blobs. The README documents multiple embedding providers and proxy support; sampled source confirms the main middleware, cache, and proxy wiring, while some provider and storage details are represented at their tree-supported directory paths.

Main entry points: [`semanticcache/middleware/adapters/fastapi/middleware.py`](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/adapters/fastapi/middleware.py) (ASGI middleware), [`semanticcache/cache.py`](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/cache.py) (SemanticCache), [`semanticcache/proxy.py`](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/proxy.py) (Proxy app), [`semanticcache/embedders`](https://github.com/axm1647/fastapi-semcache/tree/master/semanticcache/embedders) (Embedder backends)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request_path["Request handling"]
  node_middleware["ASGI middleware<br/>[middleware.py]"]
  node_request_extract["Request extraction<br/>[extractors.py]"]
  node_coordination["Request coordination<br/>[coordination.py]"]
  node_replay["Response replay<br/>[replay.py]"]
  node_proxy["Proxy app<br/>[proxy.py]"]
end

subgraph group_cache_core["Cache core"]
  node_cache["SemanticCache<br/>[cache.py]"]
  node_settings["Cache settings<br/>[config.py]"]
end

subgraph group_embedding["Embedding"]
  node_embedder_base["Embedder interface<br/>[_base.py]"]
  node_embedder_backends["Embedder backends"]
end

subgraph group_persistence["Persistence"]
  node_vector_store["Vector store<br/>[pgvector.py]"]
  node_postgres[("Postgres pgvector")]
  node_response_store["Redis response store<br/>[redis_store.py]"]
  node_redis[("Redis")]
  node_storage_ids["Storage identifiers<br/>[storage_ids.py]"]
end

node_client(("API client"))
node_downstream["Downstream app"]
node_upstream(("Upstream API"))
node_embedding_provider(("Embedding providers"))

node_client -->|"sends request"| node_middleware
node_middleware -->|"extracts fields"| node_request_extract
node_middleware -->|"coordinates request"| node_coordination
node_middleware -->|"looks up"| node_cache
node_cache -->|"embeds query"| node_embedder_base
node_embedder_backends -->|"implements"| node_embedder_base
node_embedder_backends -.->|"requests embeddings"| node_embedding_provider
node_cache -->|"searches and writes"| node_vector_store
node_vector_store -->|"queries vectors"| node_postgres
node_cache -->|"reads and writes blobs"| node_response_store
node_response_store -.->|"stores JSON"| node_redis
node_cache -->|"uses configuration"| node_settings
node_cache -->|"derives identifiers"| node_storage_ids
node_middleware -->|"replays hit"| node_replay
node_replay -->|"sends response"| node_client
node_middleware -->|"dispatches miss"| node_downstream
node_downstream -->|"returns response"| node_middleware
node_middleware -.->|"dispatches proxy request"| node_proxy
node_proxy -.->|"forwards HTTP"| node_upstream
node_upstream -.->|"returns HTTP response"| node_proxy

click node_middleware "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/adapters/fastapi/middleware.py"
click node_request_extract "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/core/extractors.py"
click node_coordination "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/core/coordination.py"
click node_replay "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/core/replay.py"
click node_proxy "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/proxy.py"
click node_cache "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/cache.py"
click node_settings "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/config.py"
click node_embedder_base "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/embedders/_base.py"
click node_embedder_backends "https://github.com/axm1647/fastapi-semcache/tree/master/semanticcache/embedders"
click node_vector_store "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/stores/vector/pgvector.py"
click node_response_store "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/stores/response/redis_store.py"
click node_storage_ids "https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/stores/vector/storage_ids.py"

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_middleware,node_request_extract,node_coordination,node_replay,node_proxy,node_client toneBlue
class node_cache,node_settings toneAmber
class node_embedder_base,node_embedder_backends,node_upstream toneMint
class node_vector_store,node_postgres,node_response_store,node_redis,node_storage_ids toneRose
class node_downstream,node_embedding_provider toneIndigo
```

## Components

### Request handling

- [ASGI middleware](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/adapters/fastapi/middleware.py): `semanticcache/middleware/adapters/fastapi/middleware.py`
- [Request extraction](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/core/extractors.py): `semanticcache/middleware/core/extractors.py`
- [Request coordination](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/core/coordination.py): `semanticcache/middleware/core/coordination.py`
- [Response replay](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/middleware/core/replay.py): `semanticcache/middleware/core/replay.py`
- [Proxy app](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/proxy.py): `semanticcache/proxy.py`

### Cache core

- [SemanticCache](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/cache.py): `semanticcache/cache.py`
- [Cache settings](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/config.py): `semanticcache/config.py`

### Embedding

- [Embedder interface](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/embedders/_base.py): `semanticcache/embedders/_base.py`
- [Embedder backends](https://github.com/axm1647/fastapi-semcache/tree/master/semanticcache/embedders): `semanticcache/embedders`

### Persistence

- [Vector store](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/stores/vector/pgvector.py): `semanticcache/stores/vector/pgvector.py`
- **Postgres pgvector**
- [Redis response store](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/stores/response/redis_store.py): `semanticcache/stores/response/redis_store.py`
- **Redis**
- [Storage identifiers](https://github.com/axm1647/fastapi-semcache/blob/master/semanticcache/stores/vector/storage_ids.py): `semanticcache/stores/vector/storage_ids.py`

### Other components

- **API client**
- **Downstream app**
- **Upstream API**
- **Embedding providers**

## Connections

- API client → ASGI middleware: sends request
- ASGI middleware → Request extraction: extracts fields
- ASGI middleware → Request coordination: coordinates request
- ASGI middleware → SemanticCache: looks up
- SemanticCache → Embedder interface: embeds query
- Embedder backends → Embedder interface: implements
- Embedder backends → Embedding providers: requests embeddings
- SemanticCache → Vector store: searches and writes
- Vector store → Postgres pgvector: queries vectors
- SemanticCache → Redis response store: reads and writes blobs
- Redis response store → Redis: stores JSON
- SemanticCache → Cache settings: uses configuration
- SemanticCache → Storage identifiers: derives identifiers
- ASGI middleware → Response replay: replays hit
- Response replay → API client: sends response
- ASGI middleware → Downstream app: dispatches miss
- Downstream app → ASGI middleware: returns response
- ASGI middleware → Proxy app: dispatches proxy request
- Proxy app → Upstream API: forwards HTTP
- Upstream API → Proxy app: returns HTTP response