# phrugsa-limbunlom/picksmart architecture

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

- Interactive diagram: https://gitdiagram.com/phrugsa-limbunlom/picksmart
- Repository: https://github.com/phrugsa-limbunlom/picksmart

## Overview

##### Project type and purpose
- PickSmart is a full-stack, distributed AI-powered shopping assistant.
- It consists of:
- A React-based SPA (“chatbot-app”) for user interaction.
- A FastAPI backend (“chatbot-server”) implementing a Retrieval-Augmented Generation (RAG) pipeline with AI agents.
- Kafka for event streaming.
- MongoDB as a vector store.
- External AI services (Groq API, Tavily search API, LangChain, LangGraph).

##### File structure
Top-level directories:
- chatbot-app – React frontend (public, src, Dockerfile, package.json)
- chatbot-server – Python backend (agent, processor, service, data, utils, main.py, Dockerfile, model.yaml)
- kafka – Kafka broker config (Dockerfile, config/)
- docker-compose.yaml – brings up all containers in a network
Patterns:
- Clean separation frontend vs. backend.
- Backend is layered: service → processor → agent → data.
- Event-driven: Kafka broker between producer & consumer.
- RAG: vector store for embeddings in MongoDB.
Config & deployment:
- Dockerfiles per component.
- docker-compose orchestrates multi-container network.

##### Additional README insights
- Tech stack: React, FastAPI, Kafka, MongoDB, LangChain, LangGraph, Tavily, Groq.
- Agent workflow: Query Analysis → Online Shop Search → Analysis & Ranking → Product Source Search (implemented in SearchAgent.py & orchestrated via LangGraph).

##### Elements
- Clear labels: “React Frontend”, “FastAPI Backend”, “Kafka Broker”, “MongoDB Vector Store”, “Groq API”, “Tavily API”, “LangGraph Orchestrator”
– HTTP: Frontend → Backend → Frontend
– API calls: Backend → External AI services
– Data flow: Backend → MongoDB
– Events: Backend ↔ Kafka
– Blue rectangles: services/components
– Clouds: external APIs
– Sequence numbers: agent workflow steps

##### Final advice
1. High-level overview (user → frontend → backend → data stores → external services)
2. Detailed backend sub-architecture (layered services & agent state graph)
- Environment boundaries: Docker Compose network, container per service
- Keep it detailed but avoid clutter by grouping related modules.
- Iterate with dev team to validate component names and data flows before finalizing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ReactFrontend["React Frontend (SPA)"]:::frontend
        EntryPoint["src/index.js"]:::frontend
        AppComponent["src/App.js"]:::frontend
        PublicHTML["public/index.html"]:::frontend
        FrontendDocker["Dockerfile"]:::service
        EntryPoint -->|imports| AppComponent
        AppComponent -->|renders| ReactFrontend
        PublicHTML -->|template| ReactFrontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        API["FastAPI Backend"]:::service
        MainPY["src/main.py"]:::service
        ChatbotApp["src/chatbot.py"]:::service
        ServiceLayer["ChatbotService"]:::service
        Processor["ChatbotProcessor"]:::service
        Agent["SearchAgent"]:::service
        VectorService["VectorStoreService"]:::service
        DataModels["Data Models"]:::data
        Constants["PromptMessage.py"]:::service
        Utils["file_utils.py"]:::service

        MainPY -->|starts| API
        API -->|defines routes| ChatbotApp
        ChatbotApp -->|calls| ServiceLayer
        ServiceLayer -->|delegates| Processor
        Processor -->|orchestrates| Agent
        Agent -->|uses| VectorService
        Agent -->|uses| Constants
        Agent -->|uses| Utils
        DataModels -->|used by| ServiceLayer
    end

    %% Data & Messaging Layer
    subgraph "Data & Messaging"
        direction TB
        KafkaBroker["Kafka Broker"]:::data
        MongoDB["MongoDB Vector Store"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GroqAPI["Groq API"]:::external
        TavilyAPI["Tavily API"]:::external
        LangGraph["LangGraph Orchestrator"]:::external
        LangChain["LangChain RAG Toolkit"]:::external
    end

    %% High-level interactions
    ReactFrontend -->|HTTP/JSON| API
    API -->|returns JSON| ReactFrontend

    API -->|publishes events| KafkaBroker
    KafkaBroker -->|subscribed by| API

    ServiceLayer -->|reads/writes embeddings| MongoDB

    Agent -->|calls| LangGraph
    Agent -->|calls| LangChain
    Agent -->|calls| GroqAPI
    Agent -->|calls| TavilyAPI

    %% Click Events
    click ReactFrontend "https://github.com/phrugsa-limbunlom/picksmart/tree/main/chatbot-app/"
    click EntryPoint "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-app/src/index.js"
    click AppComponent "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-app/src/App.js"
    click PublicHTML "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-app/public/index.html"
    click FrontendDocker "https://github.com/phrugsa-limbunlom/picksmart/tree/main/chatbot-app/Dockerfile"
    click MainPY "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/main.py"
    click ChatbotApp "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/chatbot.py"
    click ServiceLayer "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/service/ChatbotService.py"
    click VectorService "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/service/VectorStoreService.py"
    click Processor "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/processor/ChatbotProcessor.py"
    click Agent "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/agent/SearchAgent.py"
    click DataModels "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/data/ChatMessage.py"
    click Constants "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/constants/PromptMessage.py"
    click Utils "https://github.com/phrugsa-limbunlom/picksmart/blob/main/chatbot-server/src/utils/file_utils.py"
    click FrontendDocker "https://github.com/phrugsa-limbunlom/picksmart/tree/main/chatbot-server/Dockerfile"
    click KafkaBroker "https://github.com/phrugsa-limbunlom/picksmart/tree/main/kafka/"
    click MongoDB "https://github.com/phrugsa-limbunlom/picksmart/blob/main/docker-compose.yaml"

    %% Styles
    classDef frontend fill:#D6E9FE,stroke:#4C8BF5,color:#000
    classDef service fill:#D0F0C0,stroke:#3B9D12,color:#000
    classDef data fill:#FEE2B3,stroke:#E69A00,color:#000
    classDef external fill:#F6D1D1,stroke:#D83A3A,color:#000
```
