# zubairmohd/nyayabot architecture

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

- Interactive diagram: https://gitdiagram.com/zubairmohd/nyayabot
- Repository: https://github.com/zubairmohd/nyayabot

## Overview

##### Project Type and Purpose
- NyayaBot is a full-stack AI legal assistant web application focused on Indian law.
- It provides a React/Next.js frontend, Node.js/Next.js API routes for HTTP endpoints, Python-based NLP/RAG utilities, and a PostgreSQL database for persistence.
- It integrates multiple external AI services (OpenAI, Anthropic, xAI) and supports document upload, processing, and voice interaction.

##### File Structure Analysis
- Top-level:
- app.py and .streamlit/config.toml → optional Streamlit front end or Python service entry point
- pages/ → Next.js pages and serverless API routes (chat.js, generate-document.js, etc.)
- components/ → React UI modules (chat interface, document uploader, layout)
- utils/ → Python scripts for NLP, document processing, RAG, audio utilities, DB utilities
- uploads/ → file storage for user-uploaded documents
- setup_database.py → DB initialization script
- pyproject.toml & package.json → Python and Node.js dependencies
- Configuration: next.config.js, tailwind.config.js, postcss.config.js

##### Key Architecture Insights from README
- Frontend: Next.js + Tailwind CSS + Material UI, served on port 5000
- Backend: Next.js API routes that orchestrate calls to Python utilities and external AI APIs
- Python: LangChain-based RAG pipeline (FAISS vector store), PDF parsing, language detection, audio processing
- Data: PostgreSQL for user/session data, vector embeddings; uploads folder for raw documents
- External: OpenAI GPT, Anthropic Claude, xAI Grok

##### Main Components & Interactions
a. Frontend (Browser / React)
- Components: ChatInterface.js, DocumentUploader.js, Header/Layout
- Interacts via Axios/fetch with Next.js API endpoints under pages/api
b. API Gateway (Next.js serverless functions)
- Endpoints: /api/chat, /api/generate-document, /api/upload-document, /api/transcribe, /api/text-to-speech
- Responsibilities: input validation, session management, orchestrating Python utilities and external AI calls
c. Python NLP & RAG Service
- Modules: utils/process_document.py, rag_utils.py, retrieve_context.py, llm_utils.py
- Responsibilities:
- Document parsing (PDF → text)
- Chunking and embedding with LangChain + FAISS
- Retrieval of context for RAG
- Calling external LLM APIs via OpenAI/Anthropic/xAI SDKs
- Audio/text conversion via audio_utils.py
- Optionally exposed via app.py (Streamlit) or invoked via child-process/HTTP from Node.js
d. Data Layer
- PostgreSQL (via utils/db_utils.py and psycopg2) — stores user chats, embedding metadata, documents
- File storage (uploads/) — stores uploaded PDF/DOCX files temporarily
- Vector store (FAISS, in-memory or persisted on disk)
e. External AI Services
- OpenAI GPT-4o / GPT-3.5, Anthropic Claude, xAI Grok
- Accessed using API keys from environment variables

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- UI vs. API vs. Python processing vs. Data store
- Serverless Functions: Next.js API routes handle stateless requests
- Microservice-style Python modules for specialized NLP and RAG tasks
- RAG Pattern: storing embeddings in FAISS, retrieving context dynamically
- Extensibility: support for multiple AI backends, modular utility scripts
- Security: environment-based API keys, PostgreSQL connection strings

##### Final Advice
- Be as detailed as possible: include every logical component (chat, transcription, TTS, document upload/generation).
- Integration points: UI ↔ API ↔ Python ↔ DB ↔ External APIs.
- RAG pipeline specifics (embedding storage, retrieval, context assembly) since it’s core to NyayaBot’s intelligence.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client/UI Layer
    subgraph "Client/UI Layer"
        HomePage["Home Page"]:::ui
        UploadPage["Upload Page"]:::ui
        Layout["Layout.js"]:::ui
        Header["Header.js"]:::ui
        ChatInterface["ChatInterface.js"]:::ui
        DocumentUploader["DocumentUploader.js"]:::ui
        DocumentGenerator["DocumentGenerator.js"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        ChatAPI["POST /api/chat"]:::service
        GenDocAPI["POST /api/generate-document"]:::service
        UploadAPI["POST /api/upload-document"]:::service
        TranscribeAPI["POST /api/transcribe"]:::service
        TTSAPI["POST /api/text-to-speech"]:::service
        LLMProxyAPI["/api/llm-utils"]:::service
    end

    %% Processing Layer
    subgraph "Processing Layer (Python NLP/RAG Service)"
        DocParser["process_document.py"]:::service
        RAGUtils["rag_utils.py"]:::service
        RetrieveCtx["retrieve_context.py"]:::service
        LLMUtils["llm_utils.py"]:::service
        AudioUtils["audio_utils.py"]:::service
        LangDetect["language_utils.py"]:::service
        DocGenLogic["document_generator.py"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        DB[(PostgreSQL)]:::data
        FAISS[(FAISS Vector Store)]:::data
        UploadFS[/"uploads/"/]:::data
        DBInit["setup_database.py"]:::data
    end

    %% External AI Services
    subgraph "External AI Services"
        OpenAI["OpenAI GPT"]:::external
        Anthropic["Anthropic Claude"]:::external
        xAI["xAI Grok"]:::external
    end

    %% UI to API
    HomePage -->|uses| Layout
    HomePage -->|uses| Header
    HomePage -->|renders| ChatInterface
    UploadPage -->|renders| DocumentUploader
    UploadPage -->|renders| DocumentGenerator

    ChatInterface -->|chat request| ChatAPI
    DocumentGenerator -->|generate document| GenDocAPI
    DocumentUploader -->|upload file| UploadAPI

    %% Voice Flow
    ChatInterface -->|transcribe audio| TranscribeAPI
    TranscribeAPI -->|send text| ChatAPI
    ChatAPI -->|synthesize speech| TTSAPI
    TTSAPI -->|audio response| ChatInterface

    %% API to Processing
    ChatAPI -->|retrieve context| RetrieveCtx
    GenDocAPI -->|generate logic| DocGenLogic
    UploadAPI -->|parse document| DocParser
    TranscribeAPI -->|audio processing| AudioUtils
    TTSAPI -->|audio processing| AudioUtils
    ChatAPI -->|proxy LLM calls| LLMProxyAPI

    %% Processing to Data
    DocParser -->|store embeddings| FAISS
    DocParser -->|store metadata| DB
    DocParser -->|store file| UploadFS
    RetrieveCtx -->|query embeddings| FAISS
    RAGUtils -->|update metadata| DB
    DocGenLogic -->|save docs| DB

    %% Processing to External
    RAGUtils -->|call LLM| LLMUtils
    DocGenLogic -->|call LLM| LLMUtils
    LLMUtils -->|invoke| OpenAI
    LLMUtils -->|invoke| Anthropic
    LLMUtils -->|invoke| xAI
    OpenAI -->|response| LLMUtils
    Anthropic -->|response| LLMUtils
    xAI -->|response| LLMUtils
    LLMUtils -->|return| ChatAPI

    %% DB Init
    DBInit -->|setup| DB

    %% Click Events
    click ChatInterface "https://github.com/zubairmohd/nyayabot/blob/main/components/chat/ChatInterface.js"
    click DocumentUploader "https://github.com/zubairmohd/nyayabot/blob/main/components/document/DocumentUploader.js"
    click DocumentGenerator "https://github.com/zubairmohd/nyayabot/blob/main/components/document/DocumentGenerator.js"
    click Layout "https://github.com/zubairmohd/nyayabot/blob/main/components/layout/Layout.js"
    click Header "https://github.com/zubairmohd/nyayabot/blob/main/components/layout/Header.js"
    click HomePage "https://github.com/zubairmohd/nyayabot/blob/main/pages/index.js"
    click UploadPage "https://github.com/zubairmohd/nyayabot/blob/main/pages/upload.js"

    click ChatAPI "https://github.com/zubairmohd/nyayabot/blob/main/pages/api/chat.js"
    click GenDocAPI "https://github.com/zubairmohd/nyayabot/blob/main/pages/api/generate-document.js"
    click UploadAPI "https://github.com/zubairmohd/nyayabot/blob/main/pages/api/upload-document.js"
    click TranscribeAPI "https://github.com/zubairmohd/nyayabot/blob/main/pages/api/transcribe.js"
    click TTSAPI "https://github.com/zubairmohd/nyayabot/blob/main/pages/api/text-to-speech.js"
    click LLMProxyAPI "https://github.com/zubairmohd/nyayabot/blob/main/pages/api/llm-utils.js"

    click DocParser "https://github.com/zubairmohd/nyayabot/blob/main/utils/process_document.py"
    click RAGUtils "https://github.com/zubairmohd/nyayabot/blob/main/utils/rag_utils.py"
    click RetrieveCtx "https://github.com/zubairmohd/nyayabot/blob/main/utils/retrieve_context.py"
    click LLMUtils "https://github.com/zubairmohd/nyayabot/blob/main/utils/llm_utils.py"
    click AudioUtils "https://github.com/zubairmohd/nyayabot/blob/main/utils/audio_utils.py"
    click LangDetect "https://github.com/zubairmohd/nyayabot/blob/main/utils/language_utils.py"
    click DocGenLogic "https://github.com/zubairmohd/nyayabot/blob/main/utils/document_generator.py"

    click DBInit "https://github.com/zubairmohd/nyayabot/blob/main/setup_database.py"
    click UploadFS "https://github.com/zubairmohd/nyayabot/tree/main/uploads/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef service fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef data fill:#FFDDA0,stroke:#333,stroke-width:1px
    classDef external fill:#E8D0FF,stroke:#333,stroke-width:1px
```
