# dieppdiepp/scholarshiprouting architecture

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

- Interactive diagram: https://gitdiagram.com/dieppdiepp/scholarshiprouting
- Repository: https://github.com/dieppdiepp/scholarshiprouting

## Overview

Scholarship Routing aggregates scholarship information, supports filtered discovery and detailed search, and offers AI consultation and application tracking. The user-facing workflow enters the FastAPI server, which exposes search and other service routes; search uses Elasticsearch. A separate collection workflow researches scholarship names and produces structured reports, while two chatbot implementations provide complementary consultation and RAG paths. The graph preserves README capabilities whose internal implementation was not sampled; those links are omitted or marked unverified rather than inferred from filenames.

Main entry points: [`src/server/app.py`](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/app.py) (FastAPI Server), [`src/chatbot_thread1/main.py`](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/main.py) (Intent-and-Tool Chatbot), [`src/data_collection/main.py`](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/main.py) (Collection Runner), [`src/data_collection/agent/graph.py`](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/agent/graph.py) (Research Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_server["FastAPI Server<br/>[app.py]"]
  node_firestore_route["Firestore Route"]
  node_firestore_service["Firestore Service<br/>[firestore_svc.py]"]
  node_tracking["Application Tracking<br/>[user.py]"]
end

subgraph group_discovery["Scholarship Discovery"]
  node_search_route["Search Route<br/>[search.py]"]
  node_search_service["Elasticsearch Service<br/>[es_svc.py]"]
  node_search_index[("Scholarship Index")]
  node_structured_query["Structured Scholarship Query"]
  node_data_loader["Scholarship Data Loader<br/>[data_loader.py]"]
  node_semantic_search["Semantic Search<br/>[semantic_search.py]"]
end

subgraph group_chat["AI Consultation"]
  node_chat_route["Chatbot Route<br/>[chatbot.py]"]
  node_chatbot_agent["Scholarship Agent"]
  node_chatbot_entry["Chatbot Service Entry<br/>[main.py]"]
  node_chatbot_rag["RAG Query Router<br/>[query_router.py]"]
  node_rag_retriever["RAG Retriever<br/>[retriever.py]"]
  node_thread1_chat["Intent-and-Tool Chatbot<br/>[main.py]"]
  node_intent_router["Intent Router<br/>[intent_router.py]"]
  node_response_generator["Response Generator"]
  node_profile_advice["Profile-Based Advice"]
end

subgraph group_collection["Data Collection"]
  node_collection_entry["Collection Runner<br/>[main.py]"]
  node_research_graph["Research Graph<br/>[graph.py]"]
  node_research_nodes["Research Stages<br/>[nodes.py]"]
  node_research_tools["Web Research Tools<br/>[tools.py]"]
  node_research_prompts["Research Prompts<br/>[structuring.py]"]
  node_reports["Structured Reports<br/>[config.py]"]
end

node_student(("Student"))

node_student -->|"uses platform"| node_server
node_server -->|"mounts routes"| node_search_route
node_server -->|"mounts routes"| node_firestore_route
node_server -->|"mounts routes"| node_chat_route
node_server -->|"mounts routes"| node_tracking
node_search_route -->|"queries"| node_search_service
node_search_service -.->|"searches index"| node_search_index
node_firestore_route -->|"reads and writes"| node_firestore_service
node_chat_route -.->|"dispatches chat"| node_chatbot_entry
node_chatbot_entry -->|"invokes agent"| node_chatbot_agent
node_chatbot_rag -->|"routes retrieval"| node_rag_retriever
node_collection_entry -->|"runs agent"| node_research_graph
node_collection_entry -->|"creates tool"| node_research_tools
node_research_graph -->|"dispatches stages"| node_research_nodes
node_research_graph -->|"uses tools"| node_research_tools
node_research_nodes -->|"searches web"| node_research_tools
node_research_nodes -->|"uses prompts"| node_research_prompts
node_collection_entry -->|"writes reports"| node_reports
node_thread1_chat -->|"classifies intent"| node_intent_router
node_thread1_chat -->|"generates answer"| node_response_generator
node_thread1_chat -->|"runs search"| node_structured_query
node_thread1_chat -->|"runs search"| node_semantic_search
node_structured_query -->|"reads scholarship data"| node_data_loader
node_student -->|"finds scholarships"| node_search_route
node_student -->|"asks consultant"| node_chat_route
node_student -->|"tracks applications"| node_tracking
node_student -.->|"gets personalized advice"| node_profile_advice

click node_server "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/app.py"
click node_search_route "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/search.py"
click node_search_service "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/es_svc.py"
click node_firestore_route "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/firestore_routes.py"
click node_firestore_service "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/firestore_svc.py"
click node_chat_route "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/chatbot.py"
click node_chatbot_agent "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread1/core/agents/scholarship_agent.py"
click node_chatbot_entry "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread1/main.py"
click node_chatbot_rag "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread2/rag_pipeline/query_router.py"
click node_rag_retriever "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread2/rag_pipeline/retriever.py"
click node_collection_entry "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/main.py"
click node_research_graph "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/agent/graph.py"
click node_research_nodes "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/agent/nodes.py"
click node_research_tools "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/agent/tools.py"
click node_research_prompts "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/prompts/structuring.py"
click node_reports "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/config.py"
click node_thread1_chat "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/main.py"
click node_intent_router "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/modules/intent_router.py"
click node_response_generator "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/modules/response_generator.py"
click node_structured_query "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/tools/structured_query.py"
click node_data_loader "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/utils/data_loader.py"
click node_semantic_search "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/tools/semantic_search.py"
click node_profile_advice "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread1/core/tools/profile_retriever.py"
click node_tracking "https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/user.py"

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_server,node_firestore_route,node_firestore_service,node_tracking toneBlue
class node_search_route,node_search_service,node_search_index,node_structured_query,node_data_loader,node_semantic_search toneAmber
class node_chat_route,node_chatbot_agent,node_chatbot_entry,node_chatbot_rag,node_rag_retriever,node_thread1_chat,node_intent_router,node_response_generator,node_profile_advice toneMint
class node_collection_entry,node_research_graph,node_research_nodes,node_research_tools,node_research_prompts,node_reports toneRose
class node_student toneIndigo
```

## Components

### Application API

- [FastAPI Server](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/app.py): `src/server/app.py`
- [Firestore Route](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/firestore_routes.py): `src/server/routes/firestore_routes.py`
- [Firestore Service](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/firestore_svc.py): `src/server/services/firestore_svc.py`
- [Application Tracking](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/user.py): `src/server/routes/user.py`

### Scholarship Discovery

- [Search Route](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/search.py): `src/server/routes/search.py`
- [Elasticsearch Service](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/es_svc.py): `src/server/services/es_svc.py`
- **Scholarship Index**
- [Structured Scholarship Query](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/tools/structured_query.py): `src/chatbot_thread1/core/tools/structured_query.py`
- [Scholarship Data Loader](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/utils/data_loader.py): `src/chatbot_thread1/core/utils/data_loader.py`
- [Semantic Search](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/tools/semantic_search.py): `src/chatbot_thread1/core/tools/semantic_search.py`

### AI Consultation

- [Chatbot Route](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/routes/chatbot.py): `src/server/routes/chatbot.py`
- [Scholarship Agent](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread1/core/agents/scholarship_agent.py): `src/server/services/chatbot_thread1/core/agents/scholarship_agent.py`
- [Chatbot Service Entry](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread1/main.py): `src/server/services/chatbot_thread1/main.py`
- [RAG Query Router](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread2/rag_pipeline/query_router.py): `src/server/services/chatbot_thread2/rag_pipeline/query_router.py`
- [RAG Retriever](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread2/rag_pipeline/retriever.py): `src/server/services/chatbot_thread2/rag_pipeline/retriever.py`
- [Intent-and-Tool Chatbot](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/main.py): `src/chatbot_thread1/main.py`
- [Intent Router](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/modules/intent_router.py): `src/chatbot_thread1/core/modules/intent_router.py`
- [Response Generator](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/chatbot_thread1/core/modules/response_generator.py): `src/chatbot_thread1/core/modules/response_generator.py`
- [Profile-Based Advice](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/server/services/chatbot_thread1/core/tools/profile_retriever.py): `src/server/services/chatbot_thread1/core/tools/profile_retriever.py`

### Data Collection

- [Collection Runner](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/main.py): `src/data_collection/main.py`
- [Research Graph](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/agent/graph.py): `src/data_collection/agent/graph.py`
- [Research Stages](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/agent/nodes.py): `src/data_collection/agent/nodes.py`
- [Web Research Tools](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/agent/tools.py): `src/data_collection/agent/tools.py`
- [Research Prompts](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/prompts/structuring.py): `src/data_collection/prompts/structuring.py`
- [Structured Reports](https://github.com/dieppdiepp/scholarshiprouting/blob/main/src/data_collection/config.py): `src/data_collection/config.py`

### Other components

- **Student**

## Connections

- Student → FastAPI Server: uses platform
- FastAPI Server → Search Route: mounts routes (evidence: `src/server/app.py`)
- FastAPI Server → Firestore Route: mounts routes (evidence: `src/server/app.py`)
- FastAPI Server → Chatbot Route: mounts routes (evidence: `src/server/app.py`)
- FastAPI Server → Application Tracking: mounts routes (evidence: `src/server/app.py`)
- Search Route → Elasticsearch Service: queries (evidence: `src/server/routes/search.py`)
- Elasticsearch Service → Scholarship Index: searches index
- Firestore Route → Firestore Service: reads and writes (evidence: `src/server/routes/firestore_routes.py`)
- Chatbot Route → Chatbot Service Entry: dispatches chat
- Chatbot Service Entry → Scholarship Agent: invokes agent (evidence: `src/server/services/chatbot_thread1/main.py`)
- RAG Query Router → RAG Retriever: routes retrieval (evidence: `src/server/services/chatbot_thread2/rag_pipeline/query_router.py`)
- Collection Runner → Research Graph: runs agent (evidence: `src/data_collection/main.py`)
- Collection Runner → Web Research Tools: creates tool (evidence: `src/data_collection/main.py`)
- Research Graph → Research Stages: dispatches stages (evidence: `src/data_collection/agent/graph.py`)
- Research Graph → Web Research Tools: uses tools (evidence: `src/data_collection/agent/graph.py`)
- Research Stages → Web Research Tools: searches web (evidence: `src/data_collection/agent/nodes.py`)
- Research Stages → Research Prompts: uses prompts (evidence: `src/data_collection/agent/nodes.py`)
- Collection Runner → Structured Reports: writes reports (evidence: `src/data_collection/main.py`)
- Intent-and-Tool Chatbot → Intent Router: classifies intent (evidence: `src/chatbot_thread1/main.py`)
- Intent-and-Tool Chatbot → Response Generator: generates answer (evidence: `src/chatbot_thread1/main.py`)
- Intent-and-Tool Chatbot → Structured Scholarship Query: runs search (evidence: `src/chatbot_thread1/main.py`)
- Intent-and-Tool Chatbot → Semantic Search: runs search (evidence: `src/chatbot_thread1/main.py`)
- Structured Scholarship Query → Scholarship Data Loader: reads scholarship data (evidence: `src/chatbot_thread1/core/tools/structured_query.py`)
- Student → Search Route: finds scholarships
- Student → Chatbot Route: asks consultant
- Student → Application Tracking: tracks applications
- Student → Profile-Based Advice: gets personalized advice
