LightRAG/docs/archives/action_plan/multitenant-audit/00-audit-overview.md

Multi-Tenant Architecture Audit

Date: November 29, 2025
Auditor: GitHub Copilot
Branch: feat/multi-tenannt
Scope: Full stack audit from Web UI to REST API to Storage

---

Executive Summary

This audit examines the multi-tenant implementation in LightRAG, covering:

• Web UI Layer (React/TypeScript frontend)
• REST API Layer (FastAPI backend)
• Storage Layer (PostgreSQL, Redis, Vector DBs)

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Web UI Layer                             │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐ │
│  │ TenantStore │  │ API Client   │  │ DocumentManager/Query   │ │
│  │ (Zustand)   │◄─┤ (Axios)      │◄─┤ Components              │ │
│  └─────────────┘  └──────────────┘  └─────────────────────────┘ │
│         │                │                      │                │
│         └────────────────┼──────────────────────┘                │
│                          ▼                                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │           HTTP Headers: X-Tenant-ID, X-KB-ID              │  │
│  └───────────────────────────────────────────────────────────┘  │
└────────────────────────────────┬────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                        REST API Layer                            │
│  ┌──────────────┐  ┌───────────────────┐  ┌──────────────────┐  │
│  │ Middleware   │  │ Dependencies      │  │ Route Handlers   │  │
│  │ (Tenant     │──▶│ (get_tenant_ctx)  │──▶│ (Query/Doc/etc) │  │
│  │  Context)    │  │                   │  │                  │  │
│  └──────────────┘  └───────────────────┘  └──────────────────┘  │
│                           │                        │             │
│                           ▼                        ▼             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              TenantRAGManager                             │   │
│  │  - Per-tenant LightRAG instances                          │   │
│  │  - LRU caching with isolation                            │   │
│  │  - User access verification                               │   │
│  └──────────────────────────────────────────────────────────┘   │
└────────────────────────────────┬────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Storage Layer                              │
│  ┌─────────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│  │ PostgreSQL      │  │ Redis        │  │ Vector DBs       │    │
│  │ - tenant_id     │  │ - Namespace  │  │ - Metadata       │    │
│  │ - kb_id columns │  │   prefixes   │  │   filtering      │    │
│  │ - Composite PK  │  │              │  │                  │    │
│  └─────────────────┘  └──────────────┘  └──────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Audit Components

1. Web UI Layer

• Tenant store state management
• API client header propagation
• Tenant/KB selection persistence
• Cross-component context sharing
• Document filtering by tenant/KB
• Query scoping by tenant/KB

2. REST API Layer

• Middleware tenant context extraction
• Dependency injection for tenant context
• Route handler tenant awareness
• TenantRAGManager isolation
• TenantService operations
• User access verification

3. Storage Layer

• PostgreSQL multi-tenant schema
• Redis namespace isolation
• Vector DB metadata filtering
• Composite key enforcement
• Cross-tenant data access prevention

Test Environment Setup

Configuration:

• Web UI: Local development (not Docker)
• REST API: Local development (not Docker)
• Database: Docker container (PostgreSQL + pgvector)
• Redis: Docker container

Documents in this Audit

1. 00-audit-overview.md - This overview document
2. 01-test-protocol.md - Detailed test protocol and setup instructions
3. 02-webui-audit.md - Web UI layer findings
4. 03-api-audit.md - REST API layer findings
5. 04-storage-audit.md - Storage layer findings
6. 05-test-execution-log.md - Test execution progress and results
7. 06-issues-found.md - Issues discovered during audit
8. 07-recommendations.md - Final recommendations

Key Files Under Audit

Web UI

• lightrag_webui/src/stores/tenant.ts - Tenant state management
• lightrag_webui/src/api/client.ts - Axios interceptor for headers
• lightrag_webui/src/api/tenant.ts - Tenant/KB API functions
• lightrag_webui/src/features/DocumentManager.tsx - Document operations
• lightrag_webui/src/features/ChatQueryPanel.tsx - Query operations

REST API

• lightrag/api/dependencies.py - Tenant context extraction
• lightrag/api/routers/tenant_routes.py - Tenant CRUD
• lightrag/api/routers/document_routes.py - Document operations
• lightrag/api/routers/query_routes.py - Query operations
• lightrag/tenant_rag_manager.py - RAG instance management
• lightrag/services/tenant_service.py - Tenant business logic

Storage

• lightrag/kg/postgres_impl.py - PostgreSQL storage
• lightrag/kg/postgres_tenant_support.py - Tenant SQL utilities
• lightrag/kg/redis_tenant_support.py - Redis namespace utilities
• lightrag/kg/vector_tenant_support.py - Vector DB utilities