flowchart TD
    User([👤 Người dùng]) <-->|REST API / Chat| Host[🌐 Chat Host / FastAPI]
    
    subgraph ChatHostApp ["Chat Host (Orchestrator)"]
        Host <--> Agent["🤖 ReAct Agent Loop"]
        Agent <--> LLM["🧠 LLM (Groq / OpenAI)"]
        Agent <--> HITL["🛡️ Human-in-the-loop Gate"]
        Agent <--> MCPClient["🔌 MCP Client"]
    end

    subgraph MCPServerApp ["MCP Server (StockPilot)"]
        MCPClient <==>|MCP Protocol| MCPServer["⚙️ FastMCP Server"]
        MCPServer --> ReadTools["📖 Read Tools (find, get_stock, alert)"]
        MCPServer --> WriteTools["✍️ Write Tools (receive, issue, add)"]
        ReadTools & WriteTools --> DBModule["💾 DB Layer (asyncpg)"]
    end

    DBModule <==>|Connection Pool| Postgres[(🐘 PostgreSQL)]

stockpilot/
├── 📄 compose.yaml             # Docker Compose cho PostgreSQL & pgAdmin
├── 📄 Dockerfile               # Dockerfile cho Chat Host
├── 📄 requirements.txt         # Dependencies
├── 📄 .env.example             # Mẫu cấu hình biến môi trường
├── 📁 db/init.sql              # Schema Database & Index
├── 📁 scripts/seed_products.py # Nạp dữ liệu mẫu
├── 📁 src/
│   ├── 📁 mcp_server/          # FastMCP Server, Database & Tools
│   └── 📁 chat_host/           # FastAPI Host, ReAct Agent & HITL Confirmation
└── 📁 tests/                   # Test suite (Unit, Integration)

# Clone repo & cấu hình .env
git clone https://github.com/tutran27/stockpilot-mcp.git
cd stockpilot-mcp
cp .env.example .env   # Điền GROQ_API_KEY hoặc OPENAI_API_KEY

# Khởi động PostgreSQL qua Docker
docker compose up -d

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Nạp dữ liệu sản phẩm mẫu vào DB
python scripts/seed_products.py

docker compose up -d

{
  "message": "Tôi muốn nhập 10 cái Laptop Dell XPS 13 từ NCC FPT, số HĐ: FPT-1234."
}

⚠️ Thao tác `receive_stock` cần bạn xác nhận trước khi thực hiện.
Mã hành động: `e70ce90c-575f-4462-81ae-672a29b26fdc`
Chi tiết: {'product_id': '...', 'quantity': 10, 'partner': 'FPT'}

{
  "action_id": "e70ce90c-575f-4462-81ae-672a29b26fdc"
}