# gladysdeepak/scholarship-buddy architecture

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

- Interactive diagram: https://gitdiagram.com/gladysdeepak/scholarship-buddy
- Repository: https://github.com/gladysdeepak/scholarship-buddy

## Overview

Scholarship Buddy helps Indian students explore schemes, create a profile, check eligibility deterministically, and get application guidance. The principal flow runs from the Next.js experience through scholarship APIs and persisted scheme data to rule matching and personalized results; separate branches provide evidence-grounded chat, document advice, SOP drafting, and proactive monitoring. RAG ingestion and retrieval form an internal knowledge layer. Relationships below are limited to README statements and shown imports/calls; some unsampled UI/API connections are documented but not directly evidenced in excerpts.

Main entry points: [`backend/app/rag/pipeline.py`](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/pipeline.py) (RAG ingestion and search), [`backend/app/main.py`](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/tools/tool_registry.py`](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/tools/tool_registry.py) (Agent tools), [`backend/app/routers/scholarships.py`](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/routers/scholarships.py) (Scholarship endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student experience"]
  node_web["Student portal"]
  node_profile["Profile state<br/>[ProfileContext.tsx]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["Application API"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_scholarship_routes["Scholarship endpoints<br/>[scholarships.py]"]
  node_chat_routes["Chat and SOP endpoints<br/>[chat.py]"]
  node_schemas["Domain schemas<br/>[schema.py]"]
  node_database[("Scholarship and student store<br/>[database.py]")]
end

subgraph group_matching["Scholarship matching"]
  node_seed_data["Seeded schemes"]
  node_rule_engine["Eligibility rules"]
end

subgraph group_guidance["AI guidance"]
  node_llm_agent["Summary and document advisor<br/>[llm_agent.py]"]
  node_orchestrator["Chat workflow router<br/>[orchestrator.py]"]
  node_query_agent["Scholarship Q&amp;A<br/>[query_agent.py]"]
  node_eligibility_agent["Eligibility explanation"]
  node_document_agent["Document advice<br/>[document_agent.py]"]
  node_sop_agent["SOP drafting<br/>[sop_agent.py]"]
end

subgraph group_knowledge["Knowledge and monitoring"]
  node_monitor["Scholarship monitor<br/>[monitor_agent.py]"]
  node_tool_registry["Agent tools<br/>[tool_registry.py]"]
  node_rag_pipeline["RAG ingestion and search<br/>[pipeline.py]"]
  node_document_loader["Content loader<br/>[document_loader.py]"]
  node_chunker["Document chunker<br/>[chunker.py]"]
  node_embedder["Embedding provider<br/>[embedder.py]"]
  node_vector_store[("Vector index<br/>[vector_store.py]")]
end

node_student(("Student"))

node_student -->|"uses"| node_web
node_web -.->|"updates"| node_profile
node_web -.->|"requests"| node_api_client
node_api_client -.->|"calls API"| node_api_entry
node_api_entry -->|"registers"| node_scholarship_routes
node_api_entry -->|"registers"| node_chat_routes
node_api_entry -->|"creates schema"| node_database
node_api_entry -->|"loads schemes"| node_seed_data
node_api_entry -->|"starts scheduler"| node_monitor
node_api_entry -->|"optionally indexes"| node_rag_pipeline
node_scholarship_routes -->|"reads and writes"| node_database
node_scholarship_routes -->|"evaluates profile"| node_rule_engine
node_scholarship_routes -->|"builds guidance"| node_llm_agent
node_scholarship_routes -->|"uses models"| node_schemas
node_database -.->|"persists records"| node_schemas
node_seed_data -->|"defines schemes"| node_schemas
node_rule_engine -->|"produces matches"| node_schemas
node_llm_agent -->|"returns guidance"| node_schemas
node_chat_routes -->|"dispatches chat"| node_orchestrator
node_chat_routes -->|"dispatches SOP"| node_sop_agent
node_orchestrator -->|"routes queries"| node_query_agent
node_orchestrator -->|"routes eligibility"| node_eligibility_agent
node_orchestrator -->|"routes documents"| node_document_agent
node_query_agent -->|"searches with"| node_tool_registry
node_query_agent -->|"retrieves evidence"| node_rag_pipeline
node_eligibility_agent -->|"uses tools"| node_tool_registry
node_document_agent -->|"retrieves context"| node_rag_pipeline
node_sop_agent -->|"uses tools"| node_tool_registry
node_monitor -->|"flags notifications"| node_tool_registry
node_tool_registry -->|"reads and writes"| node_database
node_tool_registry -->|"runs matching"| node_rule_engine
node_tool_registry -->|"searches index"| node_rag_pipeline
node_rag_pipeline -->|"loads content"| node_document_loader
node_rag_pipeline -->|"splits content"| node_chunker
node_rag_pipeline -->|"creates embeddings"| node_embedder
node_rag_pipeline -->|"indexes and searches"| node_vector_store

click node_web "https://github.com/gladysdeepak/scholarship-buddy/tree/main/frontend/src/app"
click node_profile "https://github.com/gladysdeepak/scholarship-buddy/blob/main/frontend/src/context/ProfileContext.tsx"
click node_api_client "https://github.com/gladysdeepak/scholarship-buddy/blob/main/frontend/src/lib/api.ts"
click node_api_entry "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/main.py"
click node_scholarship_routes "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/routers/scholarships.py"
click node_chat_routes "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/routers/chat.py"
click node_schemas "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/models/schema.py"
click node_database "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/models/database.py"
click node_seed_data "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/data/scholarship_seed.py"
click node_rule_engine "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/engine/eligibility_engine.py"
click node_llm_agent "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agent/llm_agent.py"
click node_orchestrator "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/orchestrator.py"
click node_query_agent "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/query_agent.py"
click node_eligibility_agent "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/eligibility_agent.py"
click node_document_agent "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/document_agent.py"
click node_sop_agent "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/sop_agent.py"
click node_monitor "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/monitor_agent.py"
click node_tool_registry "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/tools/tool_registry.py"
click node_rag_pipeline "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/pipeline.py"
click node_document_loader "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/document_loader.py"
click node_chunker "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/chunker.py"
click node_embedder "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/embedder.py"
click node_vector_store "https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/vector_store.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_web,node_profile,node_api_client toneBlue
class node_api_entry,node_scholarship_routes,node_chat_routes,node_schemas,node_database toneAmber
class node_seed_data,node_rule_engine toneMint
class node_llm_agent,node_orchestrator,node_query_agent,node_eligibility_agent,node_document_agent,node_sop_agent toneRose
class node_monitor,node_tool_registry,node_rag_pipeline,node_document_loader,node_chunker,node_embedder,node_vector_store,node_student toneIndigo
```

## Components

### Student experience

- [Student portal](https://github.com/gladysdeepak/scholarship-buddy/tree/main/frontend/src/app): `frontend/src/app`
- [Profile state](https://github.com/gladysdeepak/scholarship-buddy/blob/main/frontend/src/context/ProfileContext.tsx): `frontend/src/context/ProfileContext.tsx`
- [Frontend API client](https://github.com/gladysdeepak/scholarship-buddy/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Application API

- [FastAPI application](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/main.py): `backend/app/main.py`
- [Scholarship endpoints](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/routers/scholarships.py): `backend/app/routers/scholarships.py`
- [Chat and SOP endpoints](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [Domain schemas](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/models/schema.py): `backend/app/models/schema.py`
- [Scholarship and student store](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/models/database.py): `backend/app/models/database.py`

### Scholarship matching

- [Seeded schemes](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/data/scholarship_seed.py): `backend/app/data/scholarship_seed.py`
- [Eligibility rules](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/engine/eligibility_engine.py): `backend/app/engine/eligibility_engine.py`

### AI guidance

- [Summary and document advisor](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agent/llm_agent.py): `backend/app/agent/llm_agent.py`
- [Chat workflow router](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Scholarship Q&A](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/query_agent.py): `backend/app/agents/query_agent.py`
- [Eligibility explanation](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/eligibility_agent.py): `backend/app/agents/eligibility_agent.py`
- [Document advice](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/document_agent.py): `backend/app/agents/document_agent.py`
- [SOP drafting](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/sop_agent.py): `backend/app/agents/sop_agent.py`

### Knowledge and monitoring

- [Scholarship monitor](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/agents/monitor_agent.py): `backend/app/agents/monitor_agent.py`
- [Agent tools](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/tools/tool_registry.py): `backend/app/tools/tool_registry.py`
- [RAG ingestion and search](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/pipeline.py): `backend/app/rag/pipeline.py`
- [Content loader](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/document_loader.py): `backend/app/rag/document_loader.py`
- [Document chunker](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/chunker.py): `backend/app/rag/chunker.py`
- [Embedding provider](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/embedder.py): `backend/app/rag/embedder.py`
- [Vector index](https://github.com/gladysdeepak/scholarship-buddy/blob/main/backend/app/rag/vector_store.py): `backend/app/rag/vector_store.py`

### Other components

- **Student**

## Connections

- Student → Student portal: uses
- Student portal → Profile state: updates
- Student portal → Frontend API client: requests
- Frontend API client → FastAPI application: calls API
- FastAPI application → Scholarship endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Chat and SOP endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI application → Scholarship and student store: creates schema (evidence: `backend/app/main.py`)
- FastAPI application → Seeded schemes: loads schemes (evidence: `backend/app/main.py`)
- FastAPI application → Scholarship monitor: starts scheduler (evidence: `backend/app/main.py`)
- FastAPI application → RAG ingestion and search: optionally indexes (evidence: `backend/app/main.py`)
- Scholarship endpoints → Scholarship and student store: reads and writes (evidence: `backend/app/routers/scholarships.py`)
- Scholarship endpoints → Eligibility rules: evaluates profile (evidence: `backend/app/routers/scholarships.py`)
- Scholarship endpoints → Summary and document advisor: builds guidance (evidence: `backend/app/routers/scholarships.py`)
- Scholarship endpoints → Domain schemas: uses models (evidence: `backend/app/routers/scholarships.py`)
- Scholarship and student store → Domain schemas: persists records
- Seeded schemes → Domain schemas: defines schemes (evidence: `backend/app/data/scholarship_seed.py`)
- Eligibility rules → Domain schemas: produces matches (evidence: `backend/app/engine/eligibility_engine.py`)
- Summary and document advisor → Domain schemas: returns guidance (evidence: `backend/app/agent/llm_agent.py`)
- Chat and SOP endpoints → Chat workflow router: dispatches chat (evidence: `backend/app/routers/chat.py`)
- Chat and SOP endpoints → SOP drafting: dispatches SOP (evidence: `backend/app/routers/chat.py`)
- Chat workflow router → Scholarship Q&A: routes queries (evidence: `backend/app/agents/orchestrator.py`)
- Chat workflow router → Eligibility explanation: routes eligibility (evidence: `backend/app/agents/orchestrator.py`)
- Chat workflow router → Document advice: routes documents (evidence: `backend/app/agents/orchestrator.py`)
- Scholarship Q&A → Agent tools: searches with (evidence: `backend/app/agents/query_agent.py`)
- Scholarship Q&A → RAG ingestion and search: retrieves evidence
- Eligibility explanation → Agent tools: uses tools (evidence: `backend/app/agents/eligibility_agent.py`)
- Document advice → RAG ingestion and search: retrieves context (evidence: `backend/app/agents/document_agent.py`)
- SOP drafting → Agent tools: uses tools (evidence: `backend/app/agents/sop_agent.py`)
- Scholarship monitor → Agent tools: flags notifications (evidence: `backend/app/agents/monitor_agent.py`)
- Agent tools → Scholarship and student store: reads and writes (evidence: `backend/app/tools/tool_registry.py`)
- Agent tools → Eligibility rules: runs matching (evidence: `backend/app/tools/tool_registry.py`)
- Agent tools → RAG ingestion and search: searches index (evidence: `backend/app/tools/tool_registry.py`)
- RAG ingestion and search → Content loader: loads content (evidence: `backend/app/rag/pipeline.py`)
- RAG ingestion and search → Document chunker: splits content (evidence: `backend/app/rag/pipeline.py`)
- RAG ingestion and search → Embedding provider: creates embeddings (evidence: `backend/app/rag/pipeline.py`)
- RAG ingestion and search → Vector index: indexes and searches (evidence: `backend/app/rag/pipeline.py`)