How yancotta/agentic_invoice_system_final_version works
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)