# ai-builders-iran/chemlib-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ai-builders-iran/chemlib-ai
- Repository: https://github.com/ai-builders-iran/chemlib-ai

## Overview

ChemLib AI combines a chemistry-library RAG product with a separate structured-extraction demo. The primary workflow is admin ingestion into a persistent vector index, followed by user chat or source comparison that retrieves passages, applies a grounding threshold, and returns cited answers. The Streamlit UI and REST API expose these capabilities; extraction reuses document loading and processing before producing validated schemas. Relationships for unsampled subsystems are included only where documented in the README or named by the source index; optional OCR and provider fallback are marked dashed.

Main entry points: [`app/streamlit_app/docai_ui/services.py`](https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/docai_ui/services.py) (UI backend services), [`rag/ingestion.py`](https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/ingestion.py) (RAG ingestion), [`rag/rag_service.py`](https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/rag_service.py) (RAG service), [`src/pipeline/pipeline.py`](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/pipeline/pipeline.py) (Extraction orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_chat_ui["Chat view<br/>[chat_view.py]"]
  node_admin_ui["Admin panel<br/>[admin_view.py]"]
  node_api["REST API<br/>[api_app.py]"]
  node_ui_services["UI backend services<br/>[services.py]"]
  node_extraction_demo["Extraction demo<br/>[extraction_demo.py]"]
end

subgraph group_ingestion["Document Ingestion"]
  node_ingestion_pipeline["RAG ingestion<br/>[ingestion.py]"]
  node_loader["Document loading<br/>[document_loader.py]"]
  node_ocr["Scanned PDF OCR<br/>[ocr.py]"]
  node_processing["Cleaning and chunking<br/>[pipeline.py]"]
  node_chunker["Recursive chunker<br/>[recursive.py]"]
end

subgraph group_rag["Grounded RAG"]
  node_rag_service["RAG service<br/>[rag_service.py]"]
  node_rag_prompts["RAG and compare prompts<br/>[prompts.py]"]
end

subgraph group_extraction["Structured Extraction"]
  node_extraction_pipeline["Extraction orchestration<br/>[pipeline.py]"]
  node_extractor["Document extractor<br/>[extractor.py]"]
  node_schemas["Validated schemas<br/>[common.py]"]
end

subgraph group_shared["Shared Services"]
  node_embedder["BGE-M3 embeddings<br/>[embedding.py]"]
  node_vector_store[("Chroma vector store<br/>[vector_store.py]")]
  node_session_store[("Private session store<br/>[session_store.py]")]
  node_gemini["Gemini provider<br/>[gemini_provider.py]"]
  node_openrouter["OpenRouter provider"]
end

node_students(("Students"))
node_admins(("Library admins"))

node_students -->|"use chat"| node_streamlit
node_admins -->|"manage library"| node_streamlit
node_streamlit -->|"renders"| node_chat_ui
node_streamlit -->|"renders"| node_admin_ui
node_chat_ui -->|"requests services"| node_ui_services
node_admin_ui -->|"manages documents"| node_ui_services
node_api -->|"ingests files"| node_ingestion_pipeline
node_api -->|"serves chat and compare"| node_rag_service
node_api -->|"runs extraction"| node_extraction_pipeline
node_ui_services -->|"starts ingestion"| node_ingestion_pipeline
node_ui_services -->|"creates service"| node_rag_service
node_ui_services -->|"creates store"| node_vector_store
node_ui_services -->|"holds private documents"| node_session_store
node_ingestion_pipeline -->|"loads documents"| node_loader
node_ingestion_pipeline -->|"cleans documents"| node_processing
node_ingestion_pipeline -->|"chunks documents"| node_chunker
node_ingestion_pipeline -->|"indexes chunks"| node_vector_store
node_loader -.->|"uses for scanned PDFs"| node_ocr
node_vector_store -->|"embeds and searches"| node_embedder
node_rag_service -->|"retrieves passages"| node_vector_store
node_rag_service -->|"builds prompts"| node_rag_prompts
node_rag_service -->|"requests structured output"| node_gemini
node_rag_service -.->|"falls back on failure"| node_openrouter
node_extraction_demo -.->|"submits documents"| node_extraction_pipeline
node_extraction_pipeline -->|"loads documents"| node_loader
node_extraction_pipeline -->|"processes text"| node_processing
node_extraction_pipeline -->|"chunks text"| node_chunker
node_extraction_pipeline -->|"extracts fields"| node_extractor
node_extractor -->|"validates output"| node_schemas
node_extractor -.->|"tries providers"| node_gemini
node_extractor -.->|"fallback provider"| node_openrouter

click node_streamlit "https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/app.py"
click node_chat_ui "https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/docai_ui/chat_view.py"
click node_admin_ui "https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/docai_ui/admin_view.py"
click node_api "https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/api/api_app.py"
click node_ui_services "https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/docai_ui/services.py"
click node_ingestion_pipeline "https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/ingestion.py"
click node_loader "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/loaders/document_loader.py"
click node_ocr "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/loaders/ocr.py"
click node_processing "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/processing/pipeline.py"
click node_chunker "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/processing/chunking/recursive.py"
click node_embedder "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/embedding/embedding.py"
click node_vector_store "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/retrieval/vector_store.py"
click node_session_store "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/retrieval/session_store.py"
click node_rag_service "https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/rag_service.py"
click node_rag_prompts "https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/prompts.py"
click node_gemini "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/extraction/providers/gemini_provider.py"
click node_openrouter "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/extraction/providers/openrouter_provider.py"
click node_extraction_demo "https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/extraction_demo.py"
click node_extraction_pipeline "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/pipeline/pipeline.py"
click node_extractor "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/extraction/extractor.py"
click node_schemas "https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/schemas/common.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_streamlit,node_chat_ui,node_admin_ui,node_api,node_ui_services,node_extraction_demo toneBlue
class node_ingestion_pipeline,node_loader,node_ocr,node_processing,node_chunker toneAmber
class node_rag_service,node_rag_prompts toneMint
class node_extraction_pipeline,node_extractor,node_schemas toneRose
class node_embedder,node_vector_store,node_session_store,node_gemini,node_openrouter,node_students,node_admins toneIndigo
```

## Components

### User Interfaces

- [Streamlit app](https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/app.py): `app/streamlit_app/app.py`
- [Chat view](https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/docai_ui/chat_view.py): `app/streamlit_app/docai_ui/chat_view.py`
- [Admin panel](https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/docai_ui/admin_view.py): `app/streamlit_app/docai_ui/admin_view.py`
- [REST API](https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/api/api_app.py): `app/api/api_app.py`
- [UI backend services](https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/docai_ui/services.py): `app/streamlit_app/docai_ui/services.py`
- [Extraction demo](https://github.com/ai-builders-iran/chemlib-ai/blob/main/app/streamlit_app/extraction_demo.py): `app/streamlit_app/extraction_demo.py`

### Document Ingestion

- [RAG ingestion](https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/ingestion.py): `rag/ingestion.py`
- [Document loading](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/loaders/document_loader.py): `src/loaders/document_loader.py`
- [Scanned PDF OCR](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/loaders/ocr.py): `src/loaders/ocr.py`
- [Cleaning and chunking](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/processing/pipeline.py): `src/processing/pipeline.py`
- [Recursive chunker](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/processing/chunking/recursive.py): `src/processing/chunking/recursive.py`

### Grounded RAG

- [RAG service](https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/rag_service.py): `rag/rag_service.py`
- [RAG and compare prompts](https://github.com/ai-builders-iran/chemlib-ai/blob/main/rag/prompts.py): `rag/prompts.py`

### Structured Extraction

- [Extraction orchestration](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/pipeline/pipeline.py): `src/pipeline/pipeline.py`
- [Document extractor](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/extraction/extractor.py): `src/extraction/extractor.py`
- [Validated schemas](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/schemas/common.py): `src/schemas/common.py`

### Shared Services

- [BGE-M3 embeddings](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/embedding/embedding.py): `src/embedding/embedding.py`
- [Chroma vector store](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/retrieval/vector_store.py): `src/retrieval/vector_store.py`
- [Private session store](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/retrieval/session_store.py): `src/retrieval/session_store.py`
- [Gemini provider](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/extraction/providers/gemini_provider.py): `src/extraction/providers/gemini_provider.py`
- [OpenRouter provider](https://github.com/ai-builders-iran/chemlib-ai/blob/main/src/extraction/providers/openrouter_provider.py): `src/extraction/providers/openrouter_provider.py`

### Other components

- **Students**
- **Library admins**

## Connections

- Students → Streamlit app: use chat (evidence: `README.md`)
- Library admins → Streamlit app: manage library (evidence: `README.md`)
- Streamlit app → Chat view: renders (evidence: `app/streamlit_app/app.py`)
- Streamlit app → Admin panel: renders (evidence: `app/streamlit_app/app.py`)
- Chat view → UI backend services: requests services (evidence: `app/streamlit_app/docai_ui/chat_view.py`)
- Admin panel → UI backend services: manages documents (evidence: `app/streamlit_app/docai_ui/admin_view.py`)
- REST API → RAG ingestion: ingests files (evidence: `app/api/api_app.py`)
- REST API → RAG service: serves chat and compare (evidence: `app/api/api_app.py`)
- REST API → Extraction orchestration: runs extraction (evidence: `README.md`)
- UI backend services → RAG ingestion: starts ingestion (evidence: `app/streamlit_app/docai_ui/services.py`)
- UI backend services → RAG service: creates service (evidence: `app/streamlit_app/docai_ui/services.py`)
- UI backend services → Chroma vector store: creates store (evidence: `app/streamlit_app/docai_ui/services.py`)
- UI backend services → Private session store: holds private documents (evidence: `app/streamlit_app/docai_ui/services.py`)
- RAG ingestion → Document loading: loads documents (evidence: `rag/ingestion.py`)
- RAG ingestion → Cleaning and chunking: cleans documents (evidence: `rag/ingestion.py`)
- RAG ingestion → Recursive chunker: chunks documents (evidence: `rag/ingestion.py`)
- RAG ingestion → Chroma vector store: indexes chunks (evidence: `rag/ingestion.py`)
- Document loading → Scanned PDF OCR: uses for scanned PDFs (evidence: `README.md`)
- Chroma vector store → BGE-M3 embeddings: embeds and searches (evidence: `src/retrieval/vector_store.py`)
- RAG service → Chroma vector store: retrieves passages (evidence: `rag/rag_service.py`)
- RAG service → RAG and compare prompts: builds prompts (evidence: `rag/rag_service.py`)
- RAG service → Gemini provider: requests structured output (evidence: `rag/rag_service.py`)
- RAG service → OpenRouter provider: falls back on failure (evidence: `rag/rag_service.py`)
- Extraction demo → Extraction orchestration: submits documents (evidence: `README.md`)
- Extraction orchestration → Document loading: loads documents (evidence: `src/pipeline/pipeline.py`)
- Extraction orchestration → Cleaning and chunking: processes text (evidence: `src/pipeline/pipeline.py`)
- Extraction orchestration → Recursive chunker: chunks text (evidence: `src/pipeline/pipeline.py`)
- Extraction orchestration → Document extractor: extracts fields (evidence: `src/pipeline/pipeline.py`)
- Document extractor → Validated schemas: validates output (evidence: `src/extraction/extractor.py`)
- Document extractor → Gemini provider: tries providers (evidence: `README.md`)
- Document extractor → OpenRouter provider: fallback provider (evidence: `README.md`)
