# jangjiwon0108/income-tax-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/jangjiwon0108/income-tax-chatbot
- Repository: https://github.com/jangjiwon0108/income-tax-chatbot

## Overview

##### Project Type and Purpose
- This is a full-stack retrieval-augmented ChatBot (“소득세법 안내 ChatBot (LangGraph)”) that serves tax-law Q&A over a Korean Income Tax Law PDF.
- The frontend is a Streamlit application (`frontend/chatbot_streamlit.py`).
- The backend is a Python service (likely FastAPI) under `backend/`, orchestrating a LangGraph pipeline for RAG (Retrieval-Augmented Generation) and LLM calls.

##### Top-Level Components
a. Frontend (Streamlit chat UI)
b. Backend API (e.g., FastAPI entrypoint `backend/main.py`, router in `backend/app/router/api_router.py`)
c. LangGraph Assistant Pipeline
- Graph definition (`backend/app/assistant/graph.py`)
- Nodes: retriever, run_gpt, run_upstage_llm, answer_evaluate, result_comparison (`backend/app/assistant/nodes/…`)
- State & Templates (`backend/app/assistant/state.py`, `templates.py`)
d. RAG Module
- Document ingestion & retrieval job (`backend/app/rag/rag_job.py`)
- Source documents: PDFs in `backend/app/rag/`
e. History Module
- Conversation persistence (`backend/app/history/save_history.py`)
f. Config & Schema
- Shared settings (`backend/config.py`), request/response models (`backend/schema.py`)

##### Component Relationships & Data Flow
1. User enters a query in the Streamlit UI.
2. The UI calls the Backend API (e.g., POST `/chat`).
3. API Router forwards request to the LangGraph pipeline:
- Retriever node locates relevant PDF passages (RAG).
- run_gpt or run_upstage_llm nodes invoke the LLM.
- answer_evaluate and result_comparison nodes refine the output.
4. Pipeline state and templates orchestrate prompts and responses.
5. save_history persists user-bot interactions.
6. Final answer is returned via the API to the Streamlit frontend.

##### Architectural Patterns & Technologies
- Layered/Onion architecture: UI → API layer → Application logic (LangGraph pipeline) → Data access (PDF retrieval, history store).
- RAG pattern: combining vector search over PDFs with LLM generation.
- Pipeline/Graph pattern via LangGraph nodes.
- Tech stack: Python, FastAPI (inferred), Streamlit, LangGraph, PyPDF or similar for PDF processing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    UI["Streamlit Chat UI"]:::frontend
    click UI "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/frontend/chatbot_streamlit.py"

    %% API Layer
    API["FastAPI Backend"]:::api
    click API "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/main.py"
    Router["API Router"]:::api
    click Router "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/router/api_router.py"
    CONF["Config Settings"]:::api
    click CONF "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/config.py"
    SCHEMA["Request/Response Schemas"]:::api
    click SCHEMA "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/schema.py"

    %% Application Layer - LangGraph Pipeline
    subgraph "LangGraph Orchestrator" 
        Graph["Graph Definition"]:::pipeline
        click Graph "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/graph.py"
        State["Pipeline State"]:::pipeline
        click State "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/state.py"
        Templates["Prompt Templates"]:::pipeline
        click Templates "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/templates.py"
        Retriever["Retriever\n(Vector search)"]:::pipeline
        click Retriever "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/nodes/retreiver.py"
        RAGJob["RAG Job\n(Ingest PDFs)"]:::pipeline
        click RAGJob "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/rag/rag_job.py"
        GPT["run_gpt\n(LLM call)"]:::pipeline
        click GPT "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/nodes/run_gpt.py"
        UpStage["run_upstage_llm\n(LLM call)"]:::pipeline
        click UpStage "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/nodes/run_upstage_llm.py"
        Evaluate["answer_evaluate\n(Refine answer)"]:::pipeline
        click Evaluate "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/nodes/answer_evaluate.py"
        Compare["result_comparison\n(Select best)"]:::pipeline
        click Compare "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/assistant/nodes/result_comparison.py"
    end

    %% Data Layer
    DocumentStore["Document Store\n(PDF Index)"]:::data
    HistoryDB["History Database"]:::data
    HistorySvc["History Service"]:::api
    click HistorySvc "https://github.com/jangjiwon0108/income-tax-chatbot/blob/main/backend/app/history/save_history.py"

    %% Flows
    UI -->|"POST /chat"| API
    API --> Router
    Router --> Graph
    Graph --> State
    Graph --> Templates
    Graph --> Retriever
    Retriever -->|"retrieve passages"| DocumentStore
    Retriever --> GPT
    Retriever --> UpStage
    GPT --> Evaluate
    UpStage --> Evaluate
    Evaluate --> Compare
    Compare --> HistorySvc
    HistorySvc --> HistoryDB
    Compare --> Router
    RAGJob --> DocumentStore

    %% Return to UI
    Router -->|"200 OK with answer"| UI

    %% Styles
    classDef frontend fill:#9f6,stroke:#2b,stroke-width:1px
    classDef api fill:#6cf,stroke:#06c,stroke-width:1px
    classDef pipeline fill:#c9c,stroke:#84f,stroke-width:1px
    classDef data fill:#f96,stroke:#f30,stroke-width:1px
```
