# syedashhadibrar/actlens architecture

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

- Interactive diagram: https://gitdiagram.com/syedashhadibrar/actlens
- Repository: https://github.com/syedashhadibrar/actlens

## Overview

ActLens is a citation-grounded EU AI Act assistant with two user workflows: ask questions about the Act, or upload an internal policy for gap analysis. The chat path routes through an agent to hybrid retrieval, reranking, context preparation, and grounded answer generation; the response includes citations and retrieved passages for inspection. Separate ingestion builds and incrementally updates the searchable corpus. The README documents these capabilities; unsampled routes and subsystems are shown only at their existing enclosing paths, and uncertain internal wiring is omitted.

Main entry points: [`backend/app/pipeline/rag.py`](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/pipeline/rag.py) (RAG pipeline), [`backend/app/ingestion/indexer.py`](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/ingestion/indexer.py) (Corpus indexer), [`backend/app/retrieval/hybrid.py`](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/retrieval/hybrid.py) (Hybrid retrieval), [`frontend/src/App.tsx`](https://github.com/syedashhadibrar/actlens/blob/main/frontend/src/App.tsx) (Chat workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User workspace"]
  node_workspace["Chat workspace<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_evidence_ui["Evidence inspector"]
end

subgraph group_api["API and agents"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_chat_routes["Chat and upload routes"]
  node_ingest_route["Ingest endpoint<br/>[ingest.py]"]
  node_orchestrator["Agent router<br/>[orchestrator.py]"]
  node_rag_agent["Q&amp;A agent<br/>[rag_agent.py]"]
  node_gap_agent["Gap analysis<br/>[gap_agent.py]"]
end

subgraph group_retrieval["Retrieval and indexing"]
  node_pipeline["RAG pipeline<br/>[rag.py]"]
  node_hybrid["Hybrid retrieval<br/>[hybrid.py]"]
  node_vector[("Vector index<br/>[vector_store.py]")]
  node_bm25[("BM25 index<br/>[bm25_index.py]")]
  node_reranker["Cross-encoder ranker<br/>[reranker.py]"]
  node_indexer["Corpus indexer<br/>[indexer.py]"]
  node_ingestion["Document ingestion"]
end

subgraph group_generation["Answer generation"]
  node_context["Context preparation<br/>[context.py]"]
  node_answer["Grounded answer<br/>[answer.py]"]
  node_gap_runner["Agent runners"]
end

subgraph group_providers["Model providers"]
  node_provider_registry["Provider registry<br/>[registry.py]"]
  node_llm_provider["Chat model adapters"]
  node_embedding_provider["Embedding adapter"]
end

node_user(("User"))
node_llm_service{{"Configured LLM"}}

node_user -->|"asks or uploads"| node_workspace
node_workspace -->|"sends request"| node_api_client
node_api_client -->|"calls API"| node_fastapi
node_fastapi -->|"dispatches routes"| node_chat_routes
node_chat_routes -->|"dispatches chat"| node_orchestrator
node_orchestrator -->|"selects Q&amp;A"| node_rag_agent
node_orchestrator -->|"selects gap review"| node_gap_agent
node_rag_agent -->|"runs agent"| node_gap_runner
node_gap_agent -->|"runs agent"| node_gap_runner
node_gap_runner -->|"retrieves evidence"| node_pipeline
node_pipeline -->|"queries"| node_hybrid
node_hybrid -->|"searches vectors"| node_vector
node_hybrid -->|"searches terms"| node_bm25
node_pipeline -->|"reranks results"| node_reranker
node_pipeline -->|"prepares context"| node_context
node_pipeline -->|"generates response"| node_answer
node_gap_runner -->|"extracts citations"| node_answer
node_answer -->|"requests model"| node_provider_registry
node_provider_registry -->|"selects adapter"| node_llm_provider
node_llm_provider -.->|"calls model"| node_llm_service
node_hybrid -->|"embeds query"| node_embedding_provider
node_embedding_provider -->|"selected by"| node_provider_registry
node_ingest_route -->|"starts ingestion"| node_indexer
node_fastapi -->|"loads indexes"| node_indexer
node_indexer -->|"loads and chunks"| node_ingestion
node_indexer -->|"updates vectors"| node_vector
node_indexer -->|"updates terms"| node_bm25
node_chat_routes -->|"returns answer and evidence"| node_workspace
node_workspace -->|"shows passages"| node_evidence_ui

click node_workspace "https://github.com/syedashhadibrar/actlens/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/syedashhadibrar/actlens/blob/main/frontend/src/api/client.ts"
click node_evidence_ui "https://github.com/syedashhadibrar/actlens/blob/main/frontend/src/components/inspector/EvidenceInspector.tsx"
click node_fastapi "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/main.py"
click node_chat_routes "https://github.com/syedashhadibrar/actlens/tree/main/backend/app/api/routes"
click node_ingest_route "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/api/routes/ingest.py"
click node_orchestrator "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/agents/orchestrator.py"
click node_rag_agent "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/agents/rag_agent.py"
click node_gap_agent "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/agents/gap_agent.py"
click node_pipeline "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/pipeline/rag.py"
click node_hybrid "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/retrieval/hybrid.py"
click node_vector "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/retrieval/vector_store.py"
click node_bm25 "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/retrieval/bm25_index.py"
click node_reranker "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/ranking/reranker.py"
click node_indexer "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/ingestion/indexer.py"
click node_ingestion "https://github.com/syedashhadibrar/actlens/tree/main/backend/app/ingestion"
click node_context "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/processing/context.py"
click node_answer "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/generation/answer.py"
click node_gap_runner "https://github.com/syedashhadibrar/actlens/tree/main/backend/app/agents/langchain"
click node_provider_registry "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/core/providers/registry.py"
click node_llm_provider "https://github.com/syedashhadibrar/actlens/tree/main/backend/app/core/providers"
click node_embedding_provider "https://github.com/syedashhadibrar/actlens/blob/main/backend/app/core/providers/hf_embedding_provider.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_workspace,node_api_client,node_evidence_ui,node_user toneBlue
class node_fastapi,node_chat_routes,node_ingest_route,node_orchestrator,node_rag_agent,node_gap_agent toneAmber
class node_pipeline,node_hybrid,node_vector,node_bm25,node_reranker,node_indexer,node_ingestion toneMint
class node_context,node_answer,node_gap_runner toneRose
class node_provider_registry,node_llm_provider,node_embedding_provider,node_llm_service toneIndigo
```

## Components

### User workspace

- [Chat workspace](https://github.com/syedashhadibrar/actlens/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/syedashhadibrar/actlens/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Evidence inspector](https://github.com/syedashhadibrar/actlens/blob/main/frontend/src/components/inspector/EvidenceInspector.tsx): `frontend/src/components/inspector/EvidenceInspector.tsx`

### API and agents

- [FastAPI app](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat and upload routes](https://github.com/syedashhadibrar/actlens/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Ingest endpoint](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/api/routes/ingest.py): `backend/app/api/routes/ingest.py`
- [Agent router](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Q&A agent](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/agents/rag_agent.py): `backend/app/agents/rag_agent.py`
- [Gap analysis](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/agents/gap_agent.py): `backend/app/agents/gap_agent.py`

### Retrieval and indexing

- [RAG pipeline](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/pipeline/rag.py): `backend/app/pipeline/rag.py`
- [Hybrid retrieval](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/retrieval/hybrid.py): `backend/app/retrieval/hybrid.py`
- [Vector index](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/retrieval/vector_store.py): `backend/app/retrieval/vector_store.py`
- [BM25 index](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/retrieval/bm25_index.py): `backend/app/retrieval/bm25_index.py`
- [Cross-encoder ranker](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/ranking/reranker.py): `backend/app/ranking/reranker.py`
- [Corpus indexer](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/ingestion/indexer.py): `backend/app/ingestion/indexer.py`
- [Document ingestion](https://github.com/syedashhadibrar/actlens/tree/main/backend/app/ingestion): `backend/app/ingestion`

### Answer generation

- [Context preparation](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/processing/context.py): `backend/app/processing/context.py`
- [Grounded answer](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/generation/answer.py): `backend/app/generation/answer.py`
- [Agent runners](https://github.com/syedashhadibrar/actlens/tree/main/backend/app/agents/langchain): `backend/app/agents/langchain`

### Model providers

- [Provider registry](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/core/providers/registry.py): `backend/app/core/providers/registry.py`
- [Chat model adapters](https://github.com/syedashhadibrar/actlens/tree/main/backend/app/core/providers): `backend/app/core/providers`
- [Embedding adapter](https://github.com/syedashhadibrar/actlens/blob/main/backend/app/core/providers/hf_embedding_provider.py): `backend/app/core/providers/hf_embedding_provider.py`

### Other components

- **User**
- **Configured LLM**

## Connections

- User → Chat workspace: asks or uploads
- Chat workspace → API client: sends request
- API client → FastAPI app: calls API
- FastAPI app → Chat and upload routes: dispatches routes
- Chat and upload routes → Agent router: dispatches chat
- Agent router → Q&A agent: selects Q&A
- Agent router → Gap analysis: selects gap review
- Q&A agent → Agent runners: runs agent
- Gap analysis → Agent runners: runs agent
- Agent runners → RAG pipeline: retrieves evidence
- RAG pipeline → Hybrid retrieval: queries
- Hybrid retrieval → Vector index: searches vectors
- Hybrid retrieval → BM25 index: searches terms
- RAG pipeline → Cross-encoder ranker: reranks results
- RAG pipeline → Context preparation: prepares context
- RAG pipeline → Grounded answer: generates response
- Agent runners → Grounded answer: extracts citations
- Grounded answer → Provider registry: requests model
- Provider registry → Chat model adapters: selects adapter
- Chat model adapters → Configured LLM: calls model
- Hybrid retrieval → Embedding adapter: embeds query
- Embedding adapter → Provider registry: selected by
- Ingest endpoint → Corpus indexer: starts ingestion
- FastAPI app → Corpus indexer: loads indexes
- Corpus indexer → Document ingestion: loads and chunks
- Corpus indexer → Vector index: updates vectors
- Corpus indexer → BM25 index: updates terms
- Chat and upload routes → Chat workspace: returns answer and evidence
- Chat workspace → Evidence inspector: shows passages