# edward97y/agent-marketplace architecture

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

- Interactive diagram: https://gitdiagram.com/edward97y/agent-marketplace
- Repository: https://github.com/edward97y/agent-marketplace
- Video tour (about a minute): https://gitdiagram.com/edward97y/agent-marketplace/video

## Overview

Agent Marketplace is an agent-driven marketplace scaffold with a sales-chat runtime, tenant-aware order/product operations, and document-backed RAG. The apparent user workflow is an API request entering the sales agent, which can invoke search, order-action, or knowledge-search tools; separate API routes manage conversations and knowledge documents. The README describes setup rather than application behavior, so workflow details here rely on sampled source and the source index; unsampled route and agent internals limit some connections.

Main entry points: [`src/services/db_services/document_service.py`](https://github.com/edward97y/agent-marketplace/blob/main/src/services/db_services/document_service.py) (Document Service), [`src/agent/context/context.py`](https://github.com/edward97y/agent-marketplace/blob/main/src/agent/context/context.py) (Agent Context), [`src/main.py`](https://github.com/edward97y/agent-marketplace/blob/main/src/main.py) (Application Entry), [`src/services/rag_service.py`](https://github.com/edward97y/agent-marketplace/blob/main/src/services/rag_service.py) (Hybrid RAG Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Conversations"]
  node_app["Application Entry<br/>[main.py]"]
  node_routes["API Routes"]
  node_conversation["Conversation API<br/>[conversation.py]"]
  node_document_api["Document API<br/>[document.py]"]
  node_conversation_service["Conversation Service"]
end

subgraph group_agent["Sales Agent"]
  node_sales_agent["Sales Agent<br/>[sales_agent.py]"]
  node_chat_node["Chat Node<br/>[chat.py]"]
  node_llm_tools["LLM and Tools<br/>[llm.py]"]
  node_agent_context["Agent Context<br/>[context.py]"]
  node_sales_prompt["Sales Prompt<br/>[sales_prompt.py]"]
end

subgraph group_market["Marketplace Operations"]
  node_search_tools["Search Tools"]
  node_action_tools["Order Tools"]
  node_query_service["Marketplace Queries<br/>[query_service.py]"]
  node_actions_service["Order Actions<br/>[actions_service.py]"]
  node_schema_mapping["Schema Mapping"]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_document_service["Document Service"]
  node_knowledge_api["Knowledge Base API<br/>[knowledge_base.py]"]
  node_document_processing["Document Processing"]
  node_embedding["Embedding Service"]
  node_rag_tool["RAG Search Tool<br/>[rag_search.py]"]
  node_rag_service["Hybrid RAG Search<br/>[rag_service.py]"]
  node_rag_repo["RAG Repository<br/>[rag_repo.py]"]
end

subgraph group_platform["Persistence and Tenancy"]
  node_company_db["Tenant DB Maker"]
  node_tool_calls["Tool Call Records"]
  node_database[("Application Database<br/>[database.py]")]
  node_models["Data Models"]
  node_config["Configuration<br/>[config.py]"]
end

node_client(("API Client"))

node_client -.->|"sends requests"| node_app
node_app -->|"registers routes"| node_routes
node_app -->|"initializes"| node_sales_agent
node_app -->|"initializes"| node_company_db
node_app -->|"uses"| node_database
node_conversation -->|"delegates to"| node_conversation_service
node_document_api -->|"delegates to"| node_document_service
node_sales_agent -->|"uses"| node_chat_node
node_sales_agent -->|"uses"| node_llm_tools
node_llm_tools -->|"registers tools"| node_search_tools
node_llm_tools -->|"registers tools"| node_action_tools
node_llm_tools -->|"registers tool"| node_rag_tool
node_agent_context -->|"uses"| node_query_service
node_agent_context -->|"uses"| node_actions_service
node_agent_context -->|"uses"| node_rag_service
node_search_tools -->|"accesses context"| node_agent_context
node_action_tools -->|"accesses context"| node_agent_context
node_rag_tool -->|"accesses context"| node_agent_context
node_query_service -->|"gets mappings"| node_schema_mapping
node_query_service -->|"opens tenant session"| node_company_db
node_query_service -->|"records searches"| node_tool_calls
node_actions_service -->|"uses mappings"| node_schema_mapping
node_actions_service -->|"uses tenant database"| node_company_db
node_actions_service -->|"records actions"| node_tool_calls
node_document_service -->|"extracts and splits"| node_document_processing
node_document_service -->|"embeds chunks"| node_embedding
node_document_service -->|"stores chunks"| node_rag_repo
node_rag_tool -->|"invokes search"| node_rag_service
node_rag_service -->|"embeds query"| node_embedding
node_rag_service -->|"runs hybrid search"| node_rag_repo
node_rag_service -->|"records search"| node_tool_calls
node_conversation_service -->|"accesses data"| node_database
node_document_service -->|"persists documents"| node_database
node_rag_repo -->|"queries and writes"| node_database
node_database -->|"loads settings"| node_config
node_document_service -->|"uses document models"| node_models
node_rag_repo -->|"queries chunk models"| node_models
node_knowledge_api -.->|"manages knowledge"| node_document_service
node_sales_agent -.->|"uses prompt"| node_sales_prompt

click node_app "https://github.com/edward97y/agent-marketplace/blob/main/src/main.py"
click node_routes "https://github.com/edward97y/agent-marketplace/tree/main/src/routes"
click node_conversation "https://github.com/edward97y/agent-marketplace/blob/main/src/routes/conversation.py"
click node_document_api "https://github.com/edward97y/agent-marketplace/blob/main/src/routes/document.py"
click node_conversation_service "https://github.com/edward97y/agent-marketplace/blob/main/src/services/db_services/conversation_service.py"
click node_document_service "https://github.com/edward97y/agent-marketplace/blob/main/src/services/db_services/document_service.py"
click node_sales_agent "https://github.com/edward97y/agent-marketplace/blob/main/src/agent/sales_agent.py"
click node_chat_node "https://github.com/edward97y/agent-marketplace/blob/main/src/agent/nodes/sales/chat.py"
click node_llm_tools "https://github.com/edward97y/agent-marketplace/blob/main/src/agent/llm.py"
click node_agent_context "https://github.com/edward97y/agent-marketplace/blob/main/src/agent/context/context.py"
click node_sales_prompt "https://github.com/edward97y/agent-marketplace/blob/main/src/agent/prompt/sales_prompt.py"
click node_search_tools "https://github.com/edward97y/agent-marketplace/tree/main/src/agent/tools/search_tools"
click node_action_tools "https://github.com/edward97y/agent-marketplace/tree/main/src/agent/tools/action_tools"
click node_query_service "https://github.com/edward97y/agent-marketplace/blob/main/src/services/query_service.py"
click node_actions_service "https://github.com/edward97y/agent-marketplace/blob/main/src/services/actions_service.py"
click node_schema_mapping "https://github.com/edward97y/agent-marketplace/blob/main/src/services/schema_mapping_service.py"
click node_company_db "https://github.com/edward97y/agent-marketplace/blob/main/src/services/company_db_maker_service.py"
click node_tool_calls "https://github.com/edward97y/agent-marketplace/blob/main/src/services/db_services/tool_calls_service.py"
click node_knowledge_api "https://github.com/edward97y/agent-marketplace/blob/main/src/routes/knowledge_base.py"
click node_document_processing "https://github.com/edward97y/agent-marketplace/blob/main/src/services/document_processing_service.py"
click node_embedding "https://github.com/edward97y/agent-marketplace/blob/main/src/services/embedding_service.py"
click node_rag_tool "https://github.com/edward97y/agent-marketplace/blob/main/src/agent/tools/rag_tools/rag_search.py"
click node_rag_service "https://github.com/edward97y/agent-marketplace/blob/main/src/services/rag_service.py"
click node_rag_repo "https://github.com/edward97y/agent-marketplace/blob/main/src/repository/rag_repo.py"
click node_database "https://github.com/edward97y/agent-marketplace/blob/main/src/db/database.py"
click node_models "https://github.com/edward97y/agent-marketplace/tree/main/src/models"
click node_config "https://github.com/edward97y/agent-marketplace/blob/main/src/helpers/config.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_app,node_routes,node_conversation,node_document_api,node_conversation_service,node_client toneBlue
class node_sales_agent,node_chat_node,node_llm_tools,node_agent_context,node_sales_prompt toneAmber
class node_search_tools,node_action_tools,node_query_service,node_actions_service,node_schema_mapping toneMint
class node_document_service,node_knowledge_api,node_document_processing,node_embedding,node_rag_tool,node_rag_service,node_rag_repo toneRose
class node_company_db,node_tool_calls,node_database,node_models,node_config toneIndigo
```

## Components

### API and Conversations

- [Application Entry](https://github.com/edward97y/agent-marketplace/blob/main/src/main.py): `src/main.py`
- [API Routes](https://github.com/edward97y/agent-marketplace/tree/main/src/routes): `src/routes`
- [Conversation API](https://github.com/edward97y/agent-marketplace/blob/main/src/routes/conversation.py): `src/routes/conversation.py`
- [Document API](https://github.com/edward97y/agent-marketplace/blob/main/src/routes/document.py): `src/routes/document.py`
- [Conversation Service](https://github.com/edward97y/agent-marketplace/blob/main/src/services/db_services/conversation_service.py): `src/services/db_services/conversation_service.py`

### Sales Agent

- [Sales Agent](https://github.com/edward97y/agent-marketplace/blob/main/src/agent/sales_agent.py): `src/agent/sales_agent.py`
- [Chat Node](https://github.com/edward97y/agent-marketplace/blob/main/src/agent/nodes/sales/chat.py): `src/agent/nodes/sales/chat.py`
- [LLM and Tools](https://github.com/edward97y/agent-marketplace/blob/main/src/agent/llm.py): `src/agent/llm.py`
- [Agent Context](https://github.com/edward97y/agent-marketplace/blob/main/src/agent/context/context.py): `src/agent/context/context.py`
- [Sales Prompt](https://github.com/edward97y/agent-marketplace/blob/main/src/agent/prompt/sales_prompt.py): `src/agent/prompt/sales_prompt.py`

### Marketplace Operations

- [Search Tools](https://github.com/edward97y/agent-marketplace/tree/main/src/agent/tools/search_tools): `src/agent/tools/search_tools`
- [Order Tools](https://github.com/edward97y/agent-marketplace/tree/main/src/agent/tools/action_tools): `src/agent/tools/action_tools`
- [Marketplace Queries](https://github.com/edward97y/agent-marketplace/blob/main/src/services/query_service.py): `src/services/query_service.py`
- [Order Actions](https://github.com/edward97y/agent-marketplace/blob/main/src/services/actions_service.py): `src/services/actions_service.py`
- [Schema Mapping](https://github.com/edward97y/agent-marketplace/blob/main/src/services/schema_mapping_service.py): `src/services/schema_mapping_service.py`

### Knowledge Retrieval

- [Document Service](https://github.com/edward97y/agent-marketplace/blob/main/src/services/db_services/document_service.py): `src/services/db_services/document_service.py`
- [Knowledge Base API](https://github.com/edward97y/agent-marketplace/blob/main/src/routes/knowledge_base.py): `src/routes/knowledge_base.py`
- [Document Processing](https://github.com/edward97y/agent-marketplace/blob/main/src/services/document_processing_service.py): `src/services/document_processing_service.py`
- [Embedding Service](https://github.com/edward97y/agent-marketplace/blob/main/src/services/embedding_service.py): `src/services/embedding_service.py`
- [RAG Search Tool](https://github.com/edward97y/agent-marketplace/blob/main/src/agent/tools/rag_tools/rag_search.py): `src/agent/tools/rag_tools/rag_search.py`
- [Hybrid RAG Search](https://github.com/edward97y/agent-marketplace/blob/main/src/services/rag_service.py): `src/services/rag_service.py`
- [RAG Repository](https://github.com/edward97y/agent-marketplace/blob/main/src/repository/rag_repo.py): `src/repository/rag_repo.py`

### Persistence and Tenancy

- [Tenant DB Maker](https://github.com/edward97y/agent-marketplace/blob/main/src/services/company_db_maker_service.py): `src/services/company_db_maker_service.py`
- [Tool Call Records](https://github.com/edward97y/agent-marketplace/blob/main/src/services/db_services/tool_calls_service.py): `src/services/db_services/tool_calls_service.py`
- [Application Database](https://github.com/edward97y/agent-marketplace/blob/main/src/db/database.py): `src/db/database.py`
- [Data Models](https://github.com/edward97y/agent-marketplace/tree/main/src/models): `src/models`
- [Configuration](https://github.com/edward97y/agent-marketplace/blob/main/src/helpers/config.py): `src/helpers/config.py`

### Other components

- **API Client**

## Connections

- API Client → Application Entry: sends requests
- Application Entry → API Routes: registers routes (evidence: `src/main.py`)
- Application Entry → Sales Agent: initializes (evidence: `src/main.py`)
- Application Entry → Tenant DB Maker: initializes (evidence: `src/main.py`)
- Application Entry → Application Database: uses (evidence: `src/main.py`)
- Conversation API → Conversation Service: delegates to (evidence: `src/routes/conversation.py`)
- Document API → Document Service: delegates to (evidence: `src/routes/document.py`)
- Sales Agent → Chat Node: uses (evidence: `src/agent/sales_agent.py`)
- Sales Agent → LLM and Tools: uses (evidence: `src/agent/sales_agent.py`)
- LLM and Tools → Search Tools: registers tools (evidence: `src/agent/llm.py`)
- LLM and Tools → Order Tools: registers tools (evidence: `src/agent/llm.py`)
- LLM and Tools → RAG Search Tool: registers tool (evidence: `src/agent/llm.py`)
- Agent Context → Marketplace Queries: uses (evidence: `src/agent/context/context.py`)
- Agent Context → Order Actions: uses (evidence: `src/agent/context/context.py`)
- Agent Context → Hybrid RAG Search: uses (evidence: `src/agent/context/context.py`)
- Search Tools → Agent Context: accesses context (evidence: `src/agent/tools/search_tools/search_products.py`)
- Order Tools → Agent Context: accesses context (evidence: `src/agent/tools/action_tools/create_order.py`)
- RAG Search Tool → Agent Context: accesses context (evidence: `src/agent/tools/rag_tools/rag_search.py`)
- Marketplace Queries → Schema Mapping: gets mappings (evidence: `src/services/query_service.py`)
- Marketplace Queries → Tenant DB Maker: opens tenant session (evidence: `src/services/query_service.py`)
- Marketplace Queries → Tool Call Records: records searches (evidence: `src/services/query_service.py`)
- Order Actions → Schema Mapping: uses mappings (evidence: `src/services/actions_service.py`)
- Order Actions → Tenant DB Maker: uses tenant database (evidence: `src/services/actions_service.py`)
- Order Actions → Tool Call Records: records actions (evidence: `src/services/actions_service.py`)
- Document Service → Document Processing: extracts and splits (evidence: `src/services/db_services/document_service.py`)
- Document Service → Embedding Service: embeds chunks (evidence: `src/services/db_services/document_service.py`)
- Document Service → RAG Repository: stores chunks (evidence: `src/services/db_services/document_service.py`)
- RAG Search Tool → Hybrid RAG Search: invokes search (evidence: `src/agent/tools/rag_tools/rag_search.py`)
- Hybrid RAG Search → Embedding Service: embeds query (evidence: `src/services/rag_service.py`)
- Hybrid RAG Search → RAG Repository: runs hybrid search (evidence: `src/services/rag_service.py`)
- Hybrid RAG Search → Tool Call Records: records search (evidence: `src/services/rag_service.py`)
- Conversation Service → Application Database: accesses data (evidence: `src/services/db_services/conversation_service.py`)
- Document Service → Application Database: persists documents (evidence: `src/services/db_services/document_service.py`)
- RAG Repository → Application Database: queries and writes (evidence: `src/repository/rag_repo.py`)
- Application Database → Configuration: loads settings (evidence: `src/db/database.py`)
- Document Service → Data Models: uses document models (evidence: `src/services/db_services/document_service.py`)
- RAG Repository → Data Models: queries chunk models (evidence: `src/repository/rag_repo.py`)
- Knowledge Base API → Document Service: manages knowledge
- Sales Agent → Sales Prompt: uses prompt
