How alwyn25/invoicecoreprocessor works
Project Type and Purpose
• InvoiceCoreProcessor is a distributed, multi-process microservice system that automates invoice entry.
• It uses a central FastAPI/LangGraph “MCP Host” to orchestrate a linear workflow, invoking three standalone gRPC microservices (SchemaMapper, AnomalyAgent, DataStore) to perform schema mapping, anomaly detection, and data persistence.
a. MCP Host (main.py / main_processor.py)
– FastAPI application exposing /upload-invoice endpoint (Swagger UI).
– LangGraph workflow nodes (core/workflow.py) for linear agent orchestration.
– Local OCR fallback logic (services/ocr_processor.py).
– gRPC client stubs (generated/ + mcp_client.py) for talking to MCP Servers.
b. SchemaMapperServer (microservices/mapper/main.py)
– gRPC server implementing schema mapping (mapper.proto).
c. AnomalyAgentServer (microservices/agent/main.py)
– gRPC server for validation & anomaly detection (agent.proto).
d. DataStoreServer (microservices/datastore/main.py)
– gRPC server providing persistence (datastore.proto).
e. Protos & Generated Code
– .proto files under protos/ define service contracts.
– Python stubs under generated/ used by both host (clients) and servers.
f. External Dependencies & Infrastructure
– LangGraph library, Pydantic, gRPC framework, FastAPI, Persistence backend (e.g., SQL/NoSQL DB).
Relationships & Data Flow
1. Client → HTTP upload → MCP Host (FastAPI)
2. Host:
• Pre-workflow: OCR fallback (local call).
• Launch LangGraph workflow → sequential gRPC calls:
a. SchemaMapperServer
b. AnomalyAgentServer
c. DataStoreServer
3. Each microservice → processes request → returns result via gRPC
4. Host aggregates responses → final output → HTTP response to client
5. DataStoreServer persists audit trail to its database
Architectural Patterns & Principles
• Microservices: each server is a standalone process with single responsibility.
• Model-Context Protocol (MCP): orchestrator (Host) drives LLM-based agents via network calls.
• Contract-First Design: all interfaces defined in .proto, auto-generated stubs ensure consistency.
• Separation of Concerns: OCR logic vs workflow vs mapping vs validation vs persistence.
5. Network protocols: HTTP (port 8000), gRPC (e.g., 50051, 50052, 50053).