# alwyn25/invoicecoreprocessor architecture

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

- Interactive diagram: https://gitdiagram.com/alwyn25/invoicecoreprocessor
- Repository: https://github.com/alwyn25/invoicecoreprocessor

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    Client["External Client"]:::external

    %% MCP Host Layer
    subgraph "MCP Host" 
        direction TB
        HTTPApi["FastAPI HTTP API\n(main.py)"]:::orchestrator
        OCR["Local OCR Fallback\n(services/ocr_processor.py)"]:::orchestrator
        Workflow["LangGraph Workflow\n(core/workflow.py)"]:::orchestrator
        subgraph "gRPC Clients & Stubs"
            direction TB
            MCPClient["mcp_client.py"]:::orchestrator
            GeneratedStubs["generated/"]:::contract
        end
    end

    %% Service Contracts
    subgraph "Service Contracts (Protos)"
        direction TB
        CommonProto["common.proto"]:::contract
        MapperProto["mapper.proto"]:::contract
        AgentProto["agent.proto"]:::contract
        DatastoreProto["datastore.proto"]:::contract
    end

    %% Microservices Layer
    subgraph "Microservices" 
        direction TB
        subgraph "SchemaMapperServer" 
            direction TB
            SM_Main["main.py"]:::microservice
            SM_Proto["mapper.proto"]:::contract
            SM_Stubs["mapper_pb2.py\nmapper_pb2_grpc.py"]:::contract
        end
        subgraph "AnomalyAgentServer"
            direction TB
            AA_Main["main.py"]:::microservice
            AA_Proto["agent.proto"]:::contract
            AA_Stubs["agent_pb2.py\nagent_pb2_grpc.py"]:::contract
        end
        subgraph "DataStoreServer"
            direction TB
            DS_Main["main.py"]:::microservice
            DS_Proto["datastore.proto"]:::contract
            DS_Stubs["datastore_pb2.py\ndatastore_pb2_grpc.py"]:::contract
        end
    end

    %% Database
    DB["Persistence Database"]:::db

    %% Connections
    Client -->|HTTP POST /upload-invoice| HTTPApi
    HTTPApi -->|fallback call| OCR
    HTTPApi -->|start workflow| Workflow

    Workflow -->|gRPC call| SM_Main
    SM_Main -->|returns mapped schema| Workflow
    Workflow -->|gRPC call| AA_Main
    AA_Main -->|returns validation| Workflow
    Workflow -->|gRPC call| DS_Main
    DS_Main -->|persists audit| DB
    DS_Main -->|returns ack| Workflow

    Workflow -->|final response| HTTPApi
    HTTPApi -->|HTTP 200| Client

    %% Contracts connections
    MCPClient -->|uses| CommonProto
    MCPClient -->|uses| MapperProto
    MCPClient -->|uses| AgentProto
    MCPClient -->|uses| DatastoreProto

    SM_Main -->|implements| MapperProto
    SM_Main -->|uses| SM_Stubs
    AA_Main -->|implements| AgentProto
    AA_Main -->|uses| AA_Stubs
    DS_Main -->|implements| DatastoreProto
    DS_Main -->|uses| DS_Stubs

    %% Click Events
    click HTTPApi "https://github.com/alwyn25/invoicecoreprocessor/blob/main/main.py"
    click MCPClient "https://github.com/alwyn25/invoicecoreprocessor/blob/main/mcp_client.py"
    click GeneratedStubs "https://github.com/alwyn25/invoicecoreprocessor/tree/main/generated/"
    click SM_Main "https://github.com/alwyn25/invoicecoreprocessor/blob/main/microservices/mapper/main.py"
    click SM_Proto "https://github.com/alwyn25/invoicecoreprocessor/blob/main/protos/mapper.proto"
    click SM_Stubs "https://github.com/alwyn25/invoicecoreprocessor/blob/main/generated/mapper_pb2.py"
    click AA_Main "https://github.com/alwyn25/invoicecoreprocessor/blob/main/microservices/agent/main.py"
    click AA_Proto "https://github.com/alwyn25/invoicecoreprocessor/blob/main/protos/agent.proto"
    click AA_Stubs "https://github.com/alwyn25/invoicecoreprocessor/blob/main/generated/agent_pb2.py"
    click DS_Main "https://github.com/alwyn25/invoicecoreprocessor/blob/main/microservices/datastore/main.py"
    click DS_Proto "https://github.com/alwyn25/invoicecoreprocessor/blob/main/protos/datastore.proto"
    click DS_Stubs "https://github.com/alwyn25/invoicecoreprocessor/blob/main/generated/datastore_pb2.py"

    %% Styles
    classDef external fill:#FFD1DC,stroke:#333,stroke-width:1px;
    classDef orchestrator fill:#D6EFFF,stroke:#333,stroke-width:1px;
    classDef microservice fill:#E0F8E0,stroke:#333,stroke-width:1px;
    classDef contract fill:#F0F0F0,stroke:#333,stroke-width:1px;
    classDef db fill:#FFE0B2,stroke:#333,stroke-width:1px;
```
