# yash2002vardhan/naptick_assignment architecture

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

- Interactive diagram: https://gitdiagram.com/yash2002vardhan/naptick_assignment
- Repository: https://github.com/yash2002vardhan/naptick_assignment

## Overview

##### Project Type and Purpose
- This repository contains two full-stack AI applications focused on sleep coaching:
- RAG Project: Retrieval-Augmented Generation system using FAISS or Pinecone, OpenAI/Huggingface embeddings, Gradio UI.
- Voice Project: Voice-based sleep assistant with speech-to-text (Whisper), text-to-speech, caching DB, Gradio UI.

##### File Structure Analysis
- Top-level folders: `rag_project/` and `voice_project/`.
- Each contains:
- `main.py` (and `alternate_main.py` in voice) – application entry points launching Gradio interfaces.
- `utils/` – modular helpers (embedding generation, vector store, PDF conversion, caching, audio mixing).
- `datasets/` – raw input (chat logs, fitbit CSVs, research papers, sleep data).
- Pre-built indices (FAISS folders) in RAG, optional embeddings folder in Voice.
- Docker and docker-compose configs, `.env.example` for API keys.

##### Key Architectural Insights from README
- Both use Gradio as the frontend interface, exposing endpoints on port 7860.
- RAG pipelines:
- Data ingestion → embeddings → vector store (FAISS/Pinecone) → similarity search → LLM prompt.
- Supports two embedding engines, two index types.
- Voice pipeline:
- Audio input → Whisper ASR → optional RAG retrieval (in alternate_main) → LLM for response generation → TTS → audio output.
- Caching DB stores conversation history and avoids repeated transcriptions or LLM calls.

##### Components and Relationships
a. Main Components
- Frontend Layer: Gradio web interface (Rectangles).
- Backend Application: Python runtime container (Docker), orchestrated by Docker-Compose.
- Retrieval Services:
- Vector Store (FAISS or Pinecone)
- Embedding Generator (OpenAI/Huggingface)
- LLM Endpoint: OpenAI API (ChatGPT, Embeddings API).
- Data Layer:
- Datasets (CSV, Markdown, PDFs)
- Pre-built FAISS indices
- Caching Database (e.g., SQLite or local JSON cache) in Voice Project.
- Audio Services (Voice Project): Whisper ASR, TTS engine (OpenAI or other), FFmpeg for processing.
- External Services: Pinecone API (optional), OpenAI API.

1. User → Gradio UI: question (text or audio).
2. In RAG: UI → Backend → Embedding Generator → Vector Store → Top-k docs → LLM Prompt → OpenAI API → Response → UI.
3. In Voice: UI (audio) → Whisper ASR → text → (optional RAG retrieval) → LLM → TTS → FFmpeg → UI (audio).
4. Caching DB reads/writes conversation and embeddings reuse.
5. Docker-Compose connects each container (app, vector store if separate, caching DB).

c. Architectural Patterns and Principles
- Modular pipeline stages (Separation of Concerns).
- Retrieval-Augmented Generation pattern in RAG and alternate Voice.
- Micro-components within single container (could evolve into microservices).
- Containerization for environment parity (Docker + Compose).
- Config-driven via `.env` files.

d. Technologies and Frameworks
- Python 3.10, Gradio, OpenAI API, Huggingface Embeddings, FAISS, Pinecone SDK, Docker, Docker-Compose, Whisper, FFmpeg, crewai (alternate voice).

- Blue rectangles for compute components (Python services)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% RAG Project
    subgraph "RAG Project"
        subgraph "Docker Container"
            UI["Gradio UI (port 7860)"]:::frontend
            Proc["Text Processing"]:::compute
            Embed["Embedding Generator"]:::compute
            VecStore["Vector Store Interface"]:::compute
        end
        RawData["Raw Datasets"]:::datastore
        FAISSgen["FAISS Index Generic"]:::datastore
        FAISSoai["FAISS Index OpenAI"]:::datastore
        EnvRAG[".env.example"]:::config
        DockerRAG["Dockerfile & docker-compose"]:::config
    end

    %% Voice Project
    subgraph "Voice Project"
        subgraph "Docker Container"
            UIV["Gradio Audio UI (port 7860)"]:::frontend
            AltUI["Alternate Audio RAG UI"]:::frontend
            Whisper["Whisper ASR"]:::compute
            Rave["Retrieval Service"]:::compute
            LLMV["LLM Service"]:::compute
            TTS["TTS Engine"]:::compute
            FFmpeg["FFmpeg Processor"]:::compute
        end
        CacheDB["Caching DB"]:::datastore
        EnvV[".env.example"]:::config
        DockerV["Dockerfile & docker-compose"]:::config
        RawV["Raw Datasets"]:::datastore
        PDFconv["PDF to Markdown"]:::compute
        AddBGM["Audio Mixing"]:::compute
        Prompts["Prompt Templates"]:::compute
        Agentic["Agentic Tools"]:::compute
        Responses["Static Responses"]:::datastore
        BGM["Background Music"]:::datastore
    end

    %% External Services
    OpenAIAPI["OpenAI API"]:::external
    PineconeAPI["Pinecone API"]:::external

    %% RAG Data Flows
    UI -->|"text query"| Proc
    Proc -->|"clean text"| Embed
    Embed -->|"embeddings"| VecStore
    VecStore -->|"similarity search"| FAISSgen
    VecStore -->|"similarity search"| FAISSoai
    VecStore -->|"optional Pinecone"| PineconeAPI
    VecStore -->|"top-k docs"| Proc
    Proc -->|"prompt"| OpenAIAPI
    OpenAIAPI -->|"response"| UI
    RawData --> Embed
    RawData --> Proc
    EnvRAG --- DockerRAG
    DockerRAG --- UI

    %% Voice Data Flows
    UIV -->|"audio input"| Whisper
    Whisper -->|"text"| Rave
    Rave -->|"docs"| RawV
    Rave -->|"top-k docs"| LLMV
    LLMV -->|"text response"| TTS
    TTS -->|"audio"| FFmpeg
    FFmpeg -->|"processed audio"| UIV
    CacheDB <--> Whisper
    CacheDB <--> LLMV
    RawV --> PDFconv
    PDFconv --> Rave
    AddBGM --> FFmpeg
    Prompts --> LLMV
    Agentic --> Whisper
    EnvV --- DockerV
    DockerV --- UIV

    %% Click Events RAG
    click UI "https://github.com/yash2002vardhan/naptick_assignment/blob/main/rag_project/main.py"
    click DockerRAG "https://github.com/yash2002vardhan/naptick_assignment/tree/main/rag_project/Dockerfile"
    click DockerRAG "https://github.com/yash2002vardhan/naptick_assignment/blob/main/rag_project/docker-compose.yml"
    click EnvRAG "https://github.com/yash2002vardhan/naptick_assignment/blob/main/rag_project/.env.example"
    click Embed "https://github.com/yash2002vardhan/naptick_assignment/blob/main/rag_project/utils/generate_embeddings.py"
    click VecStore "https://github.com/yash2002vardhan/naptick_assignment/blob/main/rag_project/utils/get_vector_store.py"
    click Proc "https://github.com/yash2002vardhan/naptick_assignment/blob/main/rag_project/utils/process_txt.py"
    click RawData "https://github.com/yash2002vardhan/naptick_assignment/tree/main/rag_project/datasets/"
    click FAISSgen "https://github.com/yash2002vardhan/naptick_assignment/tree/main/rag_project/faiss_index_generic/"
    click FAISSoai "https://github.com/yash2002vardhan/naptick_assignment/tree/main/rag_project/faiss_index_openai/"

    %% Click Events Voice
    click UIV "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/main.py"
    click AltUI "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/alternate_main.py"
    click DockerV "https://github.com/yash2002vardhan/naptick_assignment/tree/main/voice_project/Dockerfile"
    click DockerV "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/docker-compose.yml"
    click EnvV "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/.env.example"
    click CacheDB "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/utils/check_cache.py"
    click Rave "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/utils/get_relevant_docs.py"
    click PDFconv "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/utils/pdf_to_markdown.py"
    click AddBGM "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/utils/add_bgm.py"
    click Prompts "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/utils/prompts.py"
    click Agentic "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/utils/agentic_tools.py"
    click Responses "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/utils/responses.txt"
    click RawV "https://github.com/yash2002vardhan/naptick_assignment/tree/main/voice_project/datasets/"
    click BGM "https://github.com/yash2002vardhan/naptick_assignment/blob/main/voice_project/bgm.mp3"

    %% Styles
    classDef frontend fill:#ADE8F4,stroke:#0077B6,stroke-width:1px;
    classDef compute fill:#CAF0F8,stroke:#0096C7,stroke-width:1px;
    classDef datastore fill:#90E0EF,stroke:#00B4D8,stroke-width:1px,stroke-dasharray:5 5;
    classDef config fill:#BDE0FE,stroke:#023E8A,stroke-width:1px;
    classDef external fill:#E0FBFC,stroke:#03045E,stroke-width:1px,stroke-dasharray:2 2;
```
