# datpham0412/invoice-processor architecture

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

- Interactive diagram: https://gitdiagram.com/datpham0412/invoice-processor
- Repository: https://github.com/datpham0412/invoice-processor

## Overview

##### Project type and purpose
- Full-stack web application (“MatchFlow”) for invoice reconciliation
- Purpose: Users upload PDF invoices; the system extracts structured data via Azure Form Recognizer, matches it against stored Purchase Orders, flags discrepancies, and presents audit trails.

##### File structure
- Root directories:
– InvoiceProcessor.API – .NET 6 Web API (Application, Controllers, Domain, Infrastructure, Migrations)
– InvoiceProcessor.Tests – xUnit tests for repositories and services
– frontend – React + Vite single-page app with shadcn/ui and Tailwind CSS
– redirect-app – NGINX proxy/redirect service
- API layer follows Clean Architecture:
– Application: interfaces (IInvoiceRepository, IFormRecognizer…), DTO models, services (UploadInvoiceService, MatchingService…)
– Controllers: REST endpoints for auth, invoice upload/list/match, PO operations, OCR tests
– Domain: entities (Invoice, PurchaseOrder, LineItem, ExceptionRecord, User), enums, exceptions
– Infrastructure: Azure Blob Storage client, Form Recognizer client, EF Core DbContext & repositories, JWT & Azure settings
- Deployment/config: Dockerfiles (API, frontend, redirect-app), docker-compose.yml, GitHub Actions workflow, Fly.io manifests

##### README for additional insights
- Describes end-to-end flow: upload → OCR → compare → alert
- Tech stack: React + Vite, ASP NET Core, EF Core, SQL Server, Azure Blob, Cognitive Services, Service Bus, JWT auth, Docker/Fly.io, Nginx
- Mentions CI/CD, monitoring via Application Insights

##### Elements
- Clear, descriptive labels for each component and interface
- Annotations for protocols (HTTPS, AMQP, SQL) and data formats (JSON, JWT)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser<br/>(React SPA)"]:::client
    end

    %% Reverse Proxy Layer
    subgraph "NGINX Reverse Proxy"
        Proxy["NGINX Proxy"]:::proxy
    end

    %% API Gateway and Layers
    subgraph "API Gateway (.NET 6 Web API)"
        API["API Gateway"]:::api

        subgraph "Controllers Layer"
            AuthCtrl["AuthController"]:::controller
            UploadCtrl["InvoiceUploadController"]:::controller
            ListCtrl["InvoiceListController"]:::controller
            MatchCtrl["InvoiceMatchController"]:::controller
            POListCtrl["PurchaseOrderListController"]:::controller
            BlobTestCtrl["BlobTestController"]:::controller
            TestOcrCtrl["TestOcrController"]:::controller
        end

        subgraph "Application Layer"
            UploadSvc["UploadInvoiceService"]:::service
            MatchSvc["MatchingService"]:::service
            CreatePOSvc["CreatePurchaseOrderService"]:::service
            Interfaces["Interfaces<br/>(IInvoiceRepository, IFormRecognizer, IServiceBusClient, IUserService, etc.)"]:::service
        end

        subgraph "Domain Layer"
            Invoice["Invoice"]:::domain
            PO["PurchaseOrder"]:::domain
            LineItem["LineItem"]:::domain
            ExceptionRec["ExceptionRecord"]:::domain
            UserEnt["User"]:::domain
        end

        subgraph "Infrastructure Layer"
            BlobSvc["BlobStorageService"]:::infra
            OCRClient["FormRecognizerClient"]:::infra
            UserSvcImpl["UserService"]:::infra
            ServiceBusIntf["IServiceBusClient"]:::infra
        end
    end

    %% Persistence & Cloud Services
    subgraph "Persistence & Cloud Services"
        SQLServer["Azure SQL Database"]:::db
        BlobStore["Azure Blob Storage"]:::cloud
        FormRec["Azure Form Recognizer"]:::cloud
        ServiceBus["Azure Service Bus"]:::cloud
        Insights["Application Insights"]:::cloud
    end

    %% Data Flows
    Browser -->|"HTTPS (JWT)"| Proxy
    Proxy -->|"Forward Request"| API

    %% Authentication Flow
    API --> AuthCtrl
    AuthCtrl --> Interfaces
    Interfaces --> UserSvcImpl
    UserSvcImpl --> SQLServer
    AuthCtrl -.->|"JWT Issuance/Validation"| Interfaces

    %% Upload Flow
    API --> UploadCtrl
    UploadCtrl --> UploadSvc
    UploadSvc --> BlobSvc
    BlobSvc --> BlobStore
    UploadSvc --> OCRClient
    OCRClient --> FormRec
    UploadSvc --> SQLServer

    %% Matching Flow
    API --> MatchCtrl
    MatchCtrl --> MatchSvc
    MatchSvc --> Interfaces
    Interfaces --> SQLServer
    MatchSvc --> ServiceBus
    ServiceBus --> ServiceBusIntf
    ServiceBusIntf --> ExceptionRec
    ExceptionRec --> SQLServer

    %% Purchase Order Flow
    API --> POListCtrl
    POListCtrl --> Interfaces
    Interfaces --> SQLServer

    %% List & Test Endpoints
    API --> ListCtrl
    API --> BlobTestCtrl
    API --> TestOcrCtrl

    %% Monitoring
    API --> Insights

    %% Frontend Polling
    Browser -->|"Poll /subscribe"| MatchCtrl

    %% Click Events
    click Browser "https://github.com/datpham0412/invoice-processor/blob/main/frontend/src/App.jsx"
    click Proxy "https://github.com/datpham0412/invoice-processor/tree/main/redirect-app/"
    click API "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Program.cs"
    click AuthCtrl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Controllers/AuthController.cs"
    click UploadCtrl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Controllers/InvoiceUploadController.cs"
    click ListCtrl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Controllers/InvoiceListController.cs"
    click MatchCtrl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Controllers/InvoiceMatchController.cs"
    click POListCtrl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Controllers/PurchaseOrderListController.cs"
    click BlobTestCtrl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Controllers/BlobTestController.cs"
    click TestOcrCtrl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Controllers/TestOcrController.cs"
    click UploadSvc "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Application/Services/UploadInvoiceService.cs"
    click MatchSvc "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Application/Services/MatchingService.cs"
    click CreatePOSvc "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Application/Services/CreatePurchaseOrderService.cs"
    click Interfaces "https://github.com/datpham0412/invoice-processor/tree/main/InvoiceProcessor.API/Application/Interfaces/"
    click Invoice "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Domain/Entities/Invoice.cs"
    click PO "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Domain/Entities/PurchaseOrder.cs"
    click LineItem "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Domain/Entities/LineItem.cs"
    click ExceptionRec "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Domain/Entities/ExceptionRecord.cs"
    click UserEnt "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Domain/Entities/User.cs"
    click BlobSvc "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Infrastructure/Blob/BlobStorageService.cs"
    click OCRClient "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Infrastructure/OCR/FormRecognizerClient.cs"
    click UserSvcImpl "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Infrastructure/Service/UserService.cs"
    click ServiceBusIntf "https://github.com/datpham0412/invoice-processor/blob/main/InvoiceProcessor.API/Application/Interfaces/IServiceBusClient.cs"

    %% Styles
    classDef client fill:#E8F4FC,stroke:#333,stroke-width:1px
    classDef proxy fill:#F2F3F4,stroke:#333,stroke-width:1px
    classDef api fill:#FDEBD0,stroke:#333,stroke-width:1px
    classDef controller fill:#FCF3CF,stroke:#333,stroke-width:1px
    classDef service fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef domain fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef infra fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef db fill:#ABEBC6,stroke:#333,stroke-width:1px
    classDef cloud fill:#F5CBA7,stroke:#333,stroke-width:1px
```
