# ogulcanakca/agentic-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/ogulcanakca/agentic-chatbot
- Repository: https://github.com/ogulcanakca/agentic-chatbot

## Overview

1. **High-level shape**
   - This repository is a **Python-based multi-agent chatbot** built around a **LangGraph supervisor pattern**.
   - A single chat interface routes each user request into one of several specialized branches: Resmi Gazete RAG, news/general knowledge, uploaded-document RAG, travel planning, or fallback.

2. **Primary entry point and UI boundary**
   - The user-facing entry point is **Streamlit** in `app/ui/streamlit_app.py`.
   - The UI is thin: it collects chat input, optional document uploads, and displays answers, sources, and travel-plan outputs; it delegates orchestration to the graph layer.

3. **Main orchestration layer**
   - `app/graph.py` defines the **top-level LangGraph workflow**.
   - Shared conversational data moves through `app/core/state.py`, which acts as the central state object passed between supervisor and agents.
   - `app/core/llm.py` centralizes LLM creation so all agents use a consistent model setup.

4. **Supervisor routing**
   - `app/agents/supervisor.py` classifies the request and chooses the next agent.
   - This is the main architectural decision point: it determines whether the query is treated as legal/government text, general knowledge/news, user document QA, travel planning, or fallback.

5. **Specialized agents at the top level**
   - `app/agents/resmi_gazete_agent.py` handles **Turkish Resmi Gazete** questions using retrieval-augmented generation.
   - `app/agents/news_agent.py` answers **news and general knowledge** queries using external search and knowledge tools.
   - `app/agents/agentic_rag_agent.py` handles **uploaded document QA** via RAG.
   - `app/agents/travel_agent.py` bridges into the travel-planning subsystem.
   - `app/agents/fallback_agent.py` covers out-of-scope queries.

6. **RAG and vector storage boundary**
   - Persistent retrieval data is managed in `app/storage/database.py` on top of **ChromaDB**.
   - The repository contains prebuilt vector data in `data/embeddings/`, so the RAG agents can query local embeddings without rebuilding them at runtime.
   - `app/tools/rag_tools.py` provides document retrieval and context formatting for the Resmi Gazete path.

7. **External knowledge tools**
   - `app/tools/external_apis.py` supplies tools used by the news/general-knowledge branch.
   - The README indicates integrations such as **Tavily/DuckDuckGo**, **Wikipedia**, and related search APIs; this branch is designed for live or semi-live information rather than local corpora.

8. **Travel-planning subsystem as a nested workflow**
   - `app/travel_system/workflow.py` defines a separate **subworkflow** for trip planning, distinct from the main chat graph.
   - It has its own agents:
     - `destination_agent.py` for destination research,
     - `date_budget_agent.py` for time/budget reasoning,
     - `coordinator_agent.py` for composing the final travel plan.
   - Its tools cover parsing, budget, date, destination, and PDF generation, making it a self-contained planning pipeline.

9. **Travel outputs**
   - The travel subsystem can produce a **PDF itinerary** via `app/travel_system/utils/pdf_saver.py`.
   - `plans/` stores generated plan PDFs, while `assets/fonts/` and `fonts/` provide the font assets needed for PDF rendering.

10. **Data preparation pipeline**
   - `scripts/news_fetcher.py` and `scripts/resmi_news_fetcher.py` fetch source content into `data/raw/`.
   - `scripts/process_data.py` converts raw content into structured chunks under `data/processed/`.
   - `scripts/generate_embeddings.py` builds the vector store in `data/embeddings/`.
   - `scripts/del.py` is a cleanup utility for resetting generated data.

11. **Configuration and environment**
   - Runtime behavior is driven by `configs/agent_config.py`, `configs/app_config.py`, `configs/api_config.py`, and `configs/script_config.py`.
   - API keys and service credentials are loaded from `.env`, which is part of the deployment boundary but not the application logic itself.

12. **Deployment and persistence**
   - The repo supports both local execution and **Docker/Docker Compose** deployment.
   - Persistent application state is mostly file-based: `data/` for corpora and embeddings, `plans/` for PDFs, and environment variables for secrets.
   - There is no central relational backend in the architecture; the system is primarily a **graph-orchestrated LLM app with local vector persistence and external API calls**.

Main entry points: [`app/agents/supervisor.py`](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/supervisor.py) (Supervisor), [`app/graph.py`](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/graph.py) (Main Graph), [`app/travel_system/workflow.py`](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/workflow.py) (Travel Workflow), [`app/agents/news_agent.py`](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/news_agent.py) (News Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_ui_streamlit["Streamlit UI<br/>streamlit app<br/>[streamlit_app.py]"]
end

subgraph group_orchestration["Chat Orchestration"]
  node_graph{{"Main Graph<br/>langgraph workflow<br/>[graph.py]"}}
  node_state["Chat State<br/>shared state<br/>[state.py]"]
  node_llm(("LLM Setup<br/>model factory<br/>[llm.py]"))
  node_supervisor{{"Supervisor<br/>router agent<br/>[supervisor.py]"}}
end

subgraph group_specialized["Specialized Agents"]
  node_resmi_agent["Resmi Gazete<br/>rag agent"]
  node_news_agent["News Agent<br/>search agent<br/>[news_agent.py]"]
  node_doc_agent["Doc RAG<br/>document qa agent"]
  node_travel_agent["Travel Bridge<br/>workflow bridge<br/>[travel_agent.py]"]
  node_fallback_agent["Fallback<br/>[fallback_agent.py]"]
  node_external_apis["External APIs<br/>search tools<br/>[external_apis.py]"]
end

subgraph group_travel["Travel Subsystem"]
  node_travel_workflow{{"Travel Workflow<br/>subworkflow<br/>[workflow.py]"}}
  node_dest_agent["Destination Agent<br/>planning agent"]
  node_date_budget_agent["Date & Budget<br/>planning agent"]
  node_coordinator_agent["Trip Coordinator<br/>composition agent"]
  node_pdf_saver["PDF Saver<br/>pdf output<br/>[pdf_saver.py]"]
end

subgraph group_retrieval["Retrieval Data"]
  node_rag_tools["RAG Tools<br/>retrieval tools<br/>[rag_tools.py]"]
  node_db[("Vector Store<br/>chroma db<br/>[database.py]")]
  node_embed_data[("Embeddings<br/>vector files")]
end

subgraph group_prep["Data Prep"]
  node_raw_data[("Raw Data<br/>source corpora")]
  node_processed_data[("Processed Data<br/>chunked corpora")]
  node_fetch_scripts["Fetchers<br/>ingest scripts<br/>[news_fetcher.py]"]
  node_process_script["Process Data<br/>prep script<br/>[process_data.py]"]
  node_embed_script["Build Embeddings<br/>prep script"]
end

subgraph group_config["Configuration"]
  node_agent_config["Agent Config<br/>settings<br/>[agent_config.py]"]
  node_app_config["App Config<br/>settings<br/>[app_config.py]"]
  node_api_config["API Config<br/>settings<br/>[api_config.py]"]
end

subgraph group_assets["Outputs & Assets"]
  node_plans_dir[("Plans<br/>generated outputs")]
  node_fonts_dir["Fonts<br/>render assets"]
end

node_ui_streamlit -->|"submit chat"| node_graph
node_graph -->|"route request"| node_supervisor
node_supervisor -->|"official text"| node_resmi_agent
node_supervisor -->|"news / knowledge"| node_news_agent
node_supervisor -->|"uploaded docs"| node_doc_agent
node_supervisor -->|"travel request"| node_travel_agent
node_supervisor -->|"out of scope"| node_fallback_agent
node_graph -->|"store state"| node_state
node_graph -->|"instantiate model"| node_llm
node_resmi_agent -->|"retrieve context"| node_rag_tools
node_rag_tools -->|"query vectors"| node_db
node_db -->|"load embeddings"| node_embed_data
node_news_agent -->|"search tools"| node_external_apis
node_doc_agent -->|"local retrieval"| node_db
node_travel_agent -->|"invoke subworkflow"| node_travel_workflow
node_travel_workflow -->|"destination stage"| node_dest_agent
node_travel_workflow -->|"constraint stage"| node_date_budget_agent
node_travel_workflow -->|"compose plan"| node_coordinator_agent
node_coordinator_agent -->|"export PDF"| node_pdf_saver
node_pdf_saver -->|"save plan"| node_plans_dir
node_pdf_saver -->|"use fonts"| node_fonts_dir
node_fetch_scripts -->|"fetch source"| node_raw_data
node_process_script -->|"read raw"| node_raw_data
node_process_script -->|"write chunks"| node_processed_data
node_embed_script -->|"read processed"| node_processed_data
node_embed_script -->|"write vectors"| node_embed_data
node_ui_streamlit -->|"runtime settings"| node_app_config
node_supervisor -->|"agent rules"| node_agent_config
node_news_agent -->|"api settings"| node_api_config

click node_ui_streamlit "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/ui/streamlit_app.py"
click node_graph "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/graph.py"
click node_state "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/core/state.py"
click node_llm "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/core/llm.py"
click node_supervisor "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/supervisor.py"
click node_resmi_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/resmi_gazete_agent.py"
click node_news_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/news_agent.py"
click node_doc_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/agentic_rag_agent.py"
click node_travel_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/travel_agent.py"
click node_fallback_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/fallback_agent.py"
click node_rag_tools "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/tools/rag_tools.py"
click node_db "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/storage/database.py"
click node_travel_workflow "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/workflow.py"
click node_dest_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/agents/destination_agent.py"
click node_date_budget_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/agents/date_budget_agent.py"
click node_coordinator_agent "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/agents/coordinator_agent.py"
click node_pdf_saver "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/utils/pdf_saver.py"
click node_external_apis "https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/tools/external_apis.py"
click node_raw_data "https://github.com/ogulcanakca/agentic-chatbot/tree/main/data/raw"
click node_processed_data "https://github.com/ogulcanakca/agentic-chatbot/tree/main/data/processed"
click node_embed_data "https://github.com/ogulcanakca/agentic-chatbot/tree/main/data/embeddings"
click node_fetch_scripts "https://github.com/ogulcanakca/agentic-chatbot/blob/main/scripts/news_fetcher.py"
click node_process_script "https://github.com/ogulcanakca/agentic-chatbot/blob/main/scripts/process_data.py"
click node_embed_script "https://github.com/ogulcanakca/agentic-chatbot/blob/main/scripts/generate_embeddings.py"
click node_agent_config "https://github.com/ogulcanakca/agentic-chatbot/blob/main/configs/agent_config.py"
click node_app_config "https://github.com/ogulcanakca/agentic-chatbot/blob/main/configs/app_config.py"
click node_api_config "https://github.com/ogulcanakca/agentic-chatbot/blob/main/configs/api_config.py"
click node_plans_dir "https://github.com/ogulcanakca/agentic-chatbot/tree/main/plans"
click node_fonts_dir "https://github.com/ogulcanakca/agentic-chatbot/tree/main/fonts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_streamlit,node_agent_config,node_app_config,node_api_config toneBlue
class node_graph,node_state,node_llm,node_supervisor,node_plans_dir,node_fonts_dir toneAmber
class node_resmi_agent,node_news_agent,node_doc_agent,node_travel_agent,node_fallback_agent,node_external_apis toneMint
class node_travel_workflow,node_dest_agent,node_date_budget_agent,node_coordinator_agent,node_pdf_saver toneRose
class node_rag_tools,node_db,node_embed_data toneIndigo
class node_raw_data,node_processed_data,node_fetch_scripts,node_process_script,node_embed_script toneTeal
```

## Components

### User Interface

Streamlit chat entry point and presentation layer.

- [Streamlit UI](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/ui/streamlit_app.py): streamlit app · Chat interface that collects input, uploads, and displays answers and sources. · `app/ui/streamlit_app.py`

### Chat Orchestration

Supervisor graph, shared state, and agent routing.

- [Main Graph](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/graph.py): langgraph workflow · Top-level orchestration workflow connecting the supervisor to specialized branches. · `app/graph.py`
- [Chat State](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/core/state.py): shared state · Central conversational state passed through the graph and agents. · `app/core/state.py`
- [LLM Setup](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/core/llm.py): model factory · Centralized creation and configuration of LLM instances. · `app/core/llm.py`
- [Supervisor](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/supervisor.py): router agent · Classifies each request and selects the next branch to run. · `app/agents/supervisor.py`

### Specialized Agents

Domain branches for legal, news, document QA, travel, and fallback.

- [Resmi Gazete](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/resmi_gazete_agent.py): rag agent · Answers Turkish official gazette questions using local retrieval. · `app/agents/resmi_gazete_agent.py`
- [News Agent](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/news_agent.py): search agent · Handles news and general knowledge queries using external sources. · `app/agents/news_agent.py`
- [Doc RAG](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/agentic_rag_agent.py): document qa agent · Answers questions over user-uploaded documents. · `app/agents/agentic_rag_agent.py`
- [Travel Bridge](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/travel_agent.py): workflow bridge · Hands travel requests into the dedicated planning subsystem. · `app/agents/travel_agent.py`
- [Fallback](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/agents/fallback_agent.py): fallback agent · Covers out-of-scope or unsupported requests. · `app/agents/fallback_agent.py`
- [External APIs](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/tools/external_apis.py): search tools · Live knowledge and search integrations used by the news branch. · `app/tools/external_apis.py`

### Travel Subsystem

Nested planning workflow with its own agents, tools, and PDF output.

- [Travel Workflow](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/workflow.py): subworkflow · Separate trip-planning workflow with its own agents and tools. · `app/travel_system/workflow.py`
- [Destination Agent](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/agents/destination_agent.py): planning agent · Researches destinations and destination-specific context. · `app/travel_system/agents/destination_agent.py`
- [Date & Budget](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/agents/date_budget_agent.py): planning agent · Reasons about timing and budget constraints for the trip. · `app/travel_system/agents/date_budget_agent.py`
- [Trip Coordinator](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/agents/coordinator_agent.py): composition agent · Combines travel sub-results into the final itinerary plan. · `app/travel_system/agents/coordinator_agent.py`
- [PDF Saver](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/travel_system/utils/pdf_saver.py): pdf output · Writes itinerary PDFs for travel plans. · `app/travel_system/utils/pdf_saver.py`

### Retrieval Data

Persistent vector store and processed corpora used by RAG branches.

- [RAG Tools](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/tools/rag_tools.py): retrieval tools · Retrieval and context formatting helpers for the Resmi Gazete path. · `app/tools/rag_tools.py`
- [Vector Store](https://github.com/ogulcanakca/agentic-chatbot/blob/main/app/storage/database.py): chroma db · Persistent Chroma-backed storage for embeddings and retrieved chunks. · `app/storage/database.py`
- [Embeddings](https://github.com/ogulcanakca/agentic-chatbot/tree/main/data/embeddings): vector files · Prebuilt embedding store used by local retrieval paths. · `data/embeddings`

### Data Prep

Offline scripts that fetch, process, and embed source content.

- [Raw Data](https://github.com/ogulcanakca/agentic-chatbot/tree/main/data/raw): source corpora · Fetched source content for news and Resmi Gazete. · `data/raw`
- [Processed Data](https://github.com/ogulcanakca/agentic-chatbot/tree/main/data/processed): chunked corpora · Structured JSONL corpora prepared for embedding and retrieval. · `data/processed`
- [Fetchers](https://github.com/ogulcanakca/agentic-chatbot/blob/main/scripts/news_fetcher.py): ingest scripts · Source ingestion scripts for news and official gazette content. · `scripts/news_fetcher.py`
- [Process Data](https://github.com/ogulcanakca/agentic-chatbot/blob/main/scripts/process_data.py): prep script · Transforms raw source files into structured processed corpora. · `scripts/process_data.py`
- [Build Embeddings](https://github.com/ogulcanakca/agentic-chatbot/blob/main/scripts/generate_embeddings.py): prep script · Generates vector embeddings from processed data. · `scripts/generate_embeddings.py`

### Configuration

Runtime and API settings.

- [Agent Config](https://github.com/ogulcanakca/agentic-chatbot/blob/main/configs/agent_config.py): settings · Agent and orchestration configuration. · `configs/agent_config.py`
- [App Config](https://github.com/ogulcanakca/agentic-chatbot/blob/main/configs/app_config.py): settings · Application-level runtime settings. · `configs/app_config.py`
- [API Config](https://github.com/ogulcanakca/agentic-chatbot/blob/main/configs/api_config.py): settings · External service and API settings. · `configs/api_config.py`

### Outputs & Assets

Generated plans and font assets for rendering.

- [Plans](https://github.com/ogulcanakca/agentic-chatbot/tree/main/plans): generated outputs · Saved travel plan PDFs. · `plans`
- [Fonts](https://github.com/ogulcanakca/agentic-chatbot/tree/main/fonts): render assets · Font assets used for PDF generation. · `fonts`

## Connections

- Streamlit UI → Main Graph: submit chat · User input and uploads are handed to the orchestration graph.
- Main Graph → Supervisor: route request · The main graph begins by invoking the supervisor router.
- Supervisor → Resmi Gazete: official text · Routes legal/government queries to the Resmi Gazete branch.
- Supervisor → News Agent: news / knowledge · Routes live information and general knowledge queries to the news branch.
- Supervisor → Doc RAG: uploaded docs · Routes document questions to the uploaded-document RAG branch.
- Supervisor → Travel Bridge: travel request · Routes trip-planning requests into the travel subsystem.
- Supervisor → Fallback: out of scope · Uses fallback handling when no specialized branch fits.
- Main Graph → Chat State: store state · The workflow reads and updates shared conversation state.
- Main Graph → LLM Setup: instantiate model · Branches use the centralized model setup.
- Resmi Gazete → RAG Tools: retrieve context · Resmi Gazete questions pull context through retrieval helpers.
- RAG Tools → Vector Store: query vectors · Retrieval helpers access the persistent vector store.
- Vector Store → Embeddings: load embeddings · The database layer serves prebuilt vector data from disk.
- News Agent → External APIs: search tools · News/general knowledge answers rely on external search and knowledge tools.
- Doc RAG → Vector Store: local retrieval · Uploaded-document QA also queries the shared vector store boundary.
- Travel Bridge → Travel Workflow: invoke subworkflow · Travel requests are delegated to the dedicated planning workflow.
- Travel Workflow → Destination Agent: destination stage · The travel workflow runs destination research first.
- Travel Workflow → Date & Budget: constraint stage · It reasons over dates and budget constraints.
- Travel Workflow → Trip Coordinator: compose plan · The coordinator assembles the final travel itinerary.
- Trip Coordinator → PDF Saver: export PDF · Final plans can be rendered to a PDF file.
- PDF Saver → Plans: save plan · Generated itineraries are written to the plans directory.
- PDF Saver → Fonts: use fonts · PDF rendering depends on packaged font assets.
- Fetchers → Raw Data: fetch source · Ingestion scripts populate the raw corpora directories.
- Process Data → Raw Data: read raw · Processing reads from fetched raw content.
- Process Data → Processed Data: write chunks · Processed JSONL corpora are written for later embedding.
- Build Embeddings → Processed Data: read processed · Embedding generation consumes processed corpora.
- Build Embeddings → Embeddings: write vectors · Generated embeddings are stored under the vector data directory.
- Streamlit UI → App Config: runtime settings · The UI boundary is shaped by application configuration.
- Supervisor → Agent Config: agent rules · Routing and agent behavior are driven by agent configuration.
- News Agent → API Config: api settings · External search integrations are configured via API settings.