# climate-resilient-communities/climate-multilingual-chatbot architecture

> Architecture diagram of the GitHub repository climate-resilient-communities/climate-multilingual-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/climate-resilient-communities/climate-multilingual-chatbot
- Repository: https://github.com/climate-resilient-communities/climate-multilingual-chatbot

## Overview

##### Project Type and Purpose
- This is a full-stack, micro-service–style RAG chatbot application with both a Streamlit front end and a CLI mode.
- Its purpose is to let users ask climate-change questions in multiple languages, retrieve documents via Pinecone, rerank them with Cohere, generate responses with Amazon Bedrock Nova, enforce guardrails (hallucination checks, input validation), cache results in Redis, and display results with source citations.

##### File Structure
- Top-level “src/webui” → Streamlit app.
- “src/main_nova.py” → CLI entrypoint.
- “src/models” → RAG pipeline components (retrieval, rerank, generation, guardrails, caching).
- “src/data/config” → configuration modules (Azure, general).
- “src/utils” → cross-cutting utilities (env loading, logging, metrics, model downloads, system init).
- CI/CD workflows, Dockerfile, docker-compose.yml, Azure deployment scripts for containerized and cloud setups.
- Tests organized by unit, integration, system.

##### Extract Architectural Insights from the README
- Hybrid search uses Pinecone vector store and BGE-M3 embeddings.
- Reranking via Cohere.
- Generation via Amazon Bedrock Nova.
- Local fallback to HF ClimateBERT model.
- Redis caching layer.
- Asynchronous, pipeline-based processing.
- Streamlit front end with health checks, chat history, citations.
- Azure-ready with model-download script and env-based config.

a. User Interface
- Streamlit Web UI (src/webui/app_nova.py)
- Health Check endpoint (src/webui/health_check.py)
- CLI (src/main_nova.py)
b. Backend Pipeline
- Input Validation & Moderation (input_guardrail.py)
- Retrieval Module (retrieval.py) → Pinecone Vector Store
- Rerank Module (rerank.py) → Cohere API
- Generation Module (gen_response_nova.py) → Amazon Bedrock Nova
- Hallucination Guard (hallucination_guard.py)
- Caching Layer (redis_cache.py) → Redis
- System Messages & Prompts (system_messages.py)
c. Configuration & Utilities
- Env Loader & Config (env_loader.py, config.py, azure_config.py)
- Download Models (download_models.py) → local HF fallback
- Logging & Metrics (logging_config.py, analytics.py, metrics.py)
- System Init & Monitoring (system_init.py, system_monitor.py)
d. External Services & Data Stores
- Amazon Bedrock Nova (AWS)
- Pinecone Vector Store
- Cohere Reranking API
- Redis Server (optional)
- Optional Hugging Face local models

##### Relationships & Data Flow
1. User → (UI or CLI) → Input Validation
2. If validated → check Redis cache
- Cache hit → return cached response
- Cache miss → proceed
3. Retrieval → Pinecone → get top-k docs
4. Rerank → Cohere → reorder docs
5. Generation → Amazon Bedrock Nova (or local ClimateBERT fallback)
6. Hallucination Guard → enforce quality
7. Save response + citations to Redis
8. Return response to User + log metrics

##### Architectural Patterns & Design Principles
- Pipeline/Chain-of-Responsibility for RAG flow
- Layered separation: Presentation (UI/CLI), Application (validation, orchestration), Data (cache, vector store), External (LLM, reranker)
- Modular guardrails for safety
- Asynchronous I/O for performance
- Configuration via environment and config modules for portability (Docker, Azure)

##### Essential Elements to Capture
- All external integrations: Pinecone, Cohere, Amazon Bedrock, Redis, Hugging Face
- Configuration layers for AWS vs. Azure deployment
- Pipeline stages and guardrails
- Interfaces: Streamlit front end, CLI entrypoint

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "User Interfaces"
        direction TB
        UI["Streamlit Web UI"]:::frontend
        Health["Health Check Endpoint"]:::frontend
        CLI["CLI Entry Point"]:::frontend
    end

    %% Pipeline Layer
    subgraph "RAG Pipeline" 
        direction TB
        Guardrail["Input Validation & Moderation"]:::pipeline
        Cache["Caching Layer (Redis)"]:::pipeline
        Retrieve["Retrieval Module"]:::pipeline
        Rerank["Rerank Module"]:::pipeline
        Generate["Generation Module"]:::pipeline
        Hallucination["Hallucination Guard"]:::pipeline
        Messages["System Messages & Prompts"]:::pipeline
    end

    %% Utilities & Config
    subgraph "Config & Utilities"
        direction TB
        Env["Environment Loader"]:::config
        ConfigGen["General Configuration"]:::config
        ConfigAz["Azure Configuration"]:::config
        Download["Download Local Models"]:::config
        LogConf["Logging Configuration"]:::config
        Analytics["Analytics (Metrics)"]:::config
        Metrics["Metrics Utilities"]:::config
        Init["System Initialization"]:::config
        Monitor["System Monitoring"]:::config
    end

    %% External Services & Data Stores
    subgraph "External Services & Data Stores"
        direction TB
        Pinecone[(Pinecone Vector Store)]:::datastore
        Cohere[(Cohere Reranking API)]:::external
        Nova[(Amazon Bedrock Nova)]:::external
        Redis[(Redis Server)]:::datastore
        HF[(Hugging Face Local Models)]:::external
    end

    %% User to Pipeline
    UI -->|"1. user query"| Guardrail
    CLI -->|"1. user query"| Guardrail

    %% Cache Decision
    Guardrail -->|"2. check cache"| Cache
    Cache -->|hit| UI
    Cache -->|miss| Retrieve

    %% RAG Flow
    Retrieve -->|"3. vector search"| Pinecone
    Pinecone --> Retrieve
    Retrieve -->|"4. docs"| Rerank
    Rerank -->|"5. reranked docs"| Cohere
    Cohere --> Rerank
    Rerank --> Generate
    Generate -->|"6. generate"| Nova
    Nova --> Generate
    Generate -->|"6b. fallback"| HF
    HF --> Generate
    Generate --> Hallucination
    Hallucination -->|"7. checked response"| Cache
    Cache -->|"8. response"| UI
    Cache --> UI
    Hallucination --> UI

    %% System Messages & Prompts used throughout pipeline
    Messages --> Guardrail
    Messages --> Retrieve
    Messages --> Rerank
    Messages --> Generate
    Messages --> Hallucination

    %% Utilities & Config usage
    Env --> Guardrail
    Env --> Retrieve
    Env --> Rerank
    Env --> Generate
    Env --> Hallucination
    ConfigGen --> Env
    ConfigAz --> Env
    Download --> Generate
    LogConf --> Guardrail
    LogConf --> Retrieve
    LogConf --> Rerank
    LogConf --> Generate
    LogConf --> Hallucination
    Analytics --> Guardrail
    Analytics --> Retrieve
    Analytics --> Rerank
    Analytics --> Generate
    Analytics --> Hallucination
    Metrics --> Analytics
    Init --> Guardrail
    Init --> Retrieve
    Init --> Rerank
    Init --> Generate
    Init --> Hallucination
    Monitor --> Guardrail
    Monitor --> Retrieve
    Monitor --> Rerank
    Monitor --> Generate
    Monitor --> Hallucination

    %% Click Events
    click UI "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/webui/app_nova.py"
    click Health "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/webui/health_check.py"
    click CLI "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/main_nova.py"
    click Guardrail "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/models/input_guardrail.py"
    click Retrieve "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/models/retrieval.py"
    click Rerank "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/models/rerank.py"
    click Generate "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/models/gen_response_nova.py"
    click Hallucination "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/models/hallucination_guard.py"
    click Cache "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/models/redis_cache.py"
    click Messages "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/models/system_messages.py"
    click Env "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/utils/env_loader.py"
    click ConfigGen "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/data/config/config.py"
    click ConfigAz "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/data/config/azure_config.py"
    click Download "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/utils/download_models.py"
    click LogConf "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/utils/logging_config.py"
    click Analytics "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/utils/analytics.py"
    click Metrics "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/utils/metrics.py"
    click Init "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/utils/system_init.py"
    click Monitor "https://github.com/climate-resilient-communities/climate-multilingual-chatbot/blob/main/src/utils/system_monitor.py"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef pipeline fill:#d4edda,stroke:#155724,color:#155724,stroke-width:2px,stroke-dasharray: 5 5;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#343a40,stroke-dasharray: 2 2;
    classDef datastore fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-dasharray: 4 2;
```
