# iamgolden55/tax-invoice-agent architecture

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

- Interactive diagram: https://gitdiagram.com/iamgolden55/tax-invoice-agent
- Repository: https://github.com/iamgolden55/tax-invoice-agent

## Overview

##### Main Components Identification
- API Server: Represent the FastAPI server (located in the api folder and initiated with main.py) which exposes an endpoint (/ask) to serve client requests.
- LangChain Agent: Highlight the standalone agent logic (agent.py) where interactions with the OpenAI API occur.
- Data Processing & Analysis: Show the CSV dataset (in the data directory) that feeds salary details for generating payslips and performing analyses.
- Tools Module: Include components from the tools folder, such as:
- data_retriever.py: Handles data access.
- email_sender.py: Manages the email dispatch of payslips.
- invoice_generator.py: Handles PDF generation for invoices.
- Output Artifacts: Display the generated PDFs:
- Payslips (in the payslips folder)
- Invoices (in the invoices folder)

##### Relationships and Interaction Flow
- Clients (could be via Postman, EchoAPI, or any external system) send POST requests to the FastAPI endpoint (/ask).
- The FastAPI server (api/main.py) routes the queries to the LangChain Agent (agent.py) which decides the necessary action.
- For payslip generation, it interacts with the CSV dataset in the data folder.
- For PDF conversion, it calls tools/invoice_generator.py and possibly a corresponding tool for generating payslips.
- For emailing, it calls tools/email_sender.py.
- For data analysis, the agent processes the CSV dataset to calculate metrics such as average salary.
- The generated PDFs are then stored in the corresponding directories (invoices or payslips) and can optionally be emailed back to the users.
- The response is then delivered over the API.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Different modules handle distinct tasks (API routing, agent logic, PDF generation, emailing, and data retrieval).
- Integration with External APIs: Emphasize the integration with the OpenAI API and LangChain library.
- Deployment Considerations: Highlight that Heroku deployment uses Procfile and runtime.txt to manage the Python runtime environment.

##### Relevant Technologies & Frameworks
- FastAPI: For building the RESTful API.
- LangChain & OpenAI API: For the intelligent agent processing queries.
- Python Tools: Including modules for PDF generation, email sending, and CSV data manipulation.
- Heroku: Hosting and deployment platform.
- Possibly Uvicorn: As the server runner.

##### Elements
- Each component should be clearly labeled (e.g., "FastAPI Server", "LangChain Agent", "CSV Data Source", "Payslip Generator", "Email Sender").
- Data input from clients to API server.
- API server forwarding requests to the LangChain Agent.
- The output artifacts being saved in specific folders.

##### Detailed Component Overview
- API Layer:
- “api/main.py” as the entry point for requests.
- Annotation for endpoints (e.g., /ask).
- Intelligent Agent:
- “agent.py” as the central logic component that interprets and decides on actions.
- Data Layer:
- “data” folder with the CSV salary dataset.
- That this dataset is the source for payslip generation and analytics.
- Tools Layer:
- Lay out the three major utilities in the "tools" folder, mapping them to their function (data retrieval, email sending, invoice generation).
- Output/Artifacts:
- Storage for “payslips” and “invoices”.
- Flow from the agent’s instructions to the generation and storage of PDFs.
- External Services:
- A reference for the OpenAI API and any deployment-related services (Heroku).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        Client("Client (e.g., Postman, External System)"):::client
    end

    %% API Layer
    subgraph "API Layer"
        APIServer("FastAPI Server (/ask)"):::api
    end

    %% Agent Layer
    subgraph "Agent Layer"
        Agent("LangChain Agent"):::agent
    end

    %% Data & Tools Layer
    subgraph "Data & Tools Layer"
        Data("CSV Dataset"):::data
        subgraph "Tools Module"
            DataRetriever("Data Retriever"):::tool
            EmailSender("Email Sender"):::tool
            InvoiceGenerator("Invoice Generator"):::tool
        end
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        Payslips("Payslips (Generated PDF)"):::output
        Invoices("Invoices (Generated PDF)"):::output
    end

    %% External Services
    subgraph "External Services"
        OpenAI("OpenAI API"):::external
        Heroku("Heroku Deployment"):::external
    end

    %% Connections
    Client -->|"POST_/ask"| APIServer
    APIServer -->|"Routes_Request"| Agent
    Agent -->|"Fetches_Data"| Data
    Agent -->|"Invokes_Retrieval"| DataRetriever
    DataRetriever -->|"Accesses"| Data
    Agent -->|"Processes_for_Payslip"| Payslips
    Agent -->|"Generates_Invoice"| InvoiceGenerator
    InvoiceGenerator -->|"Creates_PDF"| Invoices
    Agent -->|"Sends_Email"| EmailSender
    EmailSender -->|"Dispatches"| Payslips
    Agent -->|"Queries"| OpenAI
    APIServer ---|"Deployed_with"| Heroku
    Agent ---|"Deployed_with"| Heroku

    %% Click Events
    click APIServer "https://github.com/iamgolden55/tax-invoice-agent/blob/main/api/main.py"
    click Agent "https://github.com/iamgolden55/tax-invoice-agent/blob/main/agent.py"
    click Data "https://github.com/iamgolden55/tax-invoice-agent/blob/main/data/Employee_Salary_Dataset.csv"
    click Payslips "https://github.com/iamgolden55/tax-invoice-agent/tree/main/payslips/"
    click Invoices "https://github.com/iamgolden55/tax-invoice-agent/tree/main/invoices/"
    click DataRetriever "https://github.com/iamgolden55/tax-invoice-agent/blob/main/tools/data_retriever.py"
    click EmailSender "https://github.com/iamgolden55/tax-invoice-agent/blob/main/tools/email_sender.py"
    click InvoiceGenerator "https://github.com/iamgolden55/tax-invoice-agent/blob/main/tools/invoice_generator.py"
    click Heroku "https://github.com/iamgolden55/tax-invoice-agent/tree/main/Procfile"

    %% Styles
    classDef client fill:#f9d6d5,stroke:#333,stroke-width:2px;
    classDef api fill:#c9daf8,stroke:#333,stroke-width:2px;
    classDef agent fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef data fill:#fce5cd,stroke:#333,stroke-width:2px;
    classDef tool fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef output fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef external fill:#d0e0e3,stroke:#333,stroke-width:2px;
```
