How zakantonio/marketassistant-mvp works
Project Type and Overall Purpose
• The project is an MVP full-stack web application that uses AI for product search and recipe suggestion. It offers a voice interface, leverages natural language processing via Ollama, and interacts with a PostgreSQL database (Supabase).
• The README explicitly divides the system into a Client (web interface), Main API (handling NLP and coordinating actions), and a Product API (managing the product/recipe database). In addition, there is a separate service for speech processing.
Analyzing the File Structure to Identify Main Components
• Client:
• Located in the “client” directory. It contains HTML, CSS, JavaScript, and assets (including debug tools). This is the frontend web interface where users interact with the assistant.
• Main API (Chatbot):
• The “chatbot” directory is the heart of the project’s logic. It includes a FastAPI-based API (api.py) and various agents under “chatbot/agents” (e.g., product_search_agent, recipe_search_agent, ingredient_based_recipe_agent, info_agent) that handle different aspects of query resolution.
• The “chatbot/utils” directory contains components like AudioTranscriber and a message_broker, indicating internal communication between modules or asynchronous processing.
• The presence of Dockerfiles and .dockerignore in the chatbot directory confirms that the Main API is containerized.
• Product API (Database Service):
• Found in the “database” directory. It contains a Dockerfile, a product_api.py, requirements, and a Supabase client, signifying that it specifically manages and exposes the product and recipe data.
• The inclusion of an SQL backup dump further supports its role as the data storage/backing service.
• Speech Processing Service:
• The “whisper-service” directory includes server.py, Dockerfile, and CUDA utilities, indicating that this service is dedicated to speech-to-text processing using Faster Whisper.
• Additional/Other Components:
• The “other” directory includes a TTS_Piper.py, suggesting that there might be voice synthesis capabilities, although this seems supplemental.
Architectural Patterns and Relationships
• Communication Flow:
• The Client sends user interactions (including text and voice commands) to the Main API.
• The Main API processes these inputs by leveraging multiple agents to handle searches and recipe suggestions.
• For voice commands, the Main API likely interacts with the whisper-service (and possibly the TTS/Piper from “other”) to transcribe or synthesize speech.
• When product-related queries or recipe data is needed, the Main API interfaces with the Product API in the “database” component.
• Containerization:
• Each major component (client, chatbot, database, whisper-service) is built using Docker (as shown by the Dockerfiles and the docker-compose.yml), which signifies microservice or multi-container architecture.
• Messaging/Asynchrony:
• The message_broker in the chatbot utils possibly plays a role in enabling asynchronous communication between the processing agents or services.