# nvidia-ai-blueprints/aiq-research-assistant architecture

> Architecture diagram of the GitHub repository nvidia-ai-blueprints/aiq-research-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia-ai-blueprints/aiq-research-assistant
- Repository: https://github.com/nvidia-ai-blueprints/aiq-research-assistant

## Overview

##### Project Type and Purpose
- This is a full-stack AI research assistant blueprint. It combines a demo frontend web app, a Python backend service (the `aiq_aira` package), a middleware proxy, and integrations with external AI/RAG microservices and web search. Its purpose is to enable on-premise deep research using internal documents and optional web search.

##### File Structure Analysis
- Top-level directories:
- `aira`: Python package containing core AI-Q Research Assistant logic and REST API entrypoints.
- `data`: Sample datasets and scripts for on-premise document ingestion.
- `demo`: Demo frontend container (source not included) exposing the web UI.
- `deploy/compose`: Docker Compose files and NGINX proxy templates.
- `notebooks`: Jupyter notebooks for quick experimentation.
- Key configs: `aira/configs/config.yml`, `Dockerfile` in `aira` and `data`.
- Tests in `aira/test_aira` exercise each backend function.

##### README Insights
- Components described:
- Demo Frontend (web app container)
- Backend Service (`aiq-aira` Python package, exposed via REST)
- Middleware Proxy (NGINX routing to backend and NVIDIA RAG)
- External Services: NVIDIA RAG Blueprint, NeMo Retriever Microservices, NIM Microservices, Tavily web search.

##### Main Components
a. User & Demo Frontend (Docker container hosting web UI)
b. NGINX Middleware Proxy (routes HTTP between frontend, backend, RAG services)
c. AI-Q Research Assistant Backend (Python `aiq_aira` service; includes modules for plan generation, RAG queries, summary)
d. NVIDIA RAG Services (hosted or local microservices for document retrieval)
e. NVIDIA NeMo Retriever & NIM Microservices (multi-modal ingest and embedding)
f. External Web Search (Tavily API)
g. On-Premise Data Store (mounted volume with internal documents)
h. Docker Compose Orchestrator (defines service graph)

##### Relationships and Interactions
- User → Frontend (HTTP)
- Frontend → NGINX Proxy → Backend API endpoints
- Backend → RAG Services (via REST)
- Backend → Web Search (Tavily HTTP)
- Backend → Data Store (local file I/O)
- NGINX → Routes to NVIDIA RAG vs AI-Q backend based on path

##### Architectural Patterns & Technologies
- Microservices (separate containers for each service)
- Layered separation: Presentation (frontend), API layer (backend), integration layer (proxy), external AI services.
- Config-as-code with YAML (`config.yml`), Dockerfiles, Docker Compose.
- Python with LangGraph toolkit (observability, config).
- NGINX as reverse-proxy and TLS terminator.
- RESTful APIs for service communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Classes
    classDef user fill:#ADD8E6,stroke:#000;
    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef infra fill:#D3D3D3,stroke:#000;
    classDef backend fill:#90EE90,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;

    %% Orchestrator
    subgraph "Docker Compose Orchestrator" 
        DC["docker-compose.yaml"]:::infra
    end

    %% User and Frontend
    User["User"]:::user
    Frontend["Demo Frontend"]:::frontend
    User -->|"HTTP"| Frontend

    %% Middleware Proxy
    NGINX["NGINX Middleware Proxy"]:::infra

    %% Backend Service
    subgraph "AI-Q Research Assistant Backend" 
        BackendCore["aiq_aira Service"]:::backend
        subgraph "Backend Modules"
            PlanGen["Plan Generation"]:::backend
            ArtifactQA["Artifact QA (RAG)"]:::backend
            Summary["Summary Generation"]:::backend
            SearchUtil["Search & Web Search"]:::backend
            Schema["Schema & Constants"]:::backend
        end
    end

    %% External Services
    subgraph "External AI Services"
        RAGCluster["NVIDIA RAG Services"]:::external
        NeMoCluster["NeMo Retriever & NIM"]:::external
        Tavily["Tavily Web Search"]:::external
    end

    %% Data Store
    DataStore["On-Premise Data Store"]:::infra

    %% Orchestration Links
    DC --> Frontend
    DC --> NGINX
    DC --> BackendCore
    DC --> DataStore
    DC --> RAGCluster
    DC --> NeMoCluster
    DC --> Tavily

    %% Request Flows
    Frontend -->|"HTTP"| NGINX
    NGINX -->|"REST /api/*"| BackendCore
    NGINX -->|"REST /rag/*"| RAGCluster

    BackendCore -->|"REST"| RAGCluster
    BackendCore -->|"REST"| NeMoCluster
    BackendCore -->|"HTTP"| Tavily
    BackendCore -->|"File I/O"| DataStore

    %% Backend Internals Flow (implicit)
    BackendCore --> PlanGen
    BackendCore --> ArtifactQA
    BackendCore --> Summary
    BackendCore --> SearchUtil
    ArtifactQA --> Schema

    %% Click Events
    click Frontend "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/tree/main/demo/"
    click NGINX "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/blob/main/deploy/compose/nginx.conf.template"
    click DC "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/blob/main/deploy/compose/docker-compose.yaml"
    click BackendCore "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/tree/main/aira/Dockerfile"
    click PlanGen "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/blob/main/aira/src/aiq_aira/functions/generate_queries.py"
    click ArtifactQA "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/blob/main/aira/src/aiq_aira/functions/artifact_qa.py"
    click Summary "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/blob/main/aira/src/aiq_aira/functions/generate_summary.py"
    click SearchUtil "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/blob/main/aira/src/aiq_aira/search_utils.py"
    click Schema "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/blob/main/aira/src/aiq_aira/schema.py"
    click DataStore "https://github.com/nvidia-ai-blueprints/aiq-research-assistant/tree/main/data/files/"
    class User user
    class Frontend frontend
    class NGINX infra
    class DC infra
    class BackendCore backend
    class PlanGen backend
    class ArtifactQA backend
    class Summary backend
    class SearchUtil backend
    class Schema backend
    class DataStore infra
    class RAGCluster external
    class NeMoCluster external
    class Tavily external
```
