Content
# 📋 README_MASTER — AI Enterprise Co-Worker Portal
> **System Architecture Documentation — Automatically generated from source code**
> Created: 2026-04-26 | Version: v3.0 (Enterprise Edition)
---
## 1. System Overview & Visual Flow
**What is this system?**
This is an **AI Co-Worker Enterprise Portal** designed to automate high-stakes business processes (Accounting and HR) using an Agentic Workflow. It combines deterministic Rule Engines with Large Language Models (LLMs) via the **Model Context Protocol (MCP)**.
### 🔄 System Architecture Flow
| # | Module | Core Logic | Deployment |
|---|--------|------------|------------|
| 1 | **MISA Accounting Agent** | 2-Stage Pipeline (Rule Engine + LLM) | Port 8000 |
| 2 | **HR Payroll OT Agent** | SOTA Math Split + AI Reason Tagging | Port 8001 |
| 3 | **Enterprise Portal** | Unified UI Dashboard & Monitoring | Port 8501 |
## 🛠 Technology Stack
This project leverages a cutting-edge AI stack to ensure high performance, scalability, and deterministic reasoning.
- **Agentic Orchestration**: [LangGraph](https://github.com/langchain-ai/langgraph) (Deterministic DAG & Cyclic Workflows)
- **LLM Communication**: [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) (Anthropic standard for tool/resource abstraction)
- **AI Models**: Google Gemini 1.5 Pro/Flash (Primary), OpenAI GPT-4o-mini (Fallback), Qwen 2.5 7B (Local/Colab)
- **Backend Framework**: FastAPI (Async high-performance API)
- **Frontend Interface**: Streamlit (Enterprise Dashboard with Glassmorphism UI)
- **Data Engineering**: Pandas & OpenPyXL (Complex Excel transformation logic)
- **Database & Persistence**: PostgreSQL (Supabase/Docker) & Cachetools (TTL Caching)
- **Infrastructure**: Docker & Docker Compose, GitHub Actions (CI/CD Automated Sync)
---
## 2. Business Modules (Mind Maps)
The following diagrams illustrate the internal reasoning and tool selection logic for each specialized agent.
### 🏢 MISA Accounting Agent
- **Goal**: Reclassify Workday journal entries into MISA SME format.
- **Strategy**: Uses **Sub-group Splitting** by Supplier key to reduce AI token costs by 90%.
### 🕒 HR Payroll OT Agent
- **Goal**: Calculate overtime buckets based on Vietnam Labor Law.
- **Strategy**: Uses an **Intersection Algorithm** with MCP Calendar integration.
---
## 3. Project Structure
```
MCP-business-process-agent-/
│
├── start.py # 🚀 Entry Point — Orchestrates all 3 services
├── PROJECT_EVALUATION_REPORT.md # 📊 System Performance & Metrics (English)
├── run_and_setup.md # 🚀 Full Setup & Operation Guide (English)
│
├── misa_agent_project/ # === MODULE 1: MISA ACCOUNTING ===
│ └── backend/
│ ├── main_api.py # FastAPI: Stage 1 (Rule) & Stage 2 (LLM)
│ └── src/graph/builder.py # LangGraph DAG
│
├── hr_payroll_project/ # === MODULE 2: HR PAYROLL ===
│ └── backend/
│ ├── main_api.py # FastAPI: /api/v2/process-payroll
│ └── src/tools/time_tools.py # SOTA Hour Splitting Logic
│
├── mcp_servers/ # === MCP SERVERS (Microservices) ===
│ ├── misa_mcp_server.py # COA Database & System Prompts
│ └── calendar_mcp.py # Vietnam Holiday Context
│
├── frontend/ # === UNIFIED UI PORTAL ===
│ └── app.py # Streamlit Multi-stage Dashboard
│
└── test/ # === VALIDATION SUITE ===
└── ab_test_runner.py # Performance Comparison Framework
```
---
## 4. Performance & Maturity (Key Metrics)
The system has been rigorously tested against real-world datasets. For the full technical breakdown, see the [PROJECT_EVALUATION_REPORT.md](PROJECT_EVALUATION_REPORT.md).
| Metric | MISA Agent | Payroll Agent | Measurement |
| :--- | :--- | :--- | :--- |
| **Success Rate** | **96.0%** | **100%** | Task completion without errors. |
| **Efficiency Gain** | **65x** | **SOTA** | Vs. manual data entry. |
| **Reliability** | **100%** | **100%** | 0 failures over 100 stress test requests. |
| **Context Usage** | **100%** | **100%** | Accurate MCP resource retrieval. |
---
## 5. Quick Start & Operation
A single command launches the entire ecosystem. For detailed prerequisites, see the [run_and_setup.md](run_and_setup.md).
### ⚡ Installation
```bash
conda create -n mcp-business python=3.11 -y
conda activate mcp-business
pip install -r requirements.txt
cp .env.example .env # Fill in your API keys
docker compose up -d # Start Database
```
### ⚡ Execution
```bash
python start.py
```
- **Access UI**: http://localhost:8501
- **API Health**: http://localhost:8000/health
---
## 6. Advanced Features
- **Multi-LLM Fallback**: Automatic redirection from Local/Colab models to Cloud APIs (Gemini/OpenAI) if latency or availability thresholds are breached.
- **Sub-Agent Routing**: Intelligent classification of incoming files via `classifier_mcp` ensures data is sent to the correct specialized pipeline.
- **Deterministic Math Engine**: Payroll calculations are 100% mathematical, ensuring compliance with labor regulations while using AI only for qualitative reason tagging.
---
*Document Version 3.0 | Maintained by AI System Architect | 2026-04-26*
