docs: update architecture diagrams and guides for Valkey cache

Add Valkey to architecture diagrams in README.md and docs/architecture.md.
Add VALKEY_URL to configuration.md environment variables table.
Update deployment-guide.md service count (3→4) with Valkey description.
Update development-setup.md to mention Valkey startup and localhost:6379.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: pinkroosterai

README.md

@@ -136,18 +136,19 @@ Clarive focuses on **prompt authoring, refinement, and team management**. If you
 
 ## Architecture
 
-One container: nginx serves the frontend and proxies `/api/` to the .NET backend.
+One container: nginx serves the frontend and proxies `/api/` to the .NET backend. PostgreSQL and Valkey run as separate Docker services.
 
 ```
                :8080 (nginx)
 ┌─────────────────────────────────┐     ┌──────────────┐
 │         Clarive Container       │     │  PostgreSQL   │
 │  ┌──────────┐   ┌────────────┐  │────▶│     16        │
-│  │  nginx   │──▶│ .NET 10 API│  │     │               │
-│  │ (frontend)│  │ (backend)  │  │     └──────────────┘
-│  └──────────┘   └────────────┘  │
-│         supervisor              │
-└─────────────────────────────────┘
+│  │  nginx   │──▶│ .NET 10 API│  │     └──────────────┘
+│  │ (frontend)│  │ (backend)  │  │
+│  └──────────┘   └────────────┘  │────▶┌──────────────┐
+│         supervisor              │     │   Valkey 8   │
+└─────────────────────────────────┘     │   (cache)    │
+                                        └──────────────┘
 ```
 
 For the full tech stack, project structure, and design details, see [docs/architecture.md](docs/architecture.md).

docs/architecture.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Clarive is a multi-tenant platform for managing, versioning, and AI-enhancing LLM prompts. A React frontend talks to a C# backend, backed by PostgreSQL. Everything ships as a single container.
+Clarive is a multi-tenant platform for managing, versioning, and AI-enhancing LLM prompts. A React frontend talks to a C# backend, backed by PostgreSQL and Valkey. Everything ships as a single container with separate database and cache services.
 
 ## System Diagram
 
@@ -20,16 +20,16 @@ Clarive is a multi-tenant platform for managing, versioning, and AI-enhancing LL
               │ (React)  │  │ (ASP.NET) │
               └──────────┘  └─────┬─────┘
                                   │
-                    ┌─────────────┼─────────────┐
-                    │             │             │
-              ┌─────▼─────┐ ┌────▼────┐ ┌──────▼──────┐
-              │ PostgreSQL │ │   AI    │ │   Google    │
-              │     16     │ │ (OpenAI │ │   OAuth     │
-              │            │ │ compat) │ │             │
-              └────────────┘ └─────────┘ └─────────────┘
+                 ┌────────────┬───┴───┬─────────────┐
+                 │            │       │             │
+           ┌─────▼─────┐ ┌───▼───┐ ┌─▼───────┐ ┌──▼──────────┐
+           │ PostgreSQL │ │Valkey │ │   AI    │ │   Google    │
+           │     16     │ │  8    │ │ (OpenAI │ │   OAuth     │
+           │            │ │(cache)│ │ compat) │ │             │
+           └────────────┘ └───────┘ └─────────┘ └─────────────┘
 ```
 
-Nginx serves the React build and proxies `/api/` to the .NET backend. Supervisor manages both processes inside the container.
+Nginx serves the React build and proxies `/api/` to the .NET backend. Supervisor manages both processes inside the container. PostgreSQL and Valkey run as separate Docker services.
 
 ## Tech Stack
 
@@ -40,11 +40,12 @@ Nginx serves the React build and proxies `/api/` to the .NET backend. Supervisor
 | Backend | C# ASP.NET Core 10 Minimal APIs |
 | ORM | EF Core 10 (Npgsql) with 25 entity configurations |
 | Database | PostgreSQL 16 with EF Core migrations |
+| Cache | Valkey 8 (distributed cache with AOF persistence), tenant-scoped TenantCacheService |
 | Auth | JWT (15-min access) + rotating refresh tokens (7-day), Google OIDC, API keys |
 | AI | Any OpenAI-compatible provider via Microsoft.Extensions.AI, agent-based orchestration |
 | Search | Tavily web search integration for research-backed generation |
 | Testing | xUnit + Testcontainers (backend), Vitest (frontend unit), Playwright (E2E) |
-| Infra | Docker Compose, Makefile (35+ commands), single unified container |
+| Infra | Docker Compose (app + PostgreSQL + Valkey), Makefile (35+ commands) |
 
 ## Components
 

docs/configuration.md

@@ -31,6 +31,7 @@ These are the only settings you need in your `.env` file. Run `make setup` to ge
 | `JWT_ISSUER` | JWT issuer claim | `Clarive` |
 | `JWT_AUDIENCE` | JWT audience claim | `Clarive` |
 | `ASPNETCORE_ENVIRONMENT` | ASP.NET environment | `Production` |
+| `VALKEY_URL` | Valkey cache connection (host:port) | `valkey:6379` |
 
 > **Note:** `CORS_ORIGINS` is the only application setting that requires a container restart. Everything else can be changed at runtime through the dashboard.
 

docs/deployment-guide.md

@@ -61,13 +61,14 @@ make db-reset                         # Destroy all database volumes (with confi
 
 ## Docker Architecture
 
-The compose file (`deploy/docker-compose.yml`) defines three services:
+The compose file (`deploy/docker-compose.yml`) defines four services:
 
 - **postgres** — PostgreSQL 16 with health check
+- **valkey** — Valkey 8 cache with AOF persistence, 256MB maxmemory, allkeys-lru eviction
 - **backend** — ASP.NET Core API (internal port 5000, not exposed to host)
 - **frontend** — React app served by nginx (port 8080), proxies `/api/` to backend
 
-All services communicate over Docker's default network. Only port 8080 is exposed to the host.
+All services communicate over Docker's default network. Only port 8080 is exposed to the host. Valkey and PostgreSQL are internal-only.
 
 ```
 Browser → :8080 (nginx)

docs/development-setup.md

@@ -17,14 +17,15 @@ Development runs entirely in Docker with hot reload. No local SDKs needed.
 git clone https://github.com/pinkroosterai/Clarive.git
 cd Clarive
 make setup    # generates .env with dev defaults
-make dev      # starts postgres, backend, and frontend with hot reload
+make dev      # starts postgres, valkey, backend, and frontend with hot reload
 ```
 
 Open **http://localhost:8080**. The Vite dev server proxies `/api/` requests to the backend.
 
 - Frontend hot reloads via Vite HMR
 - Backend hot reloads via `dotnet watch`
 - PostgreSQL is accessible on `localhost:5433` (mapped from container port 5432)
+- Valkey cache is accessible on `localhost:6379`
 
 ## Building from Source