# amith-ganta/tessera-multi-tenant-rag architecture

> Architecture diagram of the GitHub repository amith-ganta/tessera-multi-tenant-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amith-ganta/tessera-multi-tenant-rag
- Repository: https://github.com/amith-ganta/tessera-multi-tenant-rag
- Video tour (about a minute): https://gitdiagram.com/amith-ganta/tessera-multi-tenant-rag/video

## Overview

Tessera is a multi-tenant document question-answering API. Users authenticate, upload tenant documents for indexing, then ask questions that are routed through retrieval and answer generation; optional evaluation can run synchronously or through a judge queue. The map also includes documented A2A agents, tenant safeguards, streaming, and the quality gate. Request and subsystem links follow the README; sampled code confirms selected API, indexing, routing, and worker behavior, but not every internal call.

Main entry points: [`src/api/app.py`](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/api/app.py) (FastAPI), [`src/rag/orchestrator.py`](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/orchestrator.py) (RAG Orchestrator), [`src/orchestrator/a2a_supervisor.py`](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/orchestrator/a2a_supervisor.py) (A2A Supervisor), [`src/judge/redis_queue.py`](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/judge/redis_queue.py) (Judge Queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access And API"]
  node_ui["Streamlit UI"]
  node_api["FastAPI<br/>[app.py]"]
  node_auth["User Authentication<br/>[auth.py]"]
  node_service_auth["A2A Service Auth<br/>[service_auth.py]"]
  node_governance["Tenant Governance"]
  node_rate["Rate Limiting<br/>[rate_limiter.py]"]
end

subgraph group_rag["Knowledge And Answers"]
  node_ingest["Document Ingestion<br/>[ingest.py]"]
  node_index[("Tenant Vector Index<br/>[retriever_dense.py]")]
  node_orchestrator["RAG Orchestrator<br/>[orchestrator.py]"]
  node_router["Query Router<br/>[router.py]"]
  node_cache["Semantic Cache<br/>[semantic_cache.py]"]
  node_hybrid["Hybrid Retrieval"]
  node_dense["Dense Retrieval<br/>[retriever_dense.py]"]
  node_sparse["Sparse Retrieval"]
  node_rerank["Reranking<br/>[reranker.py]"]
  node_generator["Answer Generation<br/>[generator.py]"]
end

subgraph group_quality["Evaluation And Agents"]
  node_guard["Answer Guard<br/>[answer_guard.py]"]
  node_eval["Evaluation Gate<br/>[gate.py]"]
  node_judge_queue["Judge Queue<br/>[redis_queue.py]"]
  node_worker["Judge Worker<br/>[judge_worker.py]"]
  node_judge_store[("Judge Results<br/>[judge_store.py]")]
  node_supervisor["A2A Supervisor<br/>[a2a_supervisor.py]"]
  node_drafter["Drafter Agent<br/>[drafter_agent.py]"]
  node_judge_agent["Judge Agent<br/>[judge_agent.py]"]
  node_checkpoint[("Agent Checkpoint")]
end

subgraph group_operations["Operations And State"]
  node_redis[("Redis")]
  node_signals["RAG Quality Signals<br/>[rag_signals.py]"]
  node_analytics[("Analytics Log<br/>[analytics.py]")]
  node_auth_db[("User Database<br/>[auth.py]")]
end

node_user(("User / Client"))
node_llm["LLM Provider"]
node_web["Tavily Search"]

node_user -->|"uses"| node_ui
node_ui -->|"sends requests"| node_api
node_user -->|"queries / uploads"| node_api
node_api -->|"authenticates"| node_auth
node_auth -->|"reads / writes"| node_auth_db
node_api -->|"checks limits"| node_rate
node_api -->|"checks tenant limits"| node_governance
node_api -->|"indexes uploads"| node_ingest
node_ingest -->|"builds index"| node_index
node_api -->|"runs strategy"| node_orchestrator
node_orchestrator -->|"routes query"| node_router
node_router -.->|"searches current info"| node_web
node_orchestrator -->|"checks cache"| node_cache
node_orchestrator -->|"retrieves context"| node_hybrid
node_hybrid -->|"retrieves vectors"| node_dense
node_hybrid -->|"retrieves terms"| node_sparse
node_dense -->|"queries"| node_index
node_orchestrator -->|"reranks results"| node_rerank
node_orchestrator -->|"generates answer"| node_generator
node_generator -->|"requests completion"| node_llm
node_api -->|"guards answer"| node_guard
node_guard -->|"evaluates / refines"| node_llm
node_api -->|"enqueues evaluation"| node_judge_queue
node_judge_queue -->|"stores jobs"| node_redis
node_worker -->|"claims jobs"| node_judge_queue
node_worker -->|"evaluates answer"| node_llm
node_worker -->|"stores result"| node_judge_queue
node_api -->|"reads evaluation"| node_judge_store
node_api -->|"dispatches A2A"| node_supervisor
node_supervisor -->|"authenticates calls"| node_service_auth
node_supervisor -->|"requests draft"| node_drafter
node_supervisor -->|"requests judgment"| node_judge_agent
node_supervisor -->|"persists state"| node_checkpoint
node_api -->|"runs quality gate"| node_eval
node_api -->|"records metrics"| node_signals
node_signals -->|"writes signals"| node_analytics

click node_ui "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/ui/app_streamlit_auth.py"
click node_api "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/api/app.py"
click node_auth "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/auth/auth.py"
click node_service_auth "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/auth/service_auth.py"
click node_governance "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/resilience/tenant_governance.py"
click node_rate "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/resilience/rate_limiter.py"
click node_ingest "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/ingest.py"
click node_index "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_dense.py"
click node_orchestrator "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/orchestrator.py"
click node_router "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/router.py"
click node_cache "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/cache/semantic_cache.py"
click node_hybrid "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_hybrid.py"
click node_dense "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_dense.py"
click node_sparse "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_sparse.py"
click node_rerank "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/reranker.py"
click node_generator "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/generator.py"
click node_guard "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/answer_guard.py"
click node_eval "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/evals/gate.py"
click node_judge_queue "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/judge/redis_queue.py"
click node_worker "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/judge_worker.py"
click node_judge_store "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/judge/judge_store.py"
click node_supervisor "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/orchestrator/a2a_supervisor.py"
click node_drafter "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/agents/drafter_agent.py"
click node_judge_agent "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/agents/judge_agent.py"
click node_checkpoint "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/state/redis_checkpointer.py"
click node_signals "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/observability/rag_signals.py"
click node_analytics "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/analytics.py"
click node_auth_db "https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/auth/auth.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_ui,node_api,node_auth,node_service_auth,node_governance,node_rate,node_user toneBlue
class node_ingest,node_index,node_orchestrator,node_router,node_cache,node_hybrid,node_dense,node_sparse,node_rerank,node_generator toneAmber
class node_guard,node_eval,node_judge_queue,node_worker,node_judge_store,node_supervisor,node_drafter,node_judge_agent,node_checkpoint toneMint
class node_redis,node_signals,node_analytics,node_auth_db toneRose
class node_llm,node_web toneIndigo
```

## Components

### Access And API

- [Streamlit UI](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/ui/app_streamlit_auth.py): `src/ui/app_streamlit_auth.py`
- [FastAPI](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/api/app.py): `src/api/app.py`
- [User Authentication](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/auth/auth.py): `src/auth/auth.py`
- [A2A Service Auth](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/auth/service_auth.py): `src/auth/service_auth.py`
- [Tenant Governance](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/resilience/tenant_governance.py): `src/resilience/tenant_governance.py`
- [Rate Limiting](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/resilience/rate_limiter.py): `src/resilience/rate_limiter.py`

### Knowledge And Answers

- [Document Ingestion](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/ingest.py): `src/rag/ingest.py`
- [Tenant Vector Index](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_dense.py): `src/rag/retriever_dense.py`
- [RAG Orchestrator](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/orchestrator.py): `src/rag/orchestrator.py`
- [Query Router](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/router.py): `src/rag/router.py`
- [Semantic Cache](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/cache/semantic_cache.py): `src/cache/semantic_cache.py`
- [Hybrid Retrieval](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_hybrid.py): `src/rag/retriever_hybrid.py`
- [Dense Retrieval](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_dense.py): `src/rag/retriever_dense.py`
- [Sparse Retrieval](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/retriever_sparse.py): `src/rag/retriever_sparse.py`
- [Reranking](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/reranker.py): `src/rag/reranker.py`
- [Answer Generation](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/generator.py): `src/rag/generator.py`

### Evaluation And Agents

- [Answer Guard](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/answer_guard.py): `src/rag/answer_guard.py`
- [Evaluation Gate](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/evals/gate.py): `evals/gate.py`
- [Judge Queue](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/judge/redis_queue.py): `src/judge/redis_queue.py`
- [Judge Worker](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/judge_worker.py): `judge_worker.py`
- [Judge Results](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/judge/judge_store.py): `src/judge/judge_store.py`
- [A2A Supervisor](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/orchestrator/a2a_supervisor.py): `src/orchestrator/a2a_supervisor.py`
- [Drafter Agent](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/agents/drafter_agent.py): `src/agents/drafter_agent.py`
- [Judge Agent](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/agents/judge_agent.py): `src/agents/judge_agent.py`
- [Agent Checkpoint](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/state/redis_checkpointer.py): `src/state/redis_checkpointer.py`

### Operations And State

- **Redis**
- [RAG Quality Signals](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/observability/rag_signals.py): `src/observability/rag_signals.py`
- [Analytics Log](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/rag/analytics.py): `src/rag/analytics.py`
- [User Database](https://github.com/amith-ganta/tessera-multi-tenant-rag/blob/main/src/auth/auth.py): `src/auth/auth.py`

### Other components

- **User / Client**
- **LLM Provider**
- **Tavily Search**

## Connections

- User / Client → Streamlit UI: uses
- Streamlit UI → FastAPI: sends requests
- User / Client → FastAPI: queries / uploads
- FastAPI → User Authentication: authenticates
- User Authentication → User Database: reads / writes
- FastAPI → Rate Limiting: checks limits
- FastAPI → Tenant Governance: checks tenant limits
- FastAPI → Document Ingestion: indexes uploads
- Document Ingestion → Tenant Vector Index: builds index
- FastAPI → RAG Orchestrator: runs strategy
- RAG Orchestrator → Query Router: routes query
- Query Router → Tavily Search: searches current info
- RAG Orchestrator → Semantic Cache: checks cache
- RAG Orchestrator → Hybrid Retrieval: retrieves context
- Hybrid Retrieval → Dense Retrieval: retrieves vectors
- Hybrid Retrieval → Sparse Retrieval: retrieves terms
- Dense Retrieval → Tenant Vector Index: queries
- RAG Orchestrator → Reranking: reranks results
- RAG Orchestrator → Answer Generation: generates answer
- Answer Generation → LLM Provider: requests completion
- FastAPI → Answer Guard: guards answer
- Answer Guard → LLM Provider: evaluates / refines
- FastAPI → Judge Queue: enqueues evaluation
- Judge Queue → Redis: stores jobs
- Judge Worker → Judge Queue: claims jobs
- Judge Worker → LLM Provider: evaluates answer
- Judge Worker → Judge Queue: stores result
- FastAPI → Judge Results: reads evaluation
- FastAPI → A2A Supervisor: dispatches A2A
- A2A Supervisor → A2A Service Auth: authenticates calls
- A2A Supervisor → Drafter Agent: requests draft
- A2A Supervisor → Judge Agent: requests judgment
- A2A Supervisor → Agent Checkpoint: persists state
- FastAPI → Evaluation Gate: runs quality gate
- FastAPI → RAG Quality Signals: records metrics
- RAG Quality Signals → Analytics Log: writes signals