# git-me-harish/textlens architecture

> Architecture diagram of the GitHub repository git-me-harish/textlens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/git-me-harish/textlens
- Repository: https://github.com/git-me-harish/textlens

## Overview

TextLens is a document-intelligence platform: users upload documents for OCR and domain-specific extraction, then can search/chat over them or launch approval-gated actions. It also supports PDF tools, batch and scheduled processing, recovery, and integrations. The graph combines documented workflows with relationships visible in sampled source and the SOURCE INDEX; several route and feature implementations were not sampled, so their internal connections are omitted.

Main entry points: [`backend/app/api/routes`](https://github.com/git-me-harish/textlens/tree/main/backend/app/api/routes) (API routes), [`frontend/src/App.jsx`](https://github.com/git-me-harish/textlens/blob/main/frontend/src/App.jsx) (React application), [`backend/app/worker/tasks.py`](https://github.com/git-me-harish/textlens/blob/main/backend/app/worker/tasks.py) (Background processing), [`backend/app/worker/action_tasks.py`](https://github.com/git-me-harish/textlens/blob/main/backend/app/worker/action_tasks.py) (Action worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["React application<br/>[App.jsx]"]
  node_pipelines_ui["Pipelines UI<br/>[PipelinesPage.jsx]"]
  node_pdf_chat_ui["PDF chat UI<br/>[PDFChatPage.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_sse_client["SSE updates<br/>[useSSE.js]"]
  node_auth_context["Authentication state<br/>[AuthContext.jsx]"]
end

subgraph group_api["API and services"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_routes["API routes"]
  node_action_routes["Action routes"]
  node_mcp_routes["MCP proxy routes<br/>[mcp_common.py]"]
  node_notification_service["Notifications"]
end

subgraph group_processing["Document processing"]
  node_ocr["OCR and extraction<br/>[ocr_service.py]"]
  node_worker_tasks["Background processing<br/>[tasks.py]"]
  node_agent_service["Domain pipelines<br/>[agent_service.py]"]
  node_rag["Hybrid document search<br/>[rag_service.py]"]
  node_embeddings["Embedding service"]
end

subgraph group_actions["Agentic actions"]
  node_action_worker["Action worker<br/>[action_tasks.py]"]
  node_action_service["Action service<br/>[action_service.py]"]
  node_agent_router["Domain agent router<br/>[agent_router.py]"]
  node_domain_agents["Domain agents"]
  node_approval["Approval service"]
  node_mcp_registry["MCP service registry<br/>[registry.py]"]
end

subgraph group_data["Data and integrations"]
  node_database[("PostgreSQL")]
  node_redis[("Redis")]
  node_object_store[("S3-compatible storage")]
  node_models["Domain and job models<br/>[models.py]"]
  node_db_layer["Database access<br/>[database.py]"]
  node_redis_layer["Redis access<br/>[redis.py]"]
  node_storage_service["File storage<br/>[storage_service.py]"]
  node_external_services{{"Connected services"}}
  node_llm{{"Extraction LLM"}}
  node_embedding_provider{{"Voyage AI"}}
  node_chat_provider{{"Groq chat model"}}
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_pipelines_ui
node_webapp -->|"routes to"| node_pdf_chat_ui
node_webapp -->|"provides auth"| node_auth_context
node_webapp -->|"starts updates"| node_sse_client
node_pipelines_ui -->|"submits jobs"| node_api_client
node_pipelines_ui -->|"awaits job"| node_sse_client
node_webapp -->|"calls API"| node_api_app
node_api_app -->|"mounts routes"| node_api_routes
node_api_app -->|"initializes storage"| node_storage_service
node_api_app -->|"mounts actions"| node_action_routes
node_api_routes -->|"queues processing"| node_worker_tasks
node_worker_tasks -->|"runs OCR"| node_ocr
node_worker_tasks -->|"uses file storage"| node_storage_service
node_worker_tasks -->|"runs pipelines"| node_agent_service
node_worker_tasks -->|"ingests documents"| node_rag
node_agent_service -->|"requests extraction"| node_llm
node_pdf_chat_ui -->|"requests chat"| node_api_routes
node_api_routes -->|"retrieves context"| node_rag
node_rag -->|"embeds query"| node_embeddings
node_rag -->|"searches chunks"| node_database
node_rag -->|"caches results"| node_redis_layer
node_embeddings -->|"creates vectors"| node_embedding_provider
node_api_routes -->|"answers chat"| node_chat_provider
node_api_routes -->|"dispatches actions"| node_action_routes
node_action_routes -->|"queues action"| node_action_worker
node_action_worker -->|"runs action logic"| node_action_service
node_action_worker -->|"resolves agent"| node_agent_router
node_agent_router -->|"instantiates agent"| node_domain_agents
node_action_worker -->|"requests approval"| node_approval
node_action_worker -->|"invokes services"| node_mcp_registry
node_mcp_registry -->|"calls proxy"| node_mcp_routes
node_mcp_routes -->|"forwards requests"| node_external_services
node_action_worker -->|"publishes updates"| node_sse_client
node_worker_tasks -->|"publishes status"| node_sse_client
node_api_app -->|"streams events"| node_redis_layer
node_db_layer -->|"opens sessions"| node_database
node_redis_layer -->|"connects"| node_redis
node_storage_service -->|"stores files"| node_object_store
node_db_layer -->|"provides ORM"| node_models
node_api_routes -.->|"sends notifications"| node_notification_service

click node_webapp "https://github.com/git-me-harish/textlens/blob/main/frontend/src/App.jsx"
click node_pipelines_ui "https://github.com/git-me-harish/textlens/blob/main/frontend/src/pages/PipelinesPage.jsx"
click node_pdf_chat_ui "https://github.com/git-me-harish/textlens/blob/main/frontend/src/pages/PDFChatPage.jsx"
click node_api_client "https://github.com/git-me-harish/textlens/blob/main/frontend/src/lib/api.js"
click node_sse_client "https://github.com/git-me-harish/textlens/blob/main/frontend/src/hooks/useSSE.js"
click node_auth_context "https://github.com/git-me-harish/textlens/blob/main/frontend/src/lib/AuthContext.jsx"
click node_api_app "https://github.com/git-me-harish/textlens/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/git-me-harish/textlens/tree/main/backend/app/api/routes"
click node_action_routes "https://github.com/git-me-harish/textlens/tree/main/backend/app/api/routes/actions"
click node_models "https://github.com/git-me-harish/textlens/blob/main/backend/app/models/models.py"
click node_db_layer "https://github.com/git-me-harish/textlens/blob/main/backend/app/db/database.py"
click node_redis_layer "https://github.com/git-me-harish/textlens/blob/main/backend/app/db/redis.py"
click node_storage_service "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/storage_service.py"
click node_ocr "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/ocr_service.py"
click node_worker_tasks "https://github.com/git-me-harish/textlens/blob/main/backend/app/worker/tasks.py"
click node_agent_service "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/agent_service.py"
click node_rag "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/rag_service.py"
click node_embeddings "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/embedding_service.py"
click node_action_worker "https://github.com/git-me-harish/textlens/blob/main/backend/app/worker/action_tasks.py"
click node_action_service "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/action_service.py"
click node_agent_router "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/actions/agent_router.py"
click node_domain_agents "https://github.com/git-me-harish/textlens/tree/main/backend/app/services/actions"
click node_approval "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/approval_service.py"
click node_mcp_registry "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/mcp/registry.py"
click node_mcp_routes "https://github.com/git-me-harish/textlens/blob/main/backend/app/api/routes/mcp_common.py"
click node_notification_service "https://github.com/git-me-harish/textlens/blob/main/backend/app/services/notification_service.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_webapp,node_pipelines_ui,node_pdf_chat_ui,node_api_client,node_sse_client,node_auth_context,node_user toneBlue
class node_api_app,node_api_routes,node_action_routes,node_mcp_routes,node_notification_service toneAmber
class node_ocr,node_worker_tasks,node_agent_service,node_rag,node_embeddings toneMint
class node_action_worker,node_action_service,node_agent_router,node_domain_agents,node_approval,node_mcp_registry toneRose
class node_database,node_redis,node_object_store,node_models,node_db_layer,node_redis_layer,node_storage_service,node_external_services,node_llm,node_embedding_provider,node_chat_provider toneIndigo
```

## Components

### Web client

- [React application](https://github.com/git-me-harish/textlens/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Pipelines UI](https://github.com/git-me-harish/textlens/blob/main/frontend/src/pages/PipelinesPage.jsx): `frontend/src/pages/PipelinesPage.jsx`
- [PDF chat UI](https://github.com/git-me-harish/textlens/blob/main/frontend/src/pages/PDFChatPage.jsx): `frontend/src/pages/PDFChatPage.jsx`
- [API client](https://github.com/git-me-harish/textlens/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`
- [SSE updates](https://github.com/git-me-harish/textlens/blob/main/frontend/src/hooks/useSSE.js): `frontend/src/hooks/useSSE.js`
- [Authentication state](https://github.com/git-me-harish/textlens/blob/main/frontend/src/lib/AuthContext.jsx): `frontend/src/lib/AuthContext.jsx`

### API and services

- [FastAPI application](https://github.com/git-me-harish/textlens/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/git-me-harish/textlens/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Action routes](https://github.com/git-me-harish/textlens/tree/main/backend/app/api/routes/actions): `backend/app/api/routes/actions`
- [MCP proxy routes](https://github.com/git-me-harish/textlens/blob/main/backend/app/api/routes/mcp_common.py): `backend/app/api/routes/mcp_common.py`
- [Notifications](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/notification_service.py): `backend/app/services/notification_service.py`

### Document processing

- [OCR and extraction](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/ocr_service.py): `backend/app/services/ocr_service.py`
- [Background processing](https://github.com/git-me-harish/textlens/blob/main/backend/app/worker/tasks.py): `backend/app/worker/tasks.py`
- [Domain pipelines](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/agent_service.py): `backend/app/services/agent_service.py`
- [Hybrid document search](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Embedding service](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`

### Agentic actions

- [Action worker](https://github.com/git-me-harish/textlens/blob/main/backend/app/worker/action_tasks.py): `backend/app/worker/action_tasks.py`
- [Action service](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/action_service.py): `backend/app/services/action_service.py`
- [Domain agent router](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/actions/agent_router.py): `backend/app/services/actions/agent_router.py`
- [Domain agents](https://github.com/git-me-harish/textlens/tree/main/backend/app/services/actions): `backend/app/services/actions`
- [Approval service](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/approval_service.py): `backend/app/services/approval_service.py`
- [MCP service registry](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/mcp/registry.py): `backend/app/services/mcp/registry.py`

### Data and integrations

- **PostgreSQL**
- **Redis**
- **S3-compatible storage**
- [Domain and job models](https://github.com/git-me-harish/textlens/blob/main/backend/app/models/models.py): `backend/app/models/models.py`
- [Database access](https://github.com/git-me-harish/textlens/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Redis access](https://github.com/git-me-harish/textlens/blob/main/backend/app/db/redis.py): `backend/app/db/redis.py`
- [File storage](https://github.com/git-me-harish/textlens/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- **Connected services**
- **Extraction LLM**
- **Voyage AI**
- **Groq chat model**

### Other components

- **User**

## Connections

- User → React application: uses
- React application → Pipelines UI: routes to (evidence: `frontend/src/App.jsx`)
- React application → PDF chat UI: routes to (evidence: `frontend/src/App.jsx`)
- React application → Authentication state: provides auth (evidence: `frontend/src/App.jsx`)
- React application → SSE updates: starts updates (evidence: `frontend/src/App.jsx`)
- Pipelines UI → API client: submits jobs (evidence: `frontend/src/pages/PipelinesPage.jsx`)
- Pipelines UI → SSE updates: awaits job (evidence: `frontend/src/pages/PipelinesPage.jsx`)
- React application → FastAPI application: calls API
- FastAPI application → API routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → File storage: initializes storage (evidence: `backend/app/main.py`)
- FastAPI application → Action routes: mounts actions (evidence: `backend/app/main.py`)
- API routes → Background processing: queues processing
- Background processing → OCR and extraction: runs OCR (evidence: `backend/app/worker/tasks.py`)
- Background processing → File storage: uses file storage (evidence: `backend/app/worker/tasks.py`)
- Background processing → Domain pipelines: runs pipelines (evidence: `backend/app/worker/tasks.py`)
- Background processing → Hybrid document search: ingests documents (evidence: `backend/app/worker/tasks.py`)
- Domain pipelines → Extraction LLM: requests extraction
- PDF chat UI → API routes: requests chat
- API routes → Hybrid document search: retrieves context
- Hybrid document search → Embedding service: embeds query (evidence: `backend/app/services/rag_service.py`)
- Hybrid document search → PostgreSQL: searches chunks (evidence: `backend/app/services/rag_service.py`)
- Hybrid document search → Redis access: caches results (evidence: `backend/app/services/rag_service.py`)
- Embedding service → Voyage AI: creates vectors (evidence: `backend/app/services/embedding_service.py`)
- API routes → Groq chat model: answers chat
- API routes → Action routes: dispatches actions
- Action routes → Action worker: queues action
- Action worker → Action service: runs action logic (evidence: `backend/app/worker/action_tasks.py`)
- Action worker → Domain agent router: resolves agent (evidence: `backend/app/worker/action_tasks.py`)
- Domain agent router → Domain agents: instantiates agent (evidence: `backend/app/services/actions/agent_router.py`)
- Action worker → Approval service: requests approval (evidence: `backend/app/worker/action_tasks.py`)
- Action worker → MCP service registry: invokes services (evidence: `backend/app/worker/action_tasks.py`)
- MCP service registry → MCP proxy routes: calls proxy
- MCP proxy routes → Connected services: forwards requests
- Action worker → SSE updates: publishes updates
- Background processing → SSE updates: publishes status
- FastAPI application → Redis access: streams events (evidence: `backend/app/main.py`)
- Database access → PostgreSQL: opens sessions (evidence: `backend/app/db/database.py`)
- Redis access → Redis: connects (evidence: `backend/app/db/redis.py`)
- File storage → S3-compatible storage: stores files (evidence: `backend/app/services/storage_service.py`)
- Database access → Domain and job models: provides ORM (evidence: `backend/app/models/models.py`)
- API routes → Notifications: sends notifications
