# iiiiiiiinseong/finance-agent architecture

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

- Interactive diagram: https://gitdiagram.com/iiiiiiiinseong/finance-agent
- Repository: https://github.com/iiiiiiiinseong/finance-agent

## Overview

##### Main Components
- Data Layer
- Raw Documents (PDFs in `data/raw_docs/woori_deposit_trust_docs`)
- Structured FAQ JSONL (`data/processed/faq_woori_structured.jsonl`)
- ETL & Indexing Layer
- Product Loader (`data/loader/product_loader.py`)
- FAQ Structure Script (`data/processed/faq_woori.py`)
- Index Builders (`scripts/build_faq_index.py`, `scripts/build_deposit_index.py`)
- FAISS Indices (`index/faq_faiss/`, `index/deposit_faiss/`)
- Retrieval & Generation Layer (RAG Services)
- FAQ RAG (`services/rag/faq_rag/retriever.py`, `faq_chain.py`)
- Product RAG (`services/rag/product_rag/retriever.py`, `chain.py`)
- Orchestration & Fallback
- Router/Manager Agent (`services/orchestrator/router_node.py`)
- Fallback LLM Node (`services/fallback/fallback_llm.py`)
- Advisor Stub (future; `services/advisor/advisor_stub.py`)
- Configuration
- `config.py` (holds API keys, model names, chunk sizes, top-K parameters)
- UI Layer
- Streamlit App (`apps/streamlit_app/app.py`)
- External Services
- OpenAI Embeddings & LLM API
- (Optional) BM25 search component

##### Relationships & Data Flow
- Data Ingestion Flow (offline):
Raw Documents → ETL Loader → Chunked Documents → Embedding via OpenAI → FAISS Index
FAQ JSONL → Embedding → FAQ FAISS Index
- Query Flow (online):
User Input in Streamlit → Router Node
→ Parallel calls to FAQ RAG and Product RAG
- Each retrieves top-k contexts from FAISS (and optionally BM25)
- Each executes a LangGraph chain to generate answer with citations
→ Fallback LLM for out-of-scope queries
→ Merge outputs in Manager Agent → Return to UI
- Configuration Globals guide all modules via `config.py`

##### Architectural Patterns & Principles
- Modular RAG services for each domain (FAQ vs. Product)
- Hybrid retrieval pattern (FAISS + BM25)
- Pipelines defined by LangGraph (retrieve → generate)
- Orchestrator as coordinator (router + manager agent + fallback)
- Separation of concerns: ETL, indexing, retrieval, orchestration, presentation

##### Essential Elements to Capture
- Offline ETL & index-build process (as a separate flow)
- Dual retrieval pipelines (FAQ vs. Product)
- Orchestrator logic (parallel calls, fallback merge)
- Configuration centralization
- Streamlit UI invoking the router
- External dependencies (OpenAI API)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI & External"
        UI("Streamlit UI"):::ui
        OpenAI("OpenAI API"):::external
    end

    subgraph "Service Layer"
        Router("Router/Manager Agent"):::service
        Fallback("Fallback LLM Node"):::service
        subgraph "FAQ RAG Service"
            FAQRet("FAQ Retriever"):::service
            FAQChain("FAQ Chain"):::service
        end
        subgraph "Product RAG Service"
            ProdRet("Product Retriever"):::service
            ProdChain("Product Chain"):::service
        end
    end

    subgraph "Indexing & ETL Layer"
        ProdLoader("Product Loader"):::etl
        FAQStruct("FAQ Structure Script"):::etl
        BuildFAQ("Build FAQ Index"):::etl
        BuildDep("Build Deposit Index"):::etl
        subgraph "FAISS Indices"
            FAQIndex("FAQ FAISS Index"):::index
            DepIndex("Deposit FAISS Index"):::index
        end
    end

    subgraph "Data Layer"
        RawDocs("Raw Documents"):::data
        FAQJSON("Structured FAQ JSONL"):::data
    end

    Config("Config"):::config

    %% Data Ingestion Flow
    RawDocs --> ProdLoader
    RawDocs --> FAQStruct
    FAQJSON --> BuildFAQ
    ProdLoader --> BuildDep
    FAQStruct --> BuildFAQ
    BuildFAQ --> FAQIndex
    BuildDep --> DepIndex

    %% Query Flow
    UI --> Router
    Router --> FAQRet
    Router --> ProdRet
    FAQRet --> FAQChain
    ProdRet --> ProdChain
    FAQChain --> Router
    ProdChain --> Router
    Router --> Fallback
    Fallback --> Router
    Router --> UI

    %% External Calls
    FAQRet --> OpenAI
    ProdRet --> OpenAI
    FAQChain --> OpenAI
    ProdChain --> OpenAI
    Fallback --> OpenAI

    %% Configuration
    Config -.-> ProdLoader
    Config -.-> FAQStruct
    Config -.-> BuildFAQ
    Config -.-> BuildDep
    Config -.-> Router
    Config -.-> Fallback
    Config -.-> FAQRet
    Config -.-> FAQChain
    Config -.-> ProdRet
    Config -.-> ProdChain
    Config -.-> UI

    %% Click Events
    click UI "https://github.com/iiiiiiiinseong/finance-agent/blob/main/apps/streamlit_app/app.py"
    click Router "https://github.com/iiiiiiiinseong/finance-agent/blob/main/services/orchestrator/router_node.py"
    click Fallback "https://github.com/iiiiiiiinseong/finance-agent/blob/main/services/fallback/fallback_llm.py"
    click FAQRet "https://github.com/iiiiiiiinseong/finance-agent/blob/main/services/rag/faq_rag/retriever.py"
    click FAQChain "https://github.com/iiiiiiiinseong/finance-agent/blob/main/services/rag/faq_rag/faq_chain.py"
    click ProdRet "https://github.com/iiiiiiiinseong/finance-agent/blob/main/services/rag/product_rag/retriever.py"
    click ProdChain "https://github.com/iiiiiiiinseong/finance-agent/blob/main/services/rag/product_rag/chain.py"
    click ProdLoader "https://github.com/iiiiiiiinseong/finance-agent/blob/main/data/loader/product_loader.py"
    click FAQStruct "https://github.com/iiiiiiiinseong/finance-agent/blob/main/data/processed/faq_woori.py"
    click BuildFAQ "https://github.com/iiiiiiiinseong/finance-agent/blob/main/scripts/build_faq_index.py"
    click BuildDep "https://github.com/iiiiiiiinseong/finance-agent/blob/main/scripts/build_deposit_index.py"
    click RawDocs "https://github.com/iiiiiiiinseong/finance-agent/tree/main/data/raw_docs/woori_deposit_trust_docs"
    click FAQJSON "https://github.com/iiiiiiiinseong/finance-agent/blob/main/data/processed/faq_woori_structured.jsonl"
    click Config "https://github.com/iiiiiiiinseong/finance-agent/blob/main/config.py"

    %% Styles
    classDef ui fill:#e0f7fa,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef service fill:#e1bee7,stroke:#333,stroke-width:1px
    classDef etl fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef index fill:#f0f4c3,stroke:#333,stroke-width:1px
    classDef data fill:#fff9c4,stroke:#333,stroke-width:1px
    classDef config fill:#d7ccc8,stroke:#333,stroke-width:1px
```
