# mrunalg141/eco-biodiversity-rag architecture

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

- Interactive diagram: https://gitdiagram.com/mrunalg141/eco-biodiversity-rag
- Repository: https://github.com/mrunalg141/eco-biodiversity-rag

## Overview

ECO provides two user-facing workflows: PDF-grounded document Q&A and evidence-based environmental recommendations, including a biodiversity clarification exchange and a structured-input endpoint. The browser calls the FastAPI routes; the application delegates retrieval, recommendation generation, and persistence to separate modules. PDF ingestion and category-scoped environmental retrieval are distinct indexing/retrieval stages. The README documents the five-category knowledge base and source-cited structured results. Source excerpts do not show the deployed index build process end to end, so the knowledge-base builder is shown separately; the documented Groq and Chroma integrations are included.

Main entry points: [`app/main.py`](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/main.py) (FastAPI routes), [`app/llm.py`](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/llm.py) (Environmental advice), [`app/rag.py`](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/rag.py) (PDF retrieval), [`app/database.py`](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/database.py) (Chat database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat interface"]
  node_browser["Chat browser<br/>[script.js]"]
  node_chat_template["Chat page<br/>[index.html]"]
end

subgraph group_application["Application workflows"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_document_ingestion["PDF ingestion<br/>[main.py]"]
  node_chat_flow["Chat routing<br/>[main.py]"]
  node_document_answer["Document answers<br/>[llm.py]"]
  node_environmental_advice["Environmental advice<br/>[llm.py]"]
end

subgraph group_retrieval["Knowledge retrieval"]
  node_pdf_retrieval["PDF retrieval<br/>[rag.py]"]
  node_category_retrieval["Category retrieval<br/>[rag.py]"]
  node_knowledge_builder["Knowledge indexing<br/>[knowledgebase.py]"]
  node_pdfs["Knowledge PDFs"]
end

subgraph group_persistence["State and services"]
  node_sqlite[("Chat database<br/>[database.py]")]
  node_vector_store[("Chroma collections<br/>[rag.py]")]
end

node_user(("User"))
node_groq{{"Groq LLM API"}}

node_user -->|"uses"| node_browser
node_browser -->|"calls routes"| node_api
node_api -->|"renders page"| node_chat_template
node_api -->|"loads history"| node_sqlite
node_api -->|"handles upload"| node_document_ingestion
node_document_ingestion -->|"indexes PDF"| node_pdf_retrieval
node_document_ingestion -->|"saves document"| node_sqlite
node_browser -->|"sends chat"| node_api
node_api -->|"routes message"| node_chat_flow
node_chat_flow -->|"answers general query"| node_document_answer
node_document_answer -->|"retrieves context"| node_pdf_retrieval
node_chat_flow -->|"requests recommendation"| node_environmental_advice
node_api -->|"submits structured input"| node_environmental_advice
node_environmental_advice -->|"retrieves categories"| node_category_retrieval
node_document_answer -->|"generates answer"| node_groq
node_environmental_advice -->|"generates recommendation"| node_groq
node_chat_flow -->|"saves exchange"| node_sqlite
node_pdf_retrieval -->|"queries or indexes"| node_vector_store
node_category_retrieval -->|"queries categories"| node_vector_store
node_knowledge_builder -->|"reads PDFs"| node_pdfs
node_knowledge_builder -->|"indexes categories"| node_vector_store
node_api -->|"clears history"| node_sqlite
node_api -->|"clears uploaded index"| node_pdf_retrieval

click node_browser "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/static/script.js"
click node_chat_template "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/templates/index.html"
click node_api "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/main.py"
click node_document_ingestion "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/main.py"
click node_chat_flow "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/main.py"
click node_document_answer "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/llm.py"
click node_environmental_advice "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/llm.py"
click node_pdf_retrieval "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/rag.py"
click node_category_retrieval "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/rag.py"
click node_knowledge_builder "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/script/knowledgebase.py"
click node_pdfs "https://github.com/mrunalg141/eco-biodiversity-rag/tree/main/knowledge_base"
click node_sqlite "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/database.py"
click node_vector_store "https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/rag.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_browser,node_chat_template,node_user toneBlue
class node_api,node_document_ingestion,node_chat_flow,node_document_answer,node_environmental_advice toneAmber
class node_pdf_retrieval,node_category_retrieval,node_knowledge_builder,node_pdfs,node_groq toneMint
class node_sqlite,node_vector_store toneRose
```

## Components

### Chat interface

- [Chat browser](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/static/script.js): `static/script.js`
- [Chat page](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/templates/index.html): `templates/index.html`

### Application workflows

- [FastAPI routes](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/main.py): `app/main.py`
- [PDF ingestion](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/main.py): `app/main.py`
- [Chat routing](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/main.py): `app/main.py`
- [Document answers](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/llm.py): `app/llm.py`
- [Environmental advice](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/llm.py): `app/llm.py`

### Knowledge retrieval

- [PDF retrieval](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/rag.py): `app/rag.py`
- [Category retrieval](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/rag.py): `app/rag.py`
- [Knowledge indexing](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/script/knowledgebase.py): `script/knowledgebase.py`
- [Knowledge PDFs](https://github.com/mrunalg141/eco-biodiversity-rag/tree/main/knowledge_base): `knowledge_base`

### State and services

- [Chat database](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/database.py): `app/database.py`
- [Chroma collections](https://github.com/mrunalg141/eco-biodiversity-rag/blob/main/app/rag.py): `app/rag.py`

### Other components

- **User**
- **Groq LLM API**

## Connections

- User → Chat browser: uses
- Chat browser → FastAPI routes: calls routes
- FastAPI routes → Chat page: renders page
- FastAPI routes → Chat database: loads history
- FastAPI routes → PDF ingestion: handles upload
- PDF ingestion → PDF retrieval: indexes PDF
- PDF ingestion → Chat database: saves document
- Chat browser → FastAPI routes: sends chat
- FastAPI routes → Chat routing: routes message
- Chat routing → Document answers: answers general query
- Document answers → PDF retrieval: retrieves context
- Chat routing → Environmental advice: requests recommendation
- FastAPI routes → Environmental advice: submits structured input
- Environmental advice → Category retrieval: retrieves categories
- Document answers → Groq LLM API: generates answer
- Environmental advice → Groq LLM API: generates recommendation
- Chat routing → Chat database: saves exchange
- PDF retrieval → Chroma collections: queries or indexes
- Category retrieval → Chroma collections: queries categories
- Knowledge indexing → Knowledge PDFs: reads PDFs
- Knowledge indexing → Chroma collections: indexes categories
- FastAPI routes → Chat database: clears history
- FastAPI routes → PDF retrieval: clears uploaded index