# naveenalampally8/partselect-agent architecture

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

- Interactive diagram: https://gitdiagram.com/naveenalampally8/partselect-agent
- Repository: https://github.com/naveenalampally8/partselect-agent

## Overview

##### Project Type & Purpose
- This is a full-stack conversational AI prototype (React + FastAPI) implementing a Retrieval-Augmented Generation (RAG) multi-agent architecture.
- Purpose: help customers search appliance parts, check compatibility, get installation guidance, and troubleshoot via a chat interface.

##### File Structure Analysis
- Top-level:
- backend/
– app.py (FastAPI entry point)
– agents/ (Orchestrator, Router, ProductSearch, Compatibility, Installation, Troubleshooting)
– database/ (SQLite models & seed scripts)
– vector_store/ (ChromaDB embeddings module)
– scripts/ (data scraping & JSON)
– backup/ (Chroma backups & sample data)
- frontend/
– public/ (static HTML + manifest)
– src/ (React components, API client)
– vite.config.js, package.json
- render.yaml (deployment config)

##### Key Architecture Insights (from README)
- Multi-agent system with a central orchestrator and specialized sub-agents.
- Hybrid search: semantic via ChromaDB + structured via SQLite.
- External LLM calls via DeepSeek API.
- Streaming chat responses over HTTP/SSE.

##### Main Components
A. Frontend Layer (React App)
- ChatWindow component, streaming UI
- API client (Axios)
B. API Layer (FastAPI Backend)
- HTTP/SSE endpoint (app.py)
- Orchestrator Agent
- Router Agent
- Specialized Agents (ProductSearch, Compatibility, Installation, Troubleshooting)
C. Data Layer
- SQLite relational database (parts, models, relationships)
- ChromaDB vector store (embeddings, semantic index)
D. External Services
- DeepSeek API (LLM)
E. Deployment/Infrastructure

##### Relationships & Data Flows
1. User → Frontend (HTTP/SSE) → Backend API
2. Orchestrator Agent routes to Router Agent (intent classification)
3. Router Agent invokes one or more specialized agents:
– ProductSearch: queries ChromaDB → filters with SQLite
– Compatibility: SQL model-part lookups
– Installation: static steps (from JSON or code)
– Troubleshooting: symptom lookup + recommendations
4. Specialized agent → (optionally) DeepSeek API for LLM completions or clarifications
5. Agent aggregates results → back to Orchestrator → streams response to Frontend
6. Backend reads/writes to Databases as needed

##### Architectural Patterns & Design Principles
- Modular “agent” pattern: each agent is a self-contained service component.
- RAG: Combining semantic search (ChromaDB) with LLM retrieval.
- Layered design: Presentation (React) → API (FastAPI) → Data.
- Single process multi-modules (not separate microservices—can evolve to microservices).
- CI/CD and Infrastructure as Code hint via render.yaml.

##### Technologies & Frameworks to Annotate
- Frontend: React 18, Vite, Tailwind CSS, Axios
- Backend: Python 3.11, FastAPI, SQLAlchemy
- Vector Store: ChromaDB, sentence-transformers
- Database: SQLite
- LLM: DeepSeek API

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        ChatWindow["ChatWindow"]:::frontend
        Styles["ChatWindow Styles"]:::frontend
        ApiClient["API Client (Axios)"]:::frontend
        App["Main App (App.js)"]:::frontend
        Vite["Vite Config (vite.config.js)"]:::frontend
    end

    subgraph "Backend API & Agents"
        API["FastAPI Endpoint\nHTTP/SSE"]:::backend
        Orchestrator["Orchestrator Agent"]:::backend
        Router["Router Agent"]:::backend
        ProdSearch["ProductSearch Agent"]:::backend
        Compatibility["Compatibility Agent"]:::backend
        Installation["Installation Agent"]:::backend
        Troubleshoot["Troubleshooting Agent"]:::backend
        DeepSeekClient["DeepSeek API Client"]:::backend
    end

    subgraph "Data Layer"
        SQLite["SQLite Relational DB"]:::data
        Chroma["ChromaDB Vector Store"]:::data
    end

    subgraph "External Services"
        LLM["DeepSeek LLM API"]:::external
    end

    ChatWindow -->|"HTTP/SSE request"| API
    API -->|"invoke"| Orchestrator
    Orchestrator -->|"route"| Router
    Router -->|"intent"| ProdSearch
    Router -->|"intent"| Compatibility
    Router -->|"intent"| Installation
    Router -->|"intent"| Troubleshoot

    ProdSearch -->|"vector search"| Chroma
    ProdSearch -->|"SQL query"| SQLite
    Compatibility -->|"SQL query"| SQLite
    Installation -->|"read steps"| SQLite
    Troubleshoot -->|"SQL query"| SQLite

    ProdSearch -->|"LLM call"| DeepSeekClient
    Compatibility -->|"LLM call"| DeepSeekClient
    Installation -->|"LLM call"| DeepSeekClient
    Troubleshoot -->|"LLM call"| DeepSeekClient

    DeepSeekClient -->|"HTTP"| LLM

    ProdSearch -->|"result"| Orchestrator
    Compatibility -->|"result"| Orchestrator
    Installation -->|"result"| Orchestrator
    Troubleshoot -->|"result"| Orchestrator

    Orchestrator -->|"stream"| API
    API -->|"SSE response"| ChatWindow

    click ChatWindow "https://github.com/naveenalampally8/partselect-agent/blob/main/frontend/src/components/ChatWindow.js"
    click Styles "https://github.com/naveenalampally8/partselect-agent/blob/main/frontend/src/components/ChatWindow.css"
    click ApiClient "https://github.com/naveenalampally8/partselect-agent/blob/main/frontend/src/api/api.js"
    click App "https://github.com/naveenalampally8/partselect-agent/blob/main/frontend/src/App.js"
    click Vite "https://github.com/naveenalampally8/partselect-agent/blob/main/frontend/vite.config.js"
    click API "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/app.py"
    click Orchestrator "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/agents/orchestrator.py"
    click Router "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/agents/router_agent.py"
    click ProdSearch "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/agents/product_search_agent.py"
    click Compatibility "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/agents/compatibility_agent.py"
    click Installation "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/agents/installation_agent.py"
    click Troubleshoot "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/agents/troubleshooting_agent.py"
    click DeepSeekClient "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/agents/deepseek_client.py"
    click SQLite "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/database/models.py"
    click Chroma "https://github.com/naveenalampally8/partselect-agent/blob/main/backend/vector_store/embeddings.py"

    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px
    classDef data fill:#fc9,stroke:#333,stroke-width:1px
    classDef external fill:#c9f,stroke:#333,stroke-width:1px
```
