# abdulkaiz-007/predators architecture

> Architecture diagram of the GitHub repository abdulkaiz-007/predators, 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/abdulkaiz-007/predators
- Repository: https://github.com/abdulkaiz-007/predators

## Overview

This is an enterprise RAG web application for ingesting documents and web pages, querying them with grounded answers and citations, and inspecting retrieval quality and audit history. The main workflow runs from the chat UI through the Express API into retrieval and answer generation, returning evidence-backed results. Separate product branches manage document ingestion, corpus exploration, engine settings, and benchmark evaluation. The excerpts show in-memory corpus state; some UI and server route details are partial, so uncertain internal wiring is omitted.

Main entry points: [`server.ts`](https://github.com/abdulkaiz-007/predators/blob/main/server.ts) (HTTP API), [`src/App.tsx`](https://github.com/abdulkaiz-007/predators/blob/main/src/App.tsx) (App Shell), [`server/ragEngine.ts`](https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts) (Grounded Answering), [`src/components/CitationsTab.tsx`](https://github.com/abdulkaiz-007/predators/blob/main/src/components/CitationsTab.tsx) (Citation Explorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interface"]
  node_app["App Shell<br/>[App.tsx]"]
  node_chat["RAG Chat<br/>[ChatTab.tsx]"]
  node_documents_ui["Document Manager<br/>[DocumentsTab.tsx]"]
  node_citations_ui["Citation Explorer<br/>[CitationsTab.tsx]"]
  node_evaluation_ui["Evaluation &amp; Audit<br/>[EvaluationTab.tsx]"]
  node_settings_ui["Engine Settings<br/>[SettingsModal.tsx]"]
  node_document_modal["Chunk Viewer<br/>[DocumentModal.tsx]"]
end

subgraph group_api["Application API"]
  node_server["HTTP API<br/>[server.ts]"]
end

subgraph group_rag["RAG Engine"]
  node_ingestion["Document Ingestion<br/>[ragEngine.ts]"]
  node_retrieval["Hybrid Retrieval<br/>[ragEngine.ts]"]
  node_answer["Grounded Answering<br/>[ragEngine.ts]"]
end

subgraph group_ops["Corpus &amp; Evaluation"]
  node_corpus[("In-Memory Corpus<br/>[ragEngine.ts]")]
  node_configuration["Engine Configuration<br/>[ragEngine.ts]"]
  node_benchmark["Benchmark Runner<br/>[ragEngine.ts]"]
end

node_user(("User"))
node_gemini{{"Gemini API"}}
node_tinyfish{{"TinyFish Agent"}}
node_source_web(("Web Sources"))

node_user -->|"uses"| node_app
node_app -->|"shows"| node_chat
node_app -->|"shows"| node_documents_ui
node_app -->|"shows"| node_citations_ui
node_app -->|"shows"| node_evaluation_ui
node_app -->|"opens"| node_settings_ui
node_app -->|"opens"| node_document_modal
node_chat -->|"posts query"| node_server
node_server -->|"dispatches query"| node_answer
node_answer -->|"requests passages"| node_retrieval
node_retrieval -->|"reads chunks"| node_corpus
node_retrieval -->|"returns evidence"| node_answer
node_answer -.->|"generates answer"| node_gemini
node_answer -->|"writes audit"| node_corpus
node_answer -->|"returns response"| node_server
node_server -->|"returns answer"| node_chat
node_documents_ui -->|"uploads or crawls"| node_server
node_server -->|"dispatches ingest"| node_ingestion
node_ingestion -.->|"extracts page"| node_tinyfish
node_ingestion -->|"fetches page"| node_source_web
node_ingestion -->|"stores documents"| node_corpus
node_server -->|"lists or deletes"| node_corpus
node_citations_ui -->|"loads chunks"| node_server
node_citations_ui -->|"tests retrieval"| node_server
node_server -->|"dispatches retrieval"| node_retrieval
node_server -->|"reads or updates"| node_configuration
node_settings_ui -->|"saves settings"| node_server
node_server -->|"runs benchmark"| node_benchmark
node_benchmark -->|"queries cases"| node_answer
node_evaluation_ui -->|"requests evaluation"| node_server
node_evaluation_ui -->|"loads audit"| node_server
node_server -->|"reads audit"| node_corpus

click node_app "https://github.com/abdulkaiz-007/predators/blob/main/src/App.tsx"
click node_chat "https://github.com/abdulkaiz-007/predators/blob/main/src/components/ChatTab.tsx"
click node_documents_ui "https://github.com/abdulkaiz-007/predators/blob/main/src/components/DocumentsTab.tsx"
click node_citations_ui "https://github.com/abdulkaiz-007/predators/blob/main/src/components/CitationsTab.tsx"
click node_evaluation_ui "https://github.com/abdulkaiz-007/predators/blob/main/src/components/EvaluationTab.tsx"
click node_settings_ui "https://github.com/abdulkaiz-007/predators/blob/main/src/components/SettingsModal.tsx"
click node_document_modal "https://github.com/abdulkaiz-007/predators/blob/main/src/components/DocumentModal.tsx"
click node_server "https://github.com/abdulkaiz-007/predators/blob/main/server.ts"
click node_ingestion "https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts"
click node_corpus "https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts"
click node_retrieval "https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts"
click node_answer "https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts"
click node_configuration "https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts"
click node_benchmark "https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts"

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_app,node_chat,node_documents_ui,node_citations_ui,node_evaluation_ui,node_settings_ui,node_document_modal,node_user toneBlue
class node_server toneAmber
class node_ingestion,node_retrieval,node_answer,node_gemini toneMint
class node_corpus,node_configuration,node_benchmark toneRose
class node_tinyfish,node_source_web toneIndigo
```

## Components

### User Interface

- [App Shell](https://github.com/abdulkaiz-007/predators/blob/main/src/App.tsx): `src/App.tsx`
- [RAG Chat](https://github.com/abdulkaiz-007/predators/blob/main/src/components/ChatTab.tsx): `src/components/ChatTab.tsx`
- [Document Manager](https://github.com/abdulkaiz-007/predators/blob/main/src/components/DocumentsTab.tsx): `src/components/DocumentsTab.tsx`
- [Citation Explorer](https://github.com/abdulkaiz-007/predators/blob/main/src/components/CitationsTab.tsx): `src/components/CitationsTab.tsx`
- [Evaluation & Audit](https://github.com/abdulkaiz-007/predators/blob/main/src/components/EvaluationTab.tsx): `src/components/EvaluationTab.tsx`
- [Engine Settings](https://github.com/abdulkaiz-007/predators/blob/main/src/components/SettingsModal.tsx): `src/components/SettingsModal.tsx`
- [Chunk Viewer](https://github.com/abdulkaiz-007/predators/blob/main/src/components/DocumentModal.tsx): `src/components/DocumentModal.tsx`

### Application API

- [HTTP API](https://github.com/abdulkaiz-007/predators/blob/main/server.ts): `server.ts`

### RAG Engine

- [Document Ingestion](https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts): `server/ragEngine.ts`
- [Hybrid Retrieval](https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts): `server/ragEngine.ts`
- [Grounded Answering](https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts): `server/ragEngine.ts`

### Corpus & Evaluation

- [In-Memory Corpus](https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts): `server/ragEngine.ts`
- [Engine Configuration](https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts): `server/ragEngine.ts`
- [Benchmark Runner](https://github.com/abdulkaiz-007/predators/blob/main/server/ragEngine.ts): `server/ragEngine.ts`

### Other components

- **User**
- **Gemini API**
- **TinyFish Agent**
- **Web Sources**

## Connections

- User → App Shell: uses
- App Shell → RAG Chat: shows
- App Shell → Document Manager: shows
- App Shell → Citation Explorer: shows
- App Shell → Evaluation & Audit: shows
- App Shell → Engine Settings: opens
- App Shell → Chunk Viewer: opens
- RAG Chat → HTTP API: posts query
- HTTP API → Grounded Answering: dispatches query
- Grounded Answering → Hybrid Retrieval: requests passages
- Hybrid Retrieval → In-Memory Corpus: reads chunks
- Hybrid Retrieval → Grounded Answering: returns evidence
- Grounded Answering → Gemini API: generates answer
- Grounded Answering → In-Memory Corpus: writes audit
- Grounded Answering → HTTP API: returns response
- HTTP API → RAG Chat: returns answer
- Document Manager → HTTP API: uploads or crawls
- HTTP API → Document Ingestion: dispatches ingest
- Document Ingestion → TinyFish Agent: extracts page
- Document Ingestion → Web Sources: fetches page
- Document Ingestion → In-Memory Corpus: stores documents
- HTTP API → In-Memory Corpus: lists or deletes
- Citation Explorer → HTTP API: loads chunks
- Citation Explorer → HTTP API: tests retrieval
- HTTP API → Hybrid Retrieval: dispatches retrieval
- HTTP API → Engine Configuration: reads or updates
- Engine Settings → HTTP API: saves settings
- HTTP API → Benchmark Runner: runs benchmark
- Benchmark Runner → Grounded Answering: queries cases
- Evaluation & Audit → HTTP API: requests evaluation
- Evaluation & Audit → HTTP API: loads audit
- HTTP API → In-Memory Corpus: reads audit