# sunbird-aiassistant/sakhi-api-service architecture

> Architecture diagram of the GitHub repository sunbird-aiassistant/sakhi-api-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sunbird-aiassistant/sakhi-api-service
- Repository: https://github.com/sunbird-aiassistant/sakhi-api-service

## Overview

##### Project Type & Purpose
- This is a Python-based backend API service (FastAPI) exposing two endpoints: POST /v1/query and POST /v1/chat.
- It ingests user text/audio queries, invokes LLMs (Azure/OpenAI/Ollama), fetches context from a vector store (Marqo), performs translation and TTS/STT, caches chats in Redis, stores audio in cloud storage, and logs telemetry.

##### High-Level File Structure Breakdown
- main.py + uvicorn entrypoint → FastAPI app & routers
- env_manager.py, config.ini, .env → configuration & environment
- llm/ → adapters for various LLM providers (azure_openai.py, openai.py, ollama.py)
- vectorstores/ → Marqo integration
- translation/ → text↔text and speech↔text modules (Google, Bhashini, Dhruva, TTS/STT)
- storage/ → cloud object storage adapters (AWS, GCP, OCI) for audio files
- redis_util.py → Redis caching for /v1/chat
- telemetry_logger.py, telemetry_middleware.py → telemetry event emission
- index_documents.py → data ingestion into Marqo
- utils/ → common utilities (env loading, helpers)

##### Core Components
1. API Layer (FastAPI)
– Routers for /v1/query and /v1/chat
– Request parsing, validation
– Telemetry middleware and general logging
2. Business Orchestrator
– QueryController (in main or a separate module) that sequences translation, LLM calls, vector retrieval, and post-processing
3. Translation Service
– Text translation submodule (Google, Bhashini, Dhruva)
– Speech-to-Text (audio→text)
– Text-to-Speech (text→audio)
4. LLM Service Layer
– Base adapter → azure_openai, openai, ollama
– Configurable prompt injection (activity_prompt, chat_intent_prompt, etc.)
5. Vector Store
– Marqo index for document retrieval
– Configured via Docker container (8882)
6. Caching
– Redis (ttl configurable)
– Used only for /v1/chat conversation history
7. Cloud Storage
– AWS/GCP/OCI bucket adapters
– Public audio URL generation for TTS outputs
8. Telemetry & Logging
– Sunbird telemetry events (batching via telemetry_logger)
– Application logs via logger.py

##### External Dependencies
- Marqo vector index (Docker container)
- Redis instance
- Azure/OpenAI/Ollama API endpoints
- Cloud object storage (AWS S3, GCP Cloud Storage, OCI Object Storage)
- Optional: Google Translation API, Bhashini/Dhruva translation services

##### Architectural Patterns & Principles
- Modular adapters (LLM, Storage, Translation) — easy to swap providers
- Orchestrator (choreography) with clear sequencing
- Separation of concerns: routing / orchestration / external calls / utilities
- Config-driven behavior via config.ini/.env
- Caching for chat history to improve context retrieval
- Async calls (FastAPI + uvicorn) for scalability

##### Final Checklist for the Engineer
– Break down the system into the 8 core components listed above
– Capture the two API flows (/v1/query vs. /v1/chat) side by side or in a single merged flow
– Highlight modular adapters and where you could plug in new providers

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients and Ingress
    Client["Clients (Parents, Teachers)"]:::external
    LB["Load Balancer"]:::compute

    %% API Layer
    subgraph "API Layer"
        API["FastAPI App (main.py)"]:::compute
        RouterQuery["/v1/query Router"]:::compute
        RouterChat["/v1/chat Router"]:::compute
        TelemetryMW["Telemetry Middleware"]:::compute
    end

    %% Business Logic
    subgraph "Business Orchestrator"
        Orchestrator["Orchestrator (io_processing.py)"]:::compute
    end

    %% AI Services
    subgraph "Translation Service"
        SpeechSTT["Speech-to-Text\n(translation/telemetry.py)"]:::compute
        TranslationText["Text Translation\n(google/bhashini/dhruva)"]:::compute
        TTS["Text-to-Speech"]:::compute
    end

    subgraph "LLM Service Layer"
        LLMAdapterBase["LLM Adapter Base\n(llm/base.py)"]:::compute
        Azure["Azure OpenAI Adapter\n(llm/azure_openai.py)"]:::compute
        OpenAI["OpenAI Adapter\n(llm/openai.py)"]:::compute
        Ollama["Ollama Adapter\n(llm/ollama.py)"]:::compute
    end

    subgraph "Vector Store"
        VectorBase["VectorStore Base\n(vectorstores/base.py)"]:::compute
        Marqo(["Marqo\n(Docker: 8882)"]):::datastore
    end

    %% Data Layer
    subgraph "Data Layer"
        Redis(["Redis Cache"]):::datastore
        IndexDocs["Index Documents\n(index_documents.py)"]:::compute
    end

    %% Storage Layer
    subgraph "Cloud Storage"
        CloudStorageBase["Storage Adapter Base\n(storage/base.py)"]:::compute
        AWS["AWS S3 Adapter\n(storage/aws.py)"]:::compute
        GCP["GCP Adapter\n(storage/gcp.py)"]:::compute
        OCI["OCI Adapter\n(storage/oci.py)"]:::compute
    end

    %% Telemetry & Logging
    subgraph "Telemetry & Logging"
        TelemetryLogger["Telemetry Logger\n(telemetry_logger.py)"]:::compute
        Logger["Application Logger\n(logger.py)"]:::compute
        Sunbird["Sunbird Telemetry Endpoint"]:::external
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        ConfigEnv["Env Manager\n(env_manager.py)"]:::compute
        ConfigFile["config.ini / .env.example"]:::compute
        UtilsEnv["Utils Env\n(utils/env.py)"]:::compute
        Utils["Utils\n(utils/utils.py)"]:::compute
        OptionalLang["LangChain Demo\n(query_with_langchain.py)"]:::compute
    end

    %% Flows
    Client --> LB --> API
    API --> RouterQuery
    API --> RouterChat
    RouterQuery --> TelemetryMW
    RouterChat --> TelemetryMW
    TelemetryMW --> Orchestrator

    Orchestrator --> SpeechSTT
    Orchestrator --> TranslationText
    Orchestrator --> Redis
    Redis --> Orchestrator
    Orchestrator --> VectorBase
    VectorBase --> Marqo
    IndexDocs --> Marqo

    Orchestrator --> LLMAdapterBase
    LLMAdapterBase --> Azure
    LLMAdapterBase --> OpenAI
    LLMAdapterBase --> Ollama

    Orchestrator --> TTS
    TTS --> CloudStorageBase
    CloudStorageBase --> AWS
    CloudStorageBase --> GCP
    CloudStorageBase --> OCI
    AWS --> Orchestrator
    GCP --> Orchestrator
    OCI --> Orchestrator

    Orchestrator --> TelemetryLogger --> Sunbird
    Orchestrator --> Logger

    %% Config & Utils Connections
    ConfigEnv --> API
    ConfigEnv --> Orchestrator
    ConfigEnv --> VectorBase
    ConfigEnv --> Redis
    ConfigEnv --> CloudStorageBase

    ConfigFile --> ConfigEnv
    UtilsEnv --> ConfigEnv
    Utils --> Orchestrator

    OptionalLang --> Orchestrator

    %% Click Events
    click API "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/main.py"
    click ConfigEnv "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/env_manager.py"
    click ConfigFile "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/config.ini"
    click ConfigFile "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/.env.example"
    click Orchestrator "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/io_processing.py"
    click IndexDocs "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/index_documents.py"
    click LLMAdapterBase "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/llm/base.py"
    click Azure "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/llm/azure_openai.py"
    click OpenAI "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/llm/openai.py"
    click Ollama "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/llm/ollama.py"
    click VectorBase "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/vectorstores/base.py"
    click Marqo "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/vectorstores/marqo.py"
    click SpeechSTT "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/translation/telemetry.py"
    click TranslationText "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/translation/base.py"
    click TranslationText "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/translation/google.py"
    click TranslationText "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/translation/bhashini.py"
    click TranslationText "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/translation/dhruva.py"
    click TranslationText "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/translation/translation_utils.py"
    click Redis "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/redis_util.py"
    click CloudStorageBase "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/storage/base.py"
    click AWS "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/storage/aws.py"
    click GCP "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/storage/gcp.py"
    click OCI "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/storage/oci.py"
    click TelemetryLogger "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/telemetry_logger.py"
    click Logger "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/logger.py"
    click UtilsEnv "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/utils/env.py"
    click Utils "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/utils/utils.py"
    click OptionalLang "https://github.com/sunbird-aiassistant/sakhi-api-service/blob/main/query_with_langchain.py"

    %% Classes
    classDef compute fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef datastore fill:#ABEBC6,stroke:#1D8348,color:#1D8348;
    classDef external fill:#FAD7A0,stroke:#B9770E,color:#B9770E;
```
