# mit-007/ecommerce-platform architecture

> Architecture diagram of the GitHub repository mit-007/ecommerce-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mit-007/ecommerce-platform
- Repository: https://github.com/mit-007/ecommerce-platform

## Overview

Buyzaar combines a customer-facing storefront and authenticated commerce REST API with an AI support workflow. Customers use the UI to manage orders, invoices, and tracking or ask for help; the backend can connect the agent to a separate MCP server for commerce tools. The README also documents knowledge-base RAG: documents are chunked, embedded, and searched against PostgreSQL/pgvector. The sampled code confirms app startup, MCP/LLM initialization, and selected REST handlers; unsampled route and tool internals are represented only where the README or tree supports them.

Main entry points: [`app/main.py`](https://github.com/mit-007/ecommerce-platform/blob/main/app/main.py) (REST application), [`server/server.py`](https://github.com/mit-007/ecommerce-platform/blob/main/server/server.py) (MCP server), [`app/agent/graph.py`](https://github.com/mit-007/ecommerce-platform/blob/main/app/agent/graph.py) (Agent workflow), [`app/services/llm_service.py`](https://github.com/mit-007/ecommerce-platform/blob/main/app/services/llm_service.py) (LLM integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Customer interface"]
  node_web["Buyzaar web UI<br/>[main.jsx]"]
end

subgraph group_api["Commerce API"]
  node_api_app["REST application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth_routes.py]"]
  node_orders["Orders and invoices<br/>[order_routes.py]"]
  node_invoice_routes["Invoice operations<br/>[invoice_routes.py]"]
  node_tracking["Tracking operations<br/>[tracking_routes.py]"]
  node_documents["Document operations<br/>[document_routes.py]"]
  node_conversation["Conversation routes"]
  node_support["Support endpoint<br/>[support_route.py]"]
end

subgraph group_agent["AI support"]
  node_agent_graph["Agent workflow<br/>[graph.py]"]
  node_agent_nodes["Agent nodes and state<br/>[nodes.py]"]
  node_llm["LLM integration<br/>[llm_service.py]"]
  node_mcp_client["MCP client<br/>[client.py]"]
end

subgraph group_mcp["MCP capabilities"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_order_tool["Order tools<br/>[order_tool.py]"]
  node_search_tool["Knowledge search<br/>[search_tool.py]"]
  node_ticket_tool["Support ticket tools"]
end

subgraph group_knowledge["Knowledge and storage"]
  node_chunking["Document chunking<br/>[chunking.py]"]
  node_embedding["Embedding generation"]
  node_chunk_store["Chunk storage"]
  node_database[("PostgreSQL and pgvector")]
end

node_customer(("Customer"))
node_gemini["Google Gemini"]

node_customer -->|"uses"| node_web
node_web -->|"calls API"| node_api_app
node_api_app -->|"routes requests"| node_auth
node_api_app -->|"routes requests"| node_orders
node_api_app -->|"routes requests"| node_invoice_routes
node_api_app -->|"routes requests"| node_tracking
node_api_app -->|"routes requests"| node_documents
node_api_app -->|"routes requests"| node_conversation
node_api_app -->|"routes requests"| node_support
node_support -->|"invokes"| node_agent_graph
node_agent_graph -->|"runs nodes"| node_agent_nodes
node_agent_graph -->|"requests reasoning"| node_llm
node_llm -->|"loads tools"| node_mcp_client
node_llm -->|"generates responses"| node_gemini
node_mcp_client -->|"discovers tools"| node_mcp_server
node_mcp_server -->|"registers"| node_order_tool
node_mcp_server -->|"registers"| node_search_tool
node_mcp_server -->|"registers"| node_ticket_tool
node_search_tool -->|"embeds queries"| node_embedding
node_search_tool -->|"searches vectors"| node_database
node_documents -->|"processes documents"| node_chunking
node_chunking -->|"prepares text"| node_embedding
node_embedding -->|"requests embeddings"| node_gemini
node_chunking -->|"stores chunks"| node_chunk_store
node_chunk_store -->|"writes chunks"| node_database
node_order_tool -->|"accesses commerce data"| node_database
node_ticket_tool -->|"accesses tickets"| node_database

click node_web "https://github.com/mit-007/ecommerce-platform/blob/main/frontend/src/main.jsx"
click node_api_app "https://github.com/mit-007/ecommerce-platform/blob/main/app/main.py"
click node_auth "https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/auth_routes.py"
click node_orders "https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/order_routes.py"
click node_invoice_routes "https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/invoice_routes.py"
click node_tracking "https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/tracking_routes.py"
click node_documents "https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/document_routes.py"
click node_conversation "https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/conversation_routes.py"
click node_support "https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/support_route.py"
click node_agent_graph "https://github.com/mit-007/ecommerce-platform/blob/main/app/agent/graph.py"
click node_agent_nodes "https://github.com/mit-007/ecommerce-platform/blob/main/app/agent/nodes.py"
click node_llm "https://github.com/mit-007/ecommerce-platform/blob/main/app/services/llm_service.py"
click node_mcp_client "https://github.com/mit-007/ecommerce-platform/blob/main/app/client/client.py"
click node_mcp_server "https://github.com/mit-007/ecommerce-platform/blob/main/server/server.py"
click node_order_tool "https://github.com/mit-007/ecommerce-platform/blob/main/server/tools/order_tool.py"
click node_search_tool "https://github.com/mit-007/ecommerce-platform/blob/main/server/tools/search_tool.py"
click node_ticket_tool "https://github.com/mit-007/ecommerce-platform/blob/main/server/tools/support_ticket_tool.py"
click node_chunking "https://github.com/mit-007/ecommerce-platform/blob/main/app/services/chunking.py"
click node_embedding "https://github.com/mit-007/ecommerce-platform/blob/main/app/services/embedding_service.py"
click node_chunk_store "https://github.com/mit-007/ecommerce-platform/blob/main/app/services/chunk_store_service.py"

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_web toneBlue
class node_api_app,node_auth,node_orders,node_invoice_routes,node_tracking,node_documents,node_conversation,node_support toneAmber
class node_agent_graph,node_agent_nodes,node_llm,node_mcp_client toneMint
class node_mcp_server,node_order_tool,node_search_tool,node_ticket_tool toneRose
class node_chunking,node_embedding,node_chunk_store,node_database,node_customer,node_gemini toneIndigo
```

## Components

### Customer interface

- [Buyzaar web UI](https://github.com/mit-007/ecommerce-platform/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### Commerce API

- [REST application](https://github.com/mit-007/ecommerce-platform/blob/main/app/main.py): `app/main.py`
- [Authentication](https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/auth_routes.py): `app/routes/auth_routes.py`
- [Orders and invoices](https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/order_routes.py): `app/routes/order_routes.py`
- [Invoice operations](https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/invoice_routes.py): `app/routes/invoice_routes.py`
- [Tracking operations](https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/tracking_routes.py): `app/routes/tracking_routes.py`
- [Document operations](https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/document_routes.py): `app/routes/document_routes.py`
- [Conversation routes](https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/conversation_routes.py): `app/routes/conversation_routes.py`
- [Support endpoint](https://github.com/mit-007/ecommerce-platform/blob/main/app/routes/support_route.py): `app/routes/support_route.py`

### AI support

- [Agent workflow](https://github.com/mit-007/ecommerce-platform/blob/main/app/agent/graph.py): `app/agent/graph.py`
- [Agent nodes and state](https://github.com/mit-007/ecommerce-platform/blob/main/app/agent/nodes.py): `app/agent/nodes.py`
- [LLM integration](https://github.com/mit-007/ecommerce-platform/blob/main/app/services/llm_service.py): `app/services/llm_service.py`
- [MCP client](https://github.com/mit-007/ecommerce-platform/blob/main/app/client/client.py): `app/client/client.py`

### MCP capabilities

- [MCP server](https://github.com/mit-007/ecommerce-platform/blob/main/server/server.py): `server/server.py`
- [Order tools](https://github.com/mit-007/ecommerce-platform/blob/main/server/tools/order_tool.py): `server/tools/order_tool.py`
- [Knowledge search](https://github.com/mit-007/ecommerce-platform/blob/main/server/tools/search_tool.py): `server/tools/search_tool.py`
- [Support ticket tools](https://github.com/mit-007/ecommerce-platform/blob/main/server/tools/support_ticket_tool.py): `server/tools/support_ticket_tool.py`

### Knowledge and storage

- [Document chunking](https://github.com/mit-007/ecommerce-platform/blob/main/app/services/chunking.py): `app/services/chunking.py`
- [Embedding generation](https://github.com/mit-007/ecommerce-platform/blob/main/app/services/embedding_service.py): `app/services/embedding_service.py`
- [Chunk storage](https://github.com/mit-007/ecommerce-platform/blob/main/app/services/chunk_store_service.py): `app/services/chunk_store_service.py`
- **PostgreSQL and pgvector**

### Other components

- **Customer**
- **Google Gemini**

## Connections

- Customer → Buyzaar web UI: uses
- Buyzaar web UI → REST application: calls API
- REST application → Authentication: routes requests
- REST application → Orders and invoices: routes requests
- REST application → Invoice operations: routes requests
- REST application → Tracking operations: routes requests
- REST application → Document operations: routes requests
- REST application → Conversation routes: routes requests
- REST application → Support endpoint: routes requests
- Support endpoint → Agent workflow: invokes
- Agent workflow → Agent nodes and state: runs nodes
- Agent workflow → LLM integration: requests reasoning
- LLM integration → MCP client: loads tools
- LLM integration → Google Gemini: generates responses
- MCP client → MCP server: discovers tools
- MCP server → Order tools: registers
- MCP server → Knowledge search: registers
- MCP server → Support ticket tools: registers
- Knowledge search → Embedding generation: embeds queries
- Knowledge search → PostgreSQL and pgvector: searches vectors
- Document operations → Document chunking: processes documents
- Document chunking → Embedding generation: prepares text
- Embedding generation → Google Gemini: requests embeddings
- Document chunking → Chunk storage: stores chunks
- Chunk storage → PostgreSQL and pgvector: writes chunks
- Order tools → PostgreSQL and pgvector: accesses commerce data
- Support ticket tools → PostgreSQL and pgvector: accesses tickets