# syed-waleed-hussain/knowledgepilot-ai architecture

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

- Interactive diagram: https://gitdiagram.com/syed-waleed-hussain/knowledgepilot-ai
- Repository: https://github.com/syed-waleed-hussain/knowledgepilot-ai

## Overview

KnowledgePilot AI is a local course-PDF study workspace with a separate research workflow. The principal study path is course/document management, PDF ingestion and retrieval, then evidence-grounded chat answers with references; users reach it through the React app and authenticated API. Research adds topic discovery, paper saving and notes, and AI analysis. Edges use the README, source-index references, or excerpts; unsampled implementation details are omitted or shown only as unverified links.

Main entry points: [`backend/app.py`](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/app.py) (FastAPI routes), [`frontend/src/App.jsx`](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/App.jsx) (React application), [`backend/agent_harness.py`](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/agent_harness.py) (Chat workflow), [`backend/research_graph.py`](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_graph.py) (Paper discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web workspace"]
  node_frontend["React application<br/>[App.jsx]"]
  node_coursepages["Course pages<br/>[Workspace.jsx]"]
  node_researchpage["Research page<br/>[Research.jsx]"]
  node_frontendapi["API client<br/>[api.js]"]
  node_authclient["Auth client<br/>[auth.js]"]
  node_answerdisplay["Answer display<br/>[MarkdownAnswer.jsx]"]
  node_researchpdf["PDF report export<br/>[researchPdf.js]"]
end

subgraph group_study["Course study"]
  node_api["FastAPI routes<br/>[app.py]"]
  node_ingest["PDF ingestion<br/>[pdf_processor.py]"]
  node_retrieval["Vector retrieval<br/>[rag_engine.py]"]
  node_chatflow["Chat workflow<br/>[agent_harness.py]"]
  node_answergen["Answer generation<br/>[llm_service.py]"]
  node_infographic["Infographics<br/>[infographic.py]"]
end

subgraph group_research["Research workspace"]
  node_researchapi["Research routes<br/>[research_api.py]"]
  node_discovery["Paper discovery<br/>[research_graph.py]"]
  node_providers["Research providers"]
  node_quality["Research quality"]
  node_researchdata["Research records<br/>[research_store.py]"]
end

subgraph group_data["Local data"]
  node_courses[("Course and chat data<br/>[course_store.py]")]
end

subgraph group_integrations["External services"]
  node_auth["Supabase auth<br/>[supabase_auth.py]"]
  node_groq{{"Groq LLM"}}
  node_supabase{{"Supabase"}}
  node_researchservices{{"Public paper APIs"}}
end

node_student(("Student"))

node_student -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_coursepages
node_frontend -->|"routes to"| node_researchpage
node_frontend -->|"restores session"| node_authclient
node_coursepages -->|"requests data"| node_frontendapi
node_researchpage -->|"renders answers"| node_answerdisplay
node_researchpage -->|"exports reports"| node_researchpdf
node_frontendapi -.->|"calls API"| node_api
node_authclient -.->|"authenticates"| node_supabase
node_api -->|"reads and writes"| node_courses
node_api -->|"processes PDFs"| node_ingest
node_api -->|"retrieves evidence"| node_retrieval
node_api -->|"handles chat"| node_chatflow
node_chatflow -->|"loads records"| node_courses
node_chatflow -.->|"retrieves evidence"| node_retrieval
node_chatflow -.->|"generates answer"| node_answergen
node_answergen -->|"requests completion"| node_groq
node_api -->|"serves infographic"| node_infographic
node_api -->|"checks identity"| node_auth
node_auth -->|"verifies user"| node_supabase
node_api -->|"mounts routes"| node_researchapi
node_researchapi -->|"invokes discovery"| node_discovery
node_researchapi -->|"stores research"| node_researchdata
node_discovery -->|"searches providers"| node_providers
node_discovery -->|"loads records"| node_researchdata
node_discovery -->|"checks quality"| node_quality
node_providers -->|"uses SQLite"| node_courses
node_providers -->|"searches papers"| node_researchservices
node_researchdata -->|"persists records"| node_courses

click node_frontend "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/App.jsx"
click node_coursepages "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/pages/Workspace.jsx"
click node_researchpage "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/pages/Research.jsx"
click node_frontendapi "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/services/api.js"
click node_authclient "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/services/auth.js"
click node_answerdisplay "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/components/MarkdownAnswer.jsx"
click node_researchpdf "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/services/researchPdf.js"
click node_api "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/app.py"
click node_ingest "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/pdf_processor.py"
click node_retrieval "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/rag_engine.py"
click node_chatflow "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/agent_harness.py"
click node_answergen "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/llm_service.py"
click node_infographic "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/infographic.py"
click node_researchapi "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_api.py"
click node_discovery "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_graph.py"
click node_providers "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_providers.py"
click node_quality "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_quality.py"
click node_researchdata "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_store.py"
click node_courses "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/course_store.py"
click node_auth "https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/supabase_auth.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_frontend,node_coursepages,node_researchpage,node_frontendapi,node_authclient,node_answerdisplay,node_researchpdf toneBlue
class node_api,node_ingest,node_retrieval,node_chatflow,node_answergen,node_infographic toneAmber
class node_researchapi,node_discovery,node_providers,node_quality,node_researchdata toneMint
class node_courses toneRose
class node_auth,node_groq,node_supabase,node_researchservices,node_student toneIndigo
```

## Components

### Web workspace

- [React application](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Course pages](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/pages/Workspace.jsx): `frontend/src/pages/Workspace.jsx`
- [Research page](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/pages/Research.jsx): `frontend/src/pages/Research.jsx`
- [API client](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Auth client](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/services/auth.js): `frontend/src/services/auth.js`
- [Answer display](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/components/MarkdownAnswer.jsx): `frontend/src/components/MarkdownAnswer.jsx`
- [PDF report export](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/frontend/src/services/researchPdf.js): `frontend/src/services/researchPdf.js`

### Course study

- [FastAPI routes](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/app.py): `backend/app.py`
- [PDF ingestion](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/pdf_processor.py): `pdf_processor.py`
- [Vector retrieval](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/rag_engine.py): `rag_engine.py`
- [Chat workflow](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/agent_harness.py): `backend/agent_harness.py`
- [Answer generation](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/llm_service.py): `llm_service.py`
- [Infographics](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/infographic.py): `backend/infographic.py`

### Research workspace

- [Research routes](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_api.py): `backend/research_api.py`
- [Paper discovery](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_graph.py): `backend/research_graph.py`
- [Research providers](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_providers.py): `backend/research_providers.py`
- [Research quality](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_quality.py): `backend/research_quality.py`
- [Research records](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/research_store.py): `backend/research_store.py`

### Local data

- [Course and chat data](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/course_store.py): `backend/course_store.py`

### External services

- [Supabase auth](https://github.com/syed-waleed-hussain/knowledgepilot-ai/blob/main/backend/supabase_auth.py): `backend/supabase_auth.py`
- **Groq LLM**
- **Supabase**
- **Public paper APIs**

### Other components

- **Student**

## Connections

- Student → React application: uses (evidence: `README.md`)
- React application → Course pages: routes to (evidence: `frontend/src/App.jsx`)
- React application → Research page: routes to (evidence: `frontend/src/App.jsx`)
- React application → Auth client: restores session (evidence: `frontend/src/App.jsx`)
- Course pages → API client: requests data (evidence: `frontend/src/pages/Workspace.jsx`)
- Research page → Answer display: renders answers (evidence: `frontend/src/pages/Research.jsx`)
- Research page → PDF report export: exports reports (evidence: `frontend/src/pages/Research.jsx`)
- API client → FastAPI routes: calls API
- Auth client → Supabase: authenticates
- FastAPI routes → Course and chat data: reads and writes (evidence: `backend/app.py`)
- FastAPI routes → PDF ingestion: processes PDFs (evidence: `backend/app.py`)
- FastAPI routes → Vector retrieval: retrieves evidence (evidence: `backend/app.py`)
- FastAPI routes → Chat workflow: handles chat (evidence: `backend/app.py`)
- Chat workflow → Course and chat data: loads records (evidence: `backend/agent_harness.py`)
- Chat workflow → Vector retrieval: retrieves evidence
- Chat workflow → Answer generation: generates answer (evidence: `README.md`)
- Answer generation → Groq LLM: requests completion (evidence: `llm_service.py`)
- FastAPI routes → Infographics: serves infographic (evidence: `backend/app.py`)
- FastAPI routes → Supabase auth: checks identity (evidence: `backend/app.py`)
- Supabase auth → Supabase: verifies user (evidence: `backend/supabase_auth.py`)
- FastAPI routes → Research routes: mounts routes (evidence: `backend/app.py`)
- Research routes → Paper discovery: invokes discovery (evidence: `backend/research_api.py`)
- Research routes → Research records: stores research (evidence: `backend/research_api.py`)
- Paper discovery → Research providers: searches providers (evidence: `backend/research_graph.py`)
- Paper discovery → Research records: loads records (evidence: `backend/research_graph.py`)
- Paper discovery → Research quality: checks quality (evidence: `backend/research_graph.py`)
- Research providers → Course and chat data: uses SQLite (evidence: `backend/research_providers.py`)
- Research providers → Public paper APIs: searches papers (evidence: `backend/research_providers.py`)
- Research records → Course and chat data: persists records (evidence: `backend/research_store.py`)
