flowchart TD
    subgraph ClientLayer ["1. Lớp Giao diện & Người dùng"]
        User([👤 Người dùng]) <-->|Web UI| Streamlit["💻 Streamlit Web App (tutran27-stockpilot-mcp)"]
    end

    subgraph HostLayer ["2. Lớp Điều phối (Chat Host / FastAPI)"]
        Streamlit <-->|REST API / JSON| Host["🌐 FastAPI Host (Railway)"]
        Host <--> Agent["🤖 ReAct Agent Loop"]
        Agent <--> LLM["🧠 LLM (Groq / OpenAI)"]
        Agent <--> Memory["🧠 Working State & Session Memory"]
        Agent <--> HITL["🛡️ Human-in-the-loop Gate"]
        Agent <--> MCPClient["🔌 MCP Client"]
    end

    subgraph ServerLayer ["3. Lớp Giao thức MCP (FastMCP Server)"]
        MCPClient <==>|MCP Protocol| MCPServer["⚙️ FastMCP Server"]
        MCPServer --> ReadTools["📖 Read Tools (find, get_stock, alert)"]
        MCPServer --> WriteTools["✍️ Write Tools (receive, issue, add)"]
        MCPServer --> Resources["📊 Resources (summary, policy)"]
        MCPServer --> Prompts["📝 Prompts (audit, restock)"]
    end

    subgraph DBLayer ["4. Lớp Dữ liệu (Supabase Cloud Database)"]
        ReadTools & WriteTools & Memory --> DBModule["💾 asyncpg Pool (statement_cache_size=0)"]
        DBModule <==>|PgBouncer Pooler| Postgres[(🐘 Supabase PostgreSQL 17)]
    end

stockpilot/
├── 📄 compose.yaml             # Cấu hình Docker Compose chuẩn Production
├── 📄 Dockerfile               # Đóng gói Chat Host & MCP Server
├── 📄 requirements.txt         # Danh mục thư viện phụ thuộc
├── 📄 .env.example             # File mẫu biến môi trường
├── 📁 db/
│   └── 📄 init.sql             # Khởi tạo Schema DB, Indexes và ràng buộc FK
├── 📁 scripts/
│   └── 📄 seed_products.py     # Nạp dữ liệu sản phẩm mẫu
├── 📁 src/
│   ├── 📁 chat_host/           # Chat Host Orchestrator
│   │   ├── 📄 main.py          # FastAPI Endpoints (/api/chat, /confirm, /cancel)
│   │   ├── 📄 agent.py         # Vòng lặp Agent ReAct & MCP Tool Routing
│   │   ├── 📄 memory.py        # Bộ nhớ Working State & Ánh xạ thực thể
│   │   ├── 📄 confirmation.py  # Xử lý Human-in-the-loop (Pending Actions)
│   │   ├── 📄 llm.py           # Kết nối AsyncOpenAI / Groq LLM
│   │   └── 📄 prompts.py       # System Prompts & Working State Injection
│   ├── 📁 mcp_server/          # MCP Server Layer
│   │   ├── 📄 server.py        # Định nghĩa FastMCP Server & Đăng ký Tool/Resource/Prompt
│   │   ├── 📄 db.py            # Thao tác PostgreSQL (asyncpg connection pool)
│   │   ├── 📄 tools_read.py    # MCP Read Tools
│   │   ├── 📄 tools_write.py   # MCP Write Tools
│   │   ├── 📄 resources.py     # MCP Resources
│   │   └── 📄 prompts.py       # MCP Prompts Templates
│   └── 📁 ui/
│       └── 📄 app.py           # Giao diện Web Chat Streamlit

git clone https://github.com/tutran27/stockpilot-mcp.git
cd stockpilot-mcp
cp .env.example .env

docker compose up -d --build