# paolopangallo/mcp_e-commerce architecture

> Architecture diagram of the GitHub repository paolopangallo/mcp_e-commerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paolopangallo/mcp_e-commerce
- Repository: https://github.com/paolopangallo/mcp_e-commerce

## Overview

1. **Overall shape**
   This is a full-stack eBay shopping assistant. The backend is a FastAPI service in `app/`, the frontend is a React/Vite app in `ebay-ui/`, and the runtime depends on PostgreSQL, Redis, and Qdrant. The architecture is centered on an AI agent that can stream its reasoning and invoke domain tools.

2. **Primary request entry points**
   `app/main.py` bootstraps the backend and wires the API routers under `app/api/`. The most important endpoints are the agent streaming API, classic search, and seller analysis. The frontend talks to these endpoints through `ebay-ui/src/api/apiClient.ts` and the streaming hooks under `ebay-ui/src/features/agent/`.

3. **User-facing interaction flow**
   The dominant user flow is chat-driven: the React chat page submits a request, the backend returns server-sent event style updates, and the UI renders “thinking” stages, tool output, and domain cards such as item details, metadata, wishlist, trends, and seller trust. The frontend is organized by feature, not by technical layer, which matches the domain-specific response types.

4. **Agent orchestration layer**
   The agent subsystem lives in `app/agent/` and is complemented by `app/services/agent_executor.py`. It follows a ReAct-style pattern: prompts and schemas define the reasoning format, a planner and task decomposer break down the user intent, memory keeps short-term context, and a tool registry exposes callable capabilities. This is the core decision-making boundary of the system.

5. **Tool execution boundary**
   The `app/mcp/` package is the execution/tooling layer. It provides an MCP-style server/client split, a Playwright-based browser automation path, and domain tools for search, item lookup, seller lookup, deals, trends, profile, conversation, contact_seller, and wishlist. The agent does not directly embed all business logic; it delegates to these tools through a standardized interface.

6. **eBay integration and scraping**
   eBay-specific behavior is split across `app/services/ebay.py`, `ebay_playwright.py`, `ebay_metadata.py`, `ebay_user.py`, and scraping helpers such as `scraping_brands.py`. This layer is responsible for fetching live marketplace data, scraping pages when needed, and normalizing the results into the app’s own domain structures.

7. **Search, ranking, and seller intelligence**
   The main business pipelines are `search_pipeline.py`, `seller_pipeline.py`, and `compare_pipeline.py`. These combine query parsing, candidate retrieval, trust scoring, sentiment, price tracking, and user preference matching. `app/services/trust.py`, `feedback.py`, `user_profiling.py`, and `price_tracker.py` are the main inputs to ranking and seller evaluation.

8. **RAG subsystem**
   `app/services/rag/` is a self-contained retrieval stack. It includes chunking, embeddings, BM25, Qdrant storage, reranking, query expansion, context building, and learning-to-rank features/training. The repo includes a persisted Qdrant store under `qdrant_storage/`, and there are local FAISS artifacts in `app/test/` for offline or test scenarios. This subsystem feeds the agent and search pipeline with semantically retrieved product and feedback context.

9. **NLP and LLM services**
   `app/services/nlp_ner.py`, `nlp_sentiment.py`, `parser.py`, and `app/llm/` provide structured understanding of free-form user input and generated explanations. The README indicates spaCy plus Gemini as the main NLP/LLM stack, and `app/llm/vision.py` suggests multimodal analysis when images are involved. These services sit upstream of search and agent planning.

10. **Persistence and caching**
   PostgreSQL is the primary relational store, with SQLAlchemy models in `app/models/` for users, listings, and wishlists, and Alembic migrations in `alembic/`. Redis is used for transient state and cache-like data through `app/db/redis.py` and `app/config/cache.py`. This cleanly separates durable domain data from ephemeral session, feedback, and performance data.

11. **Authentication and user settings**
   Authentication is isolated in `app/auth/` with JWT handling, password utilities, config, dependencies, and router integration. User settings and personalization are part of the domain model and are surfaced in both the backend and frontend settings UI. This boundary matters because user identity affects saved wishlists, preferences, and recommendation/trust behavior.

12. **Frontend domain composition**
   The UI is split into feature modules for chat, search, seller, auth, and agent streaming. State is managed in feature-local stores such as chat, wishlist, sidebar, and settings. Components like comparison cards, seller trust gauges, and market trend panels map directly to backend concepts, which makes the UI a projection of the backend’s domain model rather than a generic interface.

13. **Testing, scripts, and operational support**
   The repository contains integration and unit tests for agent streaming, MCP tools, Playwright, Redis, and search behavior under `tests/` and `app/test/`. There are also scripts for dataset analysis, LTR training, embedding checks, and environment sanitization. This indicates the project is operationally oriented around offline evaluation, ranking experiments, and reproducible agent/tool behavior.

14. **Deployment/runtime boundaries**
   `docker-compose.yaml` and the README imply local multi-service development with FastAPI, Postgres, Redis, and Qdrant running together. The backend can also run its MCP/playwright components separately, which creates a clear split between the API surface, the agent/tool orchestration layer, and the external automation/runtime dependencies.

Main entry points: [`app/api/routes.py`](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/api/routes.py) (API routes), [`app/services/agent_executor.py`](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/agent_executor.py) (Agent executor), [`app/mcp/core.py`](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/mcp/core.py) (MCP core), [`app/services/search_pipeline.py`](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/search_pipeline.py) (Search pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_main["App entry<br/>FastAPI bootstrap<br/>[main.py]"]
  node_routes["API routes<br/>HTTP router<br/>[routes.py]"]
  node_agent_stream["Agent stream<br/>SSE endpoint<br/>[agent_stream.py]"]
  node_auth_router["Auth router<br/>JWT HTTP<br/>[auth_router.py]"]
  node_agent_exec["Agent executor<br/>Orchestration service<br/>[agent_executor.py]"]
  node_planner["Planner<br/>Task planning<br/>[planner.py]"]
  node_memory["Agent memory<br/>Context state<br/>[memory.py]"]
  node_tool_registry["Tool registry<br/>Tool binding<br/>[tool_registry.py]"]
  node_mcp_core{{"MCP core<br/>Tool runtime<br/>[core.py]"}}
  node_playwright_server["Playwright server<br/>Browser automation"]
  node_search_pipeline["Search pipeline<br/>Ranking pipeline<br/>[search_pipeline.py]"]
  node_seller_pipeline["Seller pipeline<br/>Seller intelligence<br/>[seller_pipeline.py]"]
  node_ebay_service["eBay service<br/>Marketplace adapter<br/>[ebay.py]"]
  node_rag_store{{"RAG store<br/>Retrieval stack<br/>[qdrant_store.py]"}}
  node_nlp_llm["NLP + LLM<br/>Text understanding<br/>[parser.py]"]
  node_models_user[("User model<br/>SQLAlchemy model<br/>[user.py]")]
  node_models_listing[("Listing model<br/>SQLAlchemy model<br/>[listing.py]")]
  node_db_main[("DB layer<br/>Postgres + Redis<br/>[database.py]")]
end

subgraph group_frontend["Frontend"]
  node_ui_app["UI shell<br/>React/Vite app<br/>[App.tsx]"]
  node_api_client["API client<br/>HTTP client<br/>[apiClient.ts]"]
  node_stream_hook["Stream hook<br/>SSE client<br/>[useAgentStream.ts]"]
  node_chat_page["Chat page<br/>Conversation UI<br/>[ChatPage.tsx]"]
  node_search_view["Search view<br/>Search UI"]
  node_seller_view["Seller view<br/>Seller UI"]
end

subgraph group_runtime["Runtime"]
  node_qdrant_data[("Qdrant store<br/>Vector storage")]
end

node_main -->|"mounts"| node_routes
node_main -->|"includes"| node_auth_router
node_routes -->|"streams"| node_agent_stream
node_routes -->|"search"| node_search_pipeline
node_routes -->|"seller"| node_seller_pipeline
node_routes -->|"guards"| node_auth_router
node_agent_stream -->|"delegates"| node_agent_exec
node_agent_exec -->|"plans"| node_planner
node_agent_exec -->|"tracks"| node_memory
node_agent_exec -->|"uses"| node_tool_registry
node_tool_registry -->|"invokes"| node_mcp_core
node_mcp_core -->|"automates"| node_playwright_server
node_mcp_core -->|"fetches"| node_ebay_service
node_mcp_core -->|"retrieves"| node_rag_store
node_search_pipeline -->|"queries"| node_ebay_service
node_search_pipeline -->|"enriches"| node_rag_store
node_seller_pipeline -->|"analyzes"| node_ebay_service
node_seller_pipeline -->|"augments"| node_rag_store
node_nlp_llm -->|"parses intent"| node_search_pipeline
node_nlp_llm -->|"supports"| node_agent_exec
node_db_main -->|"stores"| node_models_user
node_db_main -->|"stores"| node_models_listing
node_ui_app -->|"contains"| node_api_client
node_ui_app -->|"contains"| node_stream_hook
node_stream_hook -->|"consumes"| node_agent_stream
node_chat_page -->|"renders"| node_stream_hook
node_search_view -->|"requests"| node_api_client
node_seller_view -->|"requests"| node_api_client
node_rag_store -->|"persists"| node_qdrant_data

click node_main "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/main.py"
click node_routes "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/api/routes.py"
click node_agent_stream "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/api/agent_stream.py"
click node_auth_router "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/auth/auth_router.py"
click node_agent_exec "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/agent_executor.py"
click node_planner "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/agent/planner.py"
click node_memory "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/agent/memory.py"
click node_tool_registry "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/agent/tool_registry.py"
click node_mcp_core "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/mcp/core.py"
click node_playwright_server "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/mcp/playwright_server.py"
click node_search_pipeline "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/search_pipeline.py"
click node_seller_pipeline "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/seller_pipeline.py"
click node_ebay_service "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/ebay.py"
click node_rag_store "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/rag/qdrant_store.py"
click node_nlp_llm "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/parser.py"
click node_models_user "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/models/user.py"
click node_models_listing "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/models/listing.py"
click node_db_main "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/db/database.py"
click node_ui_app "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/App.tsx"
click node_api_client "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/api/apiClient.ts"
click node_stream_hook "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/agent/hooks/useAgentStream.ts"
click node_chat_page "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/chat/ChatPage.tsx"
click node_search_view "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/search/components/SearchResultList.tsx"
click node_seller_view "https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/seller/component/SellerTrustGauge.tsx"
click node_qdrant_data "https://github.com/paolopangallo/mcp_e-commerce/tree/Paolo_minimax2.7/qdrant_storage/collections/ecommerce_rag/0"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_routes,node_agent_stream,node_auth_router,node_agent_exec,node_planner,node_memory,node_tool_registry,node_mcp_core,node_playwright_server,node_search_pipeline,node_seller_pipeline,node_ebay_service,node_rag_store,node_nlp_llm,node_models_user,node_models_listing,node_db_main toneBlue
class node_ui_app,node_api_client,node_stream_hook,node_chat_page,node_search_view,node_seller_view toneAmber
class node_qdrant_data toneMint
```

## Components

### Backend

FastAPI application, agent orchestration, domain services, and persistence

- [App entry](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/main.py): FastAPI bootstrap · Starts the backend and mounts the API surface. · `app/main.py`
- [API routes](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/api/routes.py): HTTP router · Primary backend routing for search, seller, wishlist, and agent stream. · `app/api/routes.py`
- [Agent stream](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/api/agent_stream.py): SSE endpoint · Streams reasoning steps and tool events to the client. · `app/api/agent_stream.py`
- [Auth router](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/auth/auth_router.py): JWT HTTP · Login and auth-related request handling. · `app/auth/auth_router.py`
- [Agent executor](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/agent_executor.py): Orchestration service · Bridges API requests to agent execution and streaming behavior. · `app/services/agent_executor.py`
- [Planner](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/agent/planner.py): Task planning · Breaks user intent into actionable steps for the shopping agent. · `app/agent/planner.py`
- [Agent memory](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/agent/memory.py): Context state · Maintains short-term conversation and execution context. · `app/agent/memory.py`
- [Tool registry](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/agent/tool_registry.py): Tool binding · Exposes callable tools to the agent in a controlled way. · `app/agent/tool_registry.py`
- [MCP core](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/mcp/core.py): Tool runtime · Standardized tool execution boundary and server/client coordination. · `app/mcp/core.py`
- [Playwright server](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/mcp/playwright_server.py): Browser automation · Browser-backed automation path for page interactions and contact flows. · `app/mcp/playwright_server.py`
- [Search pipeline](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/search_pipeline.py): Ranking pipeline · Query parsing, candidate retrieval, and result ranking for product search. · `app/services/search_pipeline.py`
- [Seller pipeline](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/seller_pipeline.py): Seller intelligence · Builds seller trust, feedback, and profile insights. · `app/services/seller_pipeline.py`
- [eBay service](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/ebay.py): Marketplace adapter · Fetches live marketplace data and normalizes listings and item details. · `app/services/ebay.py`
- [RAG store](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/rag/qdrant_store.py): Retrieval stack · Retrieval, embeddings, reranking, and Qdrant-backed context assembly. · `app/services/rag/qdrant_store.py`
- [NLP + LLM](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/services/parser.py): Text understanding · NER, sentiment, parsing, and multimodal LLM helpers. · `app/services/parser.py`
- [User model](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/models/user.py): SQLAlchemy model · Persistent user and preference data. · `app/models/user.py`
- [Listing model](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/models/listing.py): SQLAlchemy model · Persistent marketplace listing data. · `app/models/listing.py`
- [DB layer](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/app/db/database.py): Postgres + Redis · Database and cache access used by the backend services. · `app/db/database.py`

### Frontend

React/Vite UI organized by shopping features

- [UI shell](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/App.tsx): React/Vite app · Main browser application and theme wiring. · `ebay-ui/src/App.tsx`
- [API client](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/api/apiClient.ts): HTTP client · Frontend request layer for backend APIs. · `ebay-ui/src/api/apiClient.ts`
- [Stream hook](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/agent/hooks/useAgentStream.ts): SSE client · Consumes streamed agent updates and maps them into UI state. · `ebay-ui/src/features/agent/hooks/useAgentStream.ts`
- [Chat page](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/chat/ChatPage.tsx): Conversation UI · Primary chat-driven shopping experience and result rendering. · `ebay-ui/src/features/chat/ChatPage.tsx`
- [Search view](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/search/components/SearchResultList.tsx): Search UI · Search results, comparisons, filters, and deal displays. · `ebay-ui/src/features/search/components/SearchResultList.tsx`
- [Seller view](https://github.com/paolopangallo/mcp_e-commerce/blob/Paolo_minimax2.7/ebay-ui/src/features/seller/component/SellerTrustGauge.tsx): Seller UI · Seller trust, feedback, and summary panels. · `ebay-ui/src/features/seller/component/SellerTrustGauge.tsx`

### Runtime

Local datastores and persisted retrieval artifacts

- [Qdrant store](https://github.com/paolopangallo/mcp_e-commerce/tree/Paolo_minimax2.7/qdrant_storage/collections/ecommerce_rag/0): Vector storage · Persisted retrieval collection used by the RAG subsystem. · `qdrant_storage/collections/ecommerce_rag/0`

## Connections

- App entry → API routes: mounts · Bootstraps the HTTP API surface.
- App entry → Auth router: includes · Registers authentication endpoints.
- API routes → Agent stream: streams · Exposes the chat/agent SSE endpoint.
- API routes → Search pipeline: search · Serves classic product search requests.
- API routes → Seller pipeline: seller · Serves seller analysis endpoints.
- API routes → Auth router: guards · Applies authentication and user context.
- Agent stream → Agent executor: delegates · Hands off streamed requests to the executor.
- Agent executor → Planner: plans · Decomposes user intent into steps.
- Agent executor → Agent memory: tracks · Reads and updates short-term context.
- Agent executor → Tool registry: uses · Resolves the callable tool surface.
- Tool registry → MCP core: invokes · Routes tool calls through the standardized execution boundary.
- MCP core → Playwright server: automates · Uses browser automation for page-backed operations.
- MCP core → eBay service: fetches · Pulls marketplace data and item details.
- MCP core → RAG store: retrieves · Adds semantic context and ranking evidence.
- Search pipeline → eBay service: queries · Pulls live marketplace data for search.
- Search pipeline → RAG store: enriches · Uses retrieval and ranking context.
- Seller pipeline → eBay service: analyzes · Builds seller intelligence from marketplace data.
- Seller pipeline → RAG store: augments · Uses retrieved feedback and context signals.
- NLP + LLM → Search pipeline: parses intent · Converts free-form requests into structured search input.
- NLP + LLM → Agent executor: supports · Feeds reasoning and explanation generation.
- DB layer → User model: stores · Persists user accounts and preferences.
- DB layer → Listing model: stores · Persists marketplace listing records.
- UI shell → API client: contains · Hosts the API integration layer.
- UI shell → Stream hook: contains · Hosts the streaming chat integration.
- Stream hook → Agent stream: consumes · Consumes backend SSE events.
- Chat page → Stream hook: renders · Displays thinking stages and streamed results.
- Search view → API client: requests · Loads search and comparison data.
- Seller view → API client: requests · Loads seller intelligence data.
- RAG store → Qdrant store: persists · Stores and reads vector retrieval state.
