# yancotta/agentic_invoice_system_final_version architecture

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

- Interactive diagram: https://gitdiagram.com/yancotta/agentic_invoice_system_final_version
- Repository: https://github.com/yancotta/agentic_invoice_system_final_version

## Overview

##### Project Type and Purpose
- Type: Full-stack web application with a modular multi-agent backend
- Purpose: Automated PDF invoice ingestion, data extraction, validation, PO matching, and human-in-loop review, with real-time dashboard and metrics.

##### File Structure
- Top-level “frontend-nextjs” directory: Next.js + React UI, WebSocket integration, Tailwind CSS
- “api” and “main.py”: FastAPI application entrypoint, REST and WebSocket endpoints
- “agents/” and “workflows/”: Multi-agent orchestration code (`orchestrator.py`) and individual agents (extractor, validator, matching, fallback, human_review)
- “data_processing/”: Helper modules for OCR, RAG/FAISS retrieval, anomaly detection, scoring, PO matching
- “config/”: Logging, monitoring, and settings modules
- “models/”: Pydantic schemas and ORM models (if any)
- “db.py”, “setup_db.py”, “migrate_json_to_db.py”: SQLite database setup and migration logic
- “setup_s3.py” & “aws_policy.json”: AWS S3 configuration for PDF storage
- “docker-compose.yml” + Dockerfiles: Containerization of backend and frontend
- “data/”: Raw, processed, and test-sample invoices; supports FAISS index building and demo data
- “invoices.db”: SQLite file for persistent metadata

##### Extract Architectural Insights from the README
- Frontend communicates with backend over HTTP and WebSockets (real-time updates)
- Backend delegates tasks to a LangChain-style multi-agent pipeline
- Agents perform extraction (OpenAI GPT4 mini), validation (Pydantic), PO matching (fuzzy logic), FAISS fallback, and human review for low-confidence cases
- Metadata stored in SQLite; PDFs stored in AWS S3
- Fully containerized via Docker Compose, with CI/CD building and pushing images

##### Main Components and Interactions
a. Components
- Next.js Frontend (UI, WebSocket client)
- FastAPI Backend (REST + WebSocket server)
- Orchestrator (workflows/orchestrator.py)
- Agent Modules (agents/*.py)
- Data Processing Helpers (data_processing/*.py)
- SQLite Database (invoices.db)
- AWS S3 Bucket (PDF storage)
- FAISS Index (RAG fallback)
- External OpenAI API
b. Relationships & Data Flow
1. User uploads PDF → Next.js “upload” page → HTTP POST to FastAPI
2. FastAPI accepts file → pushes task to Orchestrator
3. Orchestrator dispatches to agents in sequence (extract → validate → match)
4. Each agent calls into data_processing modules and/or OpenAI
5. Low-confidence or errors → human_review_agent → manual UI review via WebSocket
6. Fallback_agent uses FAISS retrieval on test_samples
7. Completed invoice metadata → store in SQLite via db.py
8. Original PDF → upload to S3 via setup_s3.py logic
9. Backend emits WebSocket updates → Next.js UI pages (metrics, anomalies, invoices, review)
c. Architectural Patterns
- Modular agent pipeline (Chain-of-responsibility)
- Human-in-loop pattern for low-confidence cases
- Event-driven updates via WebSockets
- Containerized micro-services style (frontend + backend)
- Retrieval-Augmented Classification (RAC/RAG using FAISS)
d. Key Technologies & Frameworks
- Next.js 14 + Tailwind CSS
- FastAPI + Pydantic
- LangChain agent pattern
- OpenAI GPT-4o-mini
- FAISS for vector retrieval
- SQLite (via db.py/migrate_json_to_db.py)
- AWS S3 for PDF storage
- Docker & Docker Compose; GitHub Actions CI/CD

##### Final Checklist
- Major modules from the file tree (frontend-nextjs, api/app.py, agents, data_processing, workflows)
- Data inputs (data/raw, test_samples) and outputs (data/processed, invoices.db)
- Asynchronous workflows and fallback/human-loop branching
- CI/CD and container orchestration if desired (optional layer)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Swimlane Frontend
    subgraph "Frontend"
        direction TB
        NextJS["Next.js Frontend"]:::frontend
        Pages["UI Pages (upload, review, dashboard)"]:::frontend
        APIClient["API Client (HTTP/WebSocket)"]:::frontend
        NextJS --> Pages
        Pages --> APIClient
    end

    click NextJS "https://github.com/yancotta/agentic_invoice_system_final_version/tree/feature/database-integration/frontend-nextjs/"
    click Pages "https://github.com/yancotta/agentic_invoice_system_final_version/tree/feature/database-integration/frontend-nextjs/src/pages/"
    click APIClient "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/frontend-nextjs/src/lib/api.ts"

    %% Swimlane Backend
    subgraph "Backend"
        direction TB
        FastAPI["FastAPI Backend (app.py)"]:::backend
        ReviewAPI["Review WebSocket/REST API"]:::backend
        Main["Script Runner Entry (main.py)"]:::backend
        FastAPI --> ReviewAPI
        FastAPI --> Main
    end

    click FastAPI "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/api/app.py"
    click ReviewAPI "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/api/review_api.py"
    click Main "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/main.py"

    %% Orchestrator
    Orchestrator["Orchestrator"]:::backend
    click Orchestrator "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/workflows/orchestrator.py"

    FastAPI -->|calls| Orchestrator
    Main -->|triggers| Orchestrator

    %% Agents
    subgraph "Agents" 
        direction TB
        BaseAgent["Base Agent"]:::agent
        Extractor["Extraction Agent"]:::agent
        Validator["Validation Agent"]:::agent
        Matcher["PO-Matching Agent"]:::agent
        Fallback["FAISS Fallback Agent"]:::agent
        HumanReview["Human-Review Agent"]:::agent
    end

    click BaseAgent "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/agents/base_agent.py"
    click Extractor "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/agents/extractor_agent.py"
    click Validator "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/agents/validator_agent.py"
    click Matcher "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/agents/matching_agent.py"
    click Fallback "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/agents/fallback_agent.py"
    click HumanReview "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/agents/human_review_agent.py"

    Orchestrator --> BaseAgent
    BaseAgent --> Extractor --> Validator --> Matcher
    Validator -->|low_confidence| HumanReview
    Matcher -->|no_match| Fallback -->|fallback_result| HumanReview
    Matcher -->|matched| DB

    %% Data Processing Helpers
    subgraph "Data Processing Helpers"
        direction TB
        OCR["OCR Helper"]:::backend
        Parser["Document Parser"]:::backend
        Anomaly["Anomaly Detection"]:::backend
        Scoring["Confidence Scoring"]:::backend
        POMatcher["PO Matcher Logic"]:::backend
        RAGHelper["RAG/FAISS Helper"]:::backend
    end

    click OCR "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/data_processing/ocr_helper.py"
    click Parser "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/data_processing/document_parser.py"
    click Anomaly "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/data_processing/anomaly_detection.py"
    click Scoring "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/data_processing/confidence_scoring.py"
    click POMatcher "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/data_processing/po_matcher.py"
    click RAGHelper "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/data_processing/rag_helper.py"

    Extractor --> OCR
    Extractor --> Parser
    Validator --> Scoring
    Validator --> Anomaly
    Matcher --> POMatcher
    Fallback --> RAGHelper

    %% Storage & External
    DB["SQLite Database"]:::datastore
    click DB "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/invoices.db"
    DBSetup["DB Setup Script"]:::backend
    click DBSetup "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/setup_db.py"
    Migration["Migration Script"]:::backend
    click Migration "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/migrate_json_to_db.py"
    DBSetup --> DB
    Migration --> DB

    S3["AWS S3 Bucket"]:::datastore
    click S3 "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/setup_s3.py"
    S3Policy["IAM Policy"]:::backend
    click S3Policy "https://github.com/yancotta/agentic_invoice_system_final_version/blob/feature/database-integration/aws_policy.json"
    S3Policy --> S3

    OpenAI["OpenAI API"]:::external
    Extractor -->|calls| OpenAI

    FAISSIndex["FAISS Index"]:::datastore
    TestSamples["Test Sample Invoices"]:::datastore
    click TestSamples "https://github.com/yancotta/agentic_invoice_system_final_version/tree/feature/database-integration/data/test_samples/"
    RAGHelper --> FAISSIndex
    RAGHelper --> TestSamples

    Raw["Raw Invoices"]:::datastore
    click Raw "https://github.com/yancotta/agentic_invoice_system_final_version/tree/feature/database-integration/data/raw/invoices/"
    Processed["Processed Output"]:::datastore
    click Processed "https://github.com/yancotta/agentic_invoice_system_final_version/tree/feature/database-integration/data/processed/"

    %% Data Flows
    Pages -->|HTTP_POST| FastAPI
    APIClient -->|WebSocket| ReviewAPI
    Orchestrator --> S3
    Orchestrator --> DB
    FastAPI -->|WS_update| APIClient

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef agent fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef datastore fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
